/tasks/{taskId}/actions

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.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Path Params
string
required

The task ID

Body Params
formOutput
object

The filled form, keyed by form element id. Required elements must be present; values are validated against the task's form definition and a failure leaves the task open, reporting per-element details that name both the element and its step. Elements hidden by a visibleIf condition are not required and must be omitted. A file element takes an array of ids of documents already created and linked to this task. A signature element takes the drawing as a PNG data URI ('data:image/png;base64,…'); the stored task keeps only the SHA-256 (hex) of the image. Omit the whole field when the task carries no form.

string
enum
required

Complete the open task. When the task carries a form, formOutput is validated against it; a failure leaves the task open. Terminal. Repeating a completion that already landed, with the same formOutput, returns the completed task unchanged (200); a different formOutput on a completed task is a 409. An approval task takes a decision; it can be decided by a person or an API key, never by an agent, and is cancelled (409) when the agent run no longer waits for it.

Allowed:
string
enum

Required for an approval task, rejected for every other kind. 'approved' lets the agent's planned action run, with the values of formOutput when given (the approver may edit the pre-filled form); 'denied' does not run it.

Allowed:
string
length ≤ 1000

Approval tasks only: why the approver decided this way. On a denial the agent reads it as the answer to its planned action.

string
length between 1 and 128

Idempotency id of this action, unique per tenant (a UUID is a good choice). Sending the same id again returns the original result with status duplicate instead of applying the action twice. Generated by the platform when omitted.

Responses

400

bad request - unknown action type, form output invalid, or a snooze end that is not in the future

401

unauthorized - missing or invalid credentials, or the caller lacks the TaskAction permission for this action type

403

forbidden - the task requires a human and the caller is not one, or an agent tried to decide an approval task (internalCode TASK_REQUIRES_HUMAN)

404

task not found

409

conflict - task is no longer open, or the agent run of an approval task no longer waits for the decision (the task was cancelled)

412

precondition failed - task is not skippable

503

the request ran out of time while an external validator was still running; the task was not completed, send it again

Language
Credentials
Header
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json