Skip to main content
POST
/
v1
/
hitl
/
approvals
/
{approval_id}
/
decide
Decide an approval request (approve / deny)
curl --request POST \
  --url https://api-sandbox.featherhq.com/v1/hitl/approvals/{approval_id}/decide \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "note": "<string>"
}
'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "organization_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "conversation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "conv_turn_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "node_id": "<string>",
  "subject_ref": "<string>",
  "approver_role": "<string>",
  "status": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "payload": {},
  "suspend_message": "<string>",
  "decision": "<string>",
  "decided_by": "<string>",
  "decided_at": "2023-11-07T05:31:56Z",
  "note": "<string>",
  "timeout_at": "2023-11-07T05:31:56Z",
  "resume_token": "<string>"
}

Authorizations

​
x-api-key
string
header
required

Path Parameters

​
approval_id
string<uuid>
required

Body

application/json

Body for the approve/deny mutation. The deciding actor comes from auth, not the body.

​
decision
enum<string>
required
Available options:
approve,
deny
​
note
string | null

Response

Successful Response

Full detail view of a single approval_requests row.

​
id
string<uuid>
required
​
organization_id
string<uuid>
required
​
conversation_id
string<uuid>
required
​
conv_turn_id
string<uuid> | null
required
​
node_id
string | null
required
​
subject_kind
enum<string>
required

What a suspended approval is gating — the caller-agnostic dispatch key.

The :class:ResumeDispatcher (HITL-03 §1) routes a recorded decision back to the right continuation by this value: a workflow ApprovalNode resumes an edge (WORKFLOW_NODE); a Policy/tool-level gate resumes a partial turn (TOOL_CALL). Persisted to a VARCHAR(20) — a StrEnum serializes to its string value, so it needs no migration.

Available options:
workflow_node,
tool_call
​
subject_ref
string
required
​
approver_role
string
required
​
status
string
required
​
created_at
string<date-time>
required
​
payload
Payload · object
​
suspend_message
string | null
​
decision
string | null
​
decided_by
string | null
​
decided_at
string<date-time> | null
​
note
string | null
​
timeout_at
string<date-time> | null
​
resume_token
string | null