API overview

The awaithumans server exposes a small REST API. Most users never touch it directly — the Python and TypeScript SDKs wrap every endpoint. This reference is for:

Operators debugging an issue
Building a non-SDK client (Go, Rust, etc.)
Wiring custom integrations

Base URL

http://localhost:3001/api      # dev
https://reviews.acme.com/api   # production

All endpoints under /api/. Static dashboard files live at /, /setup, etc. — those aren’t part of the REST API.

Authentication

Two auth modes: Admin bearer token — for agents / automation:

Authorization: Bearer <AWAITHUMANS_ADMIN_API_TOKEN>

Session cookie — for the dashboard (set by POST /api/auth/login):

Cookie: awaithumans_session=<signed-cookie-value>

Public endpoints (no auth required): /api/auth/*, /api/setup/*, /api/health, channel webhook receivers (/api/channels/slack/interactions, /api/channels/email/action/*, etc.) — these self-authenticate via signed payloads.

Content types

Request bodies: application/json (except channel webhooks, which use application/x-www-form-urlencoded per their respective vendor specs)
Response bodies: application/json

Error format

Every error response has the shape:

{
  "error_code": "TASK_NOT_FOUND",
  "message": "Task 'tsk_abc' not found.",
  "docs": "https://docs.awaithumans.dev/troubleshooting#task-not-found"
}

The error_code is stable across versions; the message and docs URL may change.

Status	Meaning
400	Malformed request body
401	Auth required or session invalid
403	Authenticated but not authorized (e.g. non-operator hitting admin endpoint)
404	Task / user / identity not found
409	Idempotency conflict, terminal state, or already-completed
410	Magic-link token already consumed
422	Validation error (schema mismatch, malformed config)
429	Rate limit hit
500	Server-side error (verifier provider unavailable, etc.)
502	Vendor outage (Slack, OpenAI, etc.)
503	Service not configured (e.g. Slack OAuth without credentials)

OpenAPI spec

Interactive OpenAPI docs at /api/docs (FastAPI’s Swagger UI). The raw spec is at /api/openapi.json. For SDK code-gen against your own clients:

curl http://localhost:3001/api/openapi.json > openapi.json
# Then feed to openapi-generator-cli or similar.

Rate limits

Endpoint	Limit	Window	Key
`POST /api/auth/login`	10 / 5min / IP	5 min	IP
`POST /api/auth/login`	20 / 5min / email	5 min	Email
`POST /api/setup/operator`	30 / 5min / IP	5 min	IP

No rate limit on task routes — the bearer token holder is implicitly trusted. If you need to rate-limit your own agent’s task creation, do it in your code (Stripe-style outbox pattern recommended).

Idempotency

Every POST /api/tasks carries a required idempotency_key. The contract is Stripe-style — same key returns the same task, regardless of status, for the lifetime of the row.

First call with a fresh key: the task is inserted and the response is 201 Created.
Subsequent calls with the same key: the existing task is returned with 201 Created plus an Idempotent-Replayed: true response header. Notifications (email / Slack) do NOT re-fire on replay — that would re-page the human for already-in-flight work.

Clients that need to distinguish a fresh creation from a replay read the header:

curl -i -X POST http://localhost:3001/api/tasks \
  -H "Authorization: Bearer $AWAITHUMANS_ADMIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"task":"Approve refund","idempotency_key":"refund-A-4721", ...}'

HTTP/1.1 201 Created
content-type: application/json
idempotent-replayed: true       ← present only on replay
...

Why the status stays 201 (instead of flipping to 200 on replay): strict HTTP semantics reserve 201 for newly-created resources, but Stripe — the model this contract is named after — keeps the original status code on replay and signals replay-vs-fresh via header. That convention breaks zero clients that check status == 201 for success while still being explicit for clients that care. To trigger a fresh task for the same logical event (e.g. retry a refund review after an earlier one was rejected), pass a distinct key — convention is to suffix: "refund-A-4721:retry-1".

Endpoints by resource

Tasks (admin / operator / assignee)

Method	Path	Description
`POST`	`/api/tasks`	Create a task. Admin / operator only.
`GET`	`/api/tasks`	List tasks. Operator: all. Assignee: scoped to own.
`GET`	`/api/tasks/{id}`	Get one task. Operator / admin / assignee.
`POST`	`/api/tasks/{id}/complete`	Submit response. Operator / admin / assignee.
`POST`	`/api/tasks/{id}/cancel`	Cancel. Operator / admin only.
`GET`	`/api/tasks/{id}/poll`	Long-poll until terminal. Operator / admin / assignee.
`GET`	`/api/tasks/{id}/audit`	Audit trail. Operator / admin only.
`DELETE`	`/api/tasks/{id}`	Hard delete. Operator / admin only.

Auth

Method	Path	Description
`POST`	`/api/auth/login`	Email + password → session cookie. Public.
`POST`	`/api/auth/logout`	Clear session cookie.
`GET`	`/api/auth/me`	Session introspection.

Setup (first-run bootstrap)

Method	Path	Description
`GET`	`/api/setup/status`	Is first-run setup needed?
`POST`	`/api/setup/operator`	Create first operator. One-shot.

Users (admin / operator)

Method	Path	Description
`GET`	`/api/users`	List directory users.
`POST`	`/api/users`	Create.
`GET`	`/api/users/{id}`	Get one.
`PATCH`	`/api/users/{id}`	Update.
`DELETE`	`/api/users/{id}`	Soft-delete (sets `active=false`).

Channels

Method	Path	Description
`POST`	`/api/channels/slack/interactions`	Slack webhook (signed).
`GET/POST`	`/api/channels/slack/oauth/*`	OAuth install flow.
`GET/POST`	`/api/channels/slack/installations*`	OAuth install CRUD (admin).
`GET/POST`	`/api/channels/email/identities*`	Sender identity CRUD (admin).
`GET/POST`	`/api/channels/email/action/{token}`	Magic-link action page (signed).

Stats

Method	Path	Description
`GET`	`/api/stats`	Task counts by status, completion rate, last 30d. Operator / admin.

Health

Method	Path	Description
`GET`	`/api/health`	Readiness probe. Public.

Cross-version stability

The /api/tasks/* shape is stable for v1.x — breaking changes are a v2 event.
Error codes (error_code field) are stable across all v0.x.
The dashboard and channel webhook routes are internal — third-party clients should NOT depend on their shapes.

Get started

Concepts

Adapters

Channels

AwaitVerify

Routing

Self-hosting

Integrations

SDK reference

API reference

Help

Community

Base URL

Authentication

Content types

Error format

OpenAPI spec

Rate limits

Idempotency

Endpoints by resource

Tasks (admin / operator / assignee)

Auth

Setup (first-run bootstrap)

Users (admin / operator)

Channels

Stats

Health

Cross-version stability

​Base URL

​Authentication

​Content types

​Error format

​OpenAPI spec

​Rate limits

​Idempotency

​Endpoints by resource

​Tasks (admin / operator / assignee)

​Auth

​Setup (first-run bootstrap)

​Users (admin / operator)

​Channels

​Stats

​Health

​Cross-version stability

Base URL

Authentication

Content types

Error format

OpenAPI spec

Rate limits

Idempotency

Endpoints by resource

Tasks (admin / operator / assignee)

Auth

Setup (first-run bootstrap)

Users (admin / operator)

Channels

Stats

Health

Cross-version stability