Skip to content

Decide Work Approval

POST
/work/approvals

Decide one Work approval as the key’s person. PERSONAL KEY ONLY. APPROVING EXECUTES THE ACTION.

approve and edit_and_approve release the action the card gates; it then runs, and can send mail, change records or spend credits. reject refuses it; dismiss clears the row and runs nothing. List what is waiting with GET /work/oversight (approvals).

This is the in-app button: the same function, so the same rules. Only the person the card belongs to (or a peer the card is shared with, for a plain yes or no) may decide it; only the owner may edit or redirect it; the decider’s permission on the action’s tool is checked at decide time; and the released action is held to the same guards as in the app (quiet hours, suppressions, send allowlists, spend caps). Anyone else gets that refusal unchanged (403 or 404). An organization or agency key gets 403: decide it in graph8. Idempotency-Key is required. The room announces the decision and the approval records who decided.

Authorizations

Parameters

Header Parameters

Idempotency-Key
required

REQUIRED. A retried decision replays the first answer and never decides or runs anything twice.

string
>= 1 characters <= 255 characters

REQUIRED. A retried decision replays the first answer and never decides or runs anything twice.

X-Target-Org-Id
Any of:
string

Request Body required

One decision on one approval — never who is making it.

extra="forbid" is the security property, not tidiness. The deciding actor and the organization are resolved from the authenticated session in work/router.py, and the idempotency key comes from the Idempotency-Key header. A client that sends decidedBy, actorId or orgId is told its field was refused rather than receiving a 200 for a decision recorded under somebody else’s name.

deny is accepted alongside reject because that is the word this surface has always used; work/approvals.py::canonical_decision folds them so only one spelling ever reaches agent_approvals.decision.

dismiss is a fourth terminal decision, not a synonym for any of the others: it clears the row off the queue without deciding it and runs nothing. It is accepted HERE rather than on POST /v1/agent/approvals/{id}/decide because this is the surface the Work pane’s queue posts to, and it is the one that would otherwise schedule a plan.

object
approvalId
required
string format: uuid
decision
required
string
Allowed values: approve deny reject edit_and_approve dismiss
editPayload
Any of:
object
key
additional properties
any
scope
Any of:
string
Allowed values: once always

Responses

200

Successful Response

object
data
required

A Work direct message, chat, approval decision, work item, question, rule set or suggestion list, as the app returns it.

object
key
additional properties
any
pagination
Any of:
object
has_next
required

Whether there are more pages

boolean
limit
required

Items per page

integer
next_cursor
Any of:
string
notes
Any of:
Array<string>
page
required

Current page number (1-indexed)

integer
total
required

Total number of items

integer
total_available
Any of:
integer
total_is_lower_bound
Any of:
boolean

422

Validation Error

object
detail
Array<object>
object
loc
required
Array
msg
required
string
type
required
string