Skip to navigation
Paperwork APIAgents

Complete a human step

View as Markdown

Marks one of the run’s executor: "human" steps done, which releases everything waiting on it.

{ "note": "Client signed; scan attached.", "files": ["file_01JQ8ZKMRT4V6WXYZ0ABCDEF"] }

Both fields are optional. files are ids you registered or that the run already holds; they are attached to the step and show up in the run’s output.files.

Only human steps are completable — an agent’s own step answers 422. A step whose dependencies are unfinished answers 409, and so does one that is already done. The response carries the step plus run.status; ?wait= holds the request while the run picks the work back up.

An API key has no person behind it, so the run records your organization’s key as the actor rather than a named individual.

Learn more: Agents guide

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

idstringRequired>=1 character
taskIdstringRequired>=1 character

Headers

idempotency-keystringOptional1-255 characters
Retries with the same key replay the first applied mutation.

Query parameters

waitintegerOptional0-120Defaults to 60

How many seconds to hold the request open. Releases early the moment the run finishes or blocks on a person. Maximum 120; 0 returns immediately.

Request

This endpoint expects an object.
notestringOptional<=2000 characters
What you did, recorded on the step and visible on the run.
fileslist of stringsOptional
Files produced while doing the step, by file id.

Response headers

idempotent-replaystringOptional

true when this response replays an earlier request.

Response

The completed step, and where the run stands after it.
object"agent_run_task"
idstring
titlestring
executorenum

Who performs the step: agent runs by itself, human waits for a person to complete it.

Allowed values:
statusenum
Allowed values:
summarystring or null
completedAtstring or null
runobject
notestringOptional

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
422
Unprocessable Entity Error
429
Too Many Requests Error