v1

latestOpenAPI 3.1.0raw.githubusercontent.com2026-06-304917042.1 MB

hitl

Decide an approval request (approve / deny)

post/v1/hitl/approvals/{approval_id}/decide

Path parameters

approval_idstring uuid required

Request body

decision'approve' | 'deny' required

notestring nullable

Response

Successful Response

idstring uuid required

organization_idstring uuid required

conversation_idstring uuid required

conv_turn_idstring uuid nullable required

node_idstring nullable required

subject_kind'workflow_node' | 'tool_call' 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.

subject_refstring required

payloadobject

suspend_messagestring nullable

approver_rolestring required

statusstring required

decisionstring nullable

decided_bystring nullable

decided_atstring date-time nullable

notestring nullable

timeout_atstring date-time nullable

resume_tokenstring nullable

created_atstring date-time required