Human Tasks
Read-only monitoring of durable workflow Human Tasks for external agents and API clients.
Endpoints for durable workflow Human Tasks under /api/v1/human-tasks. A Human Task is the
control-plane projection of a workflow run that has parked at an approval (Human Task) node: the
run's checkpoint and wait token remain the execution source of truth, and the task record models
lifecycle, assignment, work state, dates, and outcome.
Endpoints
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/human-tasks | List tasks the caller is authorized for |
| GET | /api/v1/human-tasks/{id} | Get one authorized task projection |
Both require a workspace-scoped bearer API key. Authorization is resolved against the key owner's current workspace membership and task eligibility at request time (KTD9): a revoked or cross-workspace principal sees no task, even for a task issued earlier.
Listing tasks
GET /api/v1/human-tasks accepts these optional query params:
| Param | Description |
|---|---|
filter | eligible | mine | unassigned | open | due | overdue | completed |
runId | Restrict to tasks for one run |
limit | Max results, default 25, clamped 1–100 |
offset | Pagination offset; the response returns nextOffset (or null at the end) |
An unknown filter returns 400. The response is { tasks, nextOffset, links }, where links
maps each taskId to its detail path.
Task projection
Each task is a redacted summary. It never includes draft values, form contents, signal payloads, or resume secrets — only field presence flags and digestible metadata.
| Field | Meaning |
|---|---|
id | Task id |
workspaceId | Owning workspace |
workflowId, runId, nodeId | Linked workflow, run, and Human Task node |
taskType | Task kind (e.g. approval, form) |
lifecycleState | open | completed | canceled | expired |
workState | ready | started | paused (independent of lifecycle) |
priority | Task priority |
assigneeUserId | Current assignee, or null when unassigned |
eligibleRoles | Roles eligible to claim/complete |
outcomes | Named outcomes the completing human may select |
instructions | Reviewer instructions, or null |
dueAt, followUpAt, escalateAt | Due, follow-up, and escalation timestamps |
terminalOutcome | The winning outcome once terminal, else null |
hasFormSchema, hasFormDraft | Presence flags only — contents are never returned |
revision | Compare-and-set revision guarding concurrent transitions |
createdAt, updatedAt | Timestamps |
Lifecycle
Lifecycle is separate from assignment and work state. A task stays open while it is claimed,
reassigned, drafted, started, paused, reminded, or escalated; only a terminal transition consumes the
linked wait token exactly once:
completed— an eligible human selected a named outcome; the run resumes down that branch.canceled— the run or task was canceled.expired— a hard timeout elapsed; the run follows its configured timeout branch. An expired task is never silently treated as approval.
Reminders and escalations update task and audit state and notify the target, but they do not resume the run. When completion races a timeout or cancellation, one checkpoint compare-and-set wins and the loser receives a terminal conflict without a second resume.
Related
- Human-only session routes:
/api/human-tasks(claim, save draft, complete, reassign) and pending Agent tool confirmations at/api/human-tasks/agent-confirmations. - Recovery: see the durable Human Task recovery runbook.
Clearbit and Medium request confirmations
The original persisted run actor approves the exact materialized request while current workspace AND organization execution rights remain valid. The selected account revision/live policy, published node/version/input, original task ID AND wait token and winning execution lease remain bound through dispatch, success/failure settlement and freshly authenticated output. A replacement task with the same wait token is not the original consent. Rejecting or losing authority before claim sends no request; a used claim permits no automatic replay after timeout, disconnect or uncertain settlement. HTTP acceptance alone does not verify the business effect.
AWS Textract AnalyzeExpense (preview)
Textract approval belongs only to the original persisted run actor. The exact materialized request includes the complete base64 workspace image. Review the five separate acknowledgments and the selected account before approving; importing a node or saving an account supplies no consent. The signed request approval expires after fifteen minutes and does not change the ordinary task-list projection contract above.
On resume, current organization AND workspace rights, encrypted account revision, workflow/source/input, exact ready file content, original task ID/wait token/decision and current lease must still match. A changed file or account requires a new approval. One durable physical claim is consumed before sending; an uncertain paid result never permits automatic replay. Complete image requests and raw expense responses can remain in normal approval/execution history and reach downstream AI; no additional encryption or expiry is promised.
Execution requires both the deployment setting WORKFLOW_LIVE_NATIVE_TEXTRACT=true and the workspace live preference aws-textract. Real AWS requests and authenticated organization/workspace Review walkthroughs remain untested.
Español: AnalyzeExpense en vista previa
Solo el actor original persistido puede aprobar Textract. La solicitud exacta contiene la imagen completa del workspace en base64. Revisa las cinco confirmaciones separadas y la cuenta elegida antes de aprobar; importar o guardar una cuenta no concede consentimiento. La aprobación firmada caduca en quince minutos y no modifica la proyección ordinaria de la lista de tareas descrita arriba.
Al reanudar deben coincidir los permisos actuales de organización Y workspace, revisión de la cuenta cifrada, flujo/origen/entrada, contenido exacto del archivo listo, tarea/token de espera/decisión originales y lease vigente. Cambiar archivo o cuenta exige otra aprobación. Se consume un único intento durable antes del envío; un resultado facturable incierto nunca permite repetición automática. La imagen completa y los gastos sin procesar pueden permanecer en historial ordinario y llegar a IA posterior; no se promete cifrado adicional ni caducidad.
Se exige tanto WORKFLOW_LIVE_NATIVE_TEXTRACT=true en el despliegue como la preferencia real aws-textract del workspace. Siguen sin probarse las solicitudes reales AWS y los recorridos autenticados de organización y workspace en Review.