Return task to step

Endpoint

POST /bot/tasks/{task_id}/step-return

Returns a task to an earlier workflow step using an existing assignment from that step.

Auth

Authorization: Bearer <bot_token>
Content-Type: application/json

Path params

• task_id - task ID

Request body

{
  "assignment_id": 123
}

assignment_id must identify an assignment that belongs to this task and to a step before the task's current step.

Finding assignment_id

Call GET /bot/tasks/{task_id} and inspect data.step_assignments. The response includes assignments from current and previous steps. Select an earlier step's assignment_id; an assignment from the current or a later step is rejected.

See Read task for the complete assignment schema.

Example

curl -X POST \
  -H "Authorization: Bearer <bot_token>" \
  -H "Content-Type: application/json" \
  -d '{"assignment_id": 123}' \
  https://public-api.hcapp.ee/bot/tasks/5001/step-return

Response body

{
  "success": true,
  "error_message": null,
  "data": {
    "task_id": 5001,
    "previous_step_id": 8,
    "step_id": 5,
    "assignment_id": 123,
    "responsible_id": 45
  }
}

For a group assignment, responsible_id is null.

Behavior

• Changes the task to the assignment's workflow step.
• Marks the selected assignment as unconfirmed.
• Sets the assignment's user as the task responsible. For a group assignment, the task has no single responsible_id.
• Updates task activity time and creates a STEP_CHANGED system comment.
• Creates an in-app notification for the responsible user or group members.
• Queues external delivery through each recipient's enabled notification channels.

Errors

• 422 assignment_id must be greater than 0.
• 400 Task is not in a workflow step.
• 400 Target assignment must belong to an earlier step.
• 403 Form access not found.
• 404 Task not found.
• 404 Assignment with id {id} not found for this task.

The endpoint uses the standard bot update rate limit.