Apply one lifecycle action to an open task. The body is discriminated on type.
complete closes the task. When the task carries a form, formOutput is validated against it; a validation failure leaves the task open and the 400 response reports per-element details in issues, each naming the element and the step it belongs to. Elements hidden by a visibleIf condition are not required and must be omitted; sending a value for one is rejected. Documents referenced by a file element must already exist, be linked to this task, and have finished uploading. Any http-json validators configured on the form run last, once every other check has passed; a rejection or an unreachable endpoint leaves the task open. Tasks marked as requiring a human reject completion through this endpoint. When the task was created from a template with a documentTemplateId, a PDF is rendered from that document template asynchronously after completion and linked to the task and its referenced entity; subscribe to the document-link-action-created webhook (filter targetEntityType: "task") or list the task's documents to pick it up. The render never delays or fails the completion.
skip closes a task that was created as skippable; otherwise the request is rejected with 412. cancel closes a task that is no longer needed, e.g. one created in error. Both are terminal; the task and its history stay readable.
reassign moves the open task to another organization, team, or user scope.
snooze hides the task from the calling API key's default listings until until (epoch seconds). Snoozes are per actor: nobody else's listing changes, the task stays open, and a snooze never outlives the task's due date, so snoozing an overdue task has no visible effect. Pass includeSnoozed=true when listing to see snoozed tasks anyway. unsnooze ends the caller's snooze early and is a no-op without one.
set-notifications replaces the task's notification configuration (notifications, the same shape as on task creation); the task stays open. Not available to carrier or shipper users.
An approval task decides an autonomous agent's planned action. Its complete takes decision (approved or denied) and an optional reason. On approved, a formOutput with edited values makes the action run with the edited input, checked like the agent's own call (the tool's input rules and the agent's permissions); without formOutput it runs as planned. The agent run resumes once every approval task of its paused step is decided. An agent cannot decide an approval task (403). When the run no longer waits for the decision, the task is cancelled and the answer is 409. Cancelling an approval task cancels its run.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
400bad request - unknown action type, form output invalid, or a snooze end that is not in the future
401unauthorized - missing or invalid credentials, or the caller lacks the TaskAction permission for this action type
403forbidden - the task requires a human and the caller is not one, or an agent tried to decide an approval task (internalCode TASK_REQUIRES_HUMAN)
404task not found
409conflict - task is no longer open, or the agent run of an approval task no longer waits for the decision (the task was cancelled)
412precondition failed - task is not skippable
503the request ran out of time while an external validator was still running; the task was not completed, send it again
