Skip to navigation
Paperwork APIAgents

Approve or reject a step

View as Markdown

Answers a sign-off an agent run is waiting on, and lets the run carry on.

Read the outstanding ones from approvals[] on the run — each carries the step’s name, the files it touches and, for a before gate, the params it proposes.

{ "decision": "approve" }

Rejecting needs a reason. { "decision": "reject", "note": "Wrong signer." } — a rejection without a note is a 400.

Editing before you approve. Send params to replace the proposed inputs, files to replace the files the step works on (ids from POST /v1/files or the run’s own inputs). The two together must stay under 1 MiB.

The response carries the decision plus run.status, so you know whether the run moved on, finished, or is blocked on the next thing. ?wait= holds the request while the run picks the work back up, releasing early the moment it finishes or blocks again.

Deciding the same sign-off twice is a 409 — the first answer stands.

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
approvalIdstringRequired>=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.
decisionenumRequired

Approve to let the step run (or its result stand), reject to refuse it. A rejection needs a note.

Allowed values:
notestringOptional<=4000 characters
Why. Required on a rejection, recorded on the run either way.
paramsmap from strings to anyOptional
Replace the inputs proposed for the step before it runs.
fileslist of stringsOptional
Replace the files the step works on, by file id.

Response headers

idempotent-replaystringOptional

true when this response replays an earlier request.

Response

The decision, and where the run stands after it.
object"agent_run_approval"
idstring
kindenum
Allowed values:
actionstring
statusenum
Allowed values:
requestedAtstring
decidedAtstring or null
notestring or null
runobject

Errors

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