Skip to main content
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.
StatusMeaning
400Malformed request body
401Auth required or session invalid
403Authenticated but not authorized (e.g. non-operator hitting admin endpoint)
404Task / user / identity not found
409Idempotency conflict, terminal state, or already-completed
410Magic-link token already consumed
422Validation error (schema mismatch, malformed config)
429Rate limit hit
500Server-side error (verifier provider unavailable, etc.)
502Vendor outage (Slack, OpenAI, etc.)
503Service 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

EndpointLimitWindowKey
POST /api/auth/login10 / 5min / IP5 minIP
POST /api/auth/login20 / 5min / email5 minEmail
POST /api/setup/operator30 / 5min / IP5 minIP
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)

MethodPathDescription
POST/api/tasksCreate a task. Admin / operator only.
GET/api/tasksList tasks. Operator: all. Assignee: scoped to own.
GET/api/tasks/{id}Get one task. Operator / admin / assignee.
POST/api/tasks/{id}/completeSubmit response. Operator / admin / assignee.
POST/api/tasks/{id}/cancelCancel. Operator / admin only.
GET/api/tasks/{id}/pollLong-poll until terminal. Operator / admin / assignee.
GET/api/tasks/{id}/auditAudit trail. Operator / admin only.
DELETE/api/tasks/{id}Hard delete. Operator / admin only.

​
Auth

MethodPathDescription
POST/api/auth/loginEmail + password → session cookie. Public.
POST/api/auth/logoutClear session cookie.
GET/api/auth/meSession introspection.

​
Setup (first-run bootstrap)

MethodPathDescription
GET/api/setup/statusIs first-run setup needed?
POST/api/setup/operatorCreate first operator. One-shot.

​
Users (admin / operator)

MethodPathDescription
GET/api/usersList directory users.
POST/api/usersCreate.
GET/api/users/{id}Get one.
PATCH/api/users/{id}Update.
DELETE/api/users/{id}Soft-delete (sets active=false).

​
Channels

MethodPathDescription
POST/api/channels/slack/interactionsSlack 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

MethodPathDescription
GET/api/statsTask counts by status, completion rate, last 30d. Operator / admin.

​
Health

MethodPathDescription
GET/api/healthReadiness 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.