Skip to main content
Records the human’s response and transitions the task toward a terminal status. If a verifier is configured, this endpoint runs the LLM call inline before deciding the final status. The dashboard’s “Submit” button hits this endpoint. So do the Slack modal view_submission handler and the email magic-link confirmation page (each with their own auth shape — Slack signature, magic-link token).

​
Authorization

The assignee check is the security-critical bit — a non-operator can complete only their own assigned tasks.

​
Request

​
Response

The full task record (same shape as POST /api/tasks response). The status field reflects what happened:
  • completed — verifier passed (or no verifier). Final.
  • rejected — verifier rejected this attempt; the task is non-terminal, the human can resubmit.
  • verification_exhausted — verifier rejected, attempts exhausted. Final.
Inspect verifier_result.reason for the verifier’s explanation when rejected / verification_exhausted.

​
With verifier

If task.verifier_config is set:
  1. Server runs the LLM call inline (5–30s typical).
  2. Pass → status=completed, response saved, audit log records action=verified.
  3. Fail with attempts left → status=rejected, verification_attempt bumped, audit log records action=rejected + verifier_reason. The task stays open for resubmission.
  4. Fail with attempts exhausted → status=verification_exhausted (terminal), audit log records action=verification_exhausted.
Provider-level failures (vendor outage, missing API key, missing SDK extra) propagate as 5xx with typed error_code and DO NOT consume an attempt.

​
With redact_payload=True

The verifier is skipped entirely. The operator marked the payload sensitive; we don’t ship it to a third-party LLM. Status goes straight to completed.

​
Errors

Each error body has the typed error_code + docs URL.

​
Outbound webhook

If task.callback_url is set AND the task transitions to a terminal status, an HMAC-signed POST fires to the callback URL after the response is sent (FastAPI BackgroundTask — the human’s submit doesn’t wait on it). See Self-hosting → Security for the signature scheme.

​
SDK equivalent

The dashboard calls this directly from the form submission. From your own code:
For the typical agent loop (create + poll), use the SDK’s await_human().