API Reference

REST API. Versioned at https://api.useanima.sh/v1/.... Authentication via Bearer ak_*, mk_*, or sk_* tokens. Errors follow RFC 7807. Every billable write supports Idempotency-Key.

OpenAPI JSON Walkthrough docs

Authentication

Three key prefixes, all sent as Authorization: Bearer <key>:

ak_* — agent key. Scoped to one agent identity. Default for runtime.
mk_* — master key. Org-scoped admin. Required for billing settings, agent creation, hard-cap writes.
sk_* — service key. Server-to-server inside the platform; not issued to customers.

Idempotency-Key

Send Idempotency-Key: <your-uuid> on any POST/PUT/PATCH/ DELETE. We cache the response for 24 hours and replay on retry. Constraints:

1-255 ASCII printable characters.
Reuse with a different body or path → 409 IDEMPOTENCY_BODY_MISMATCH.
5xx responses are NOT cached — retries fall through to the handler.
Idempotent-Replayed: true response header tells you it was a cache hit.

Rate limits

Every response carries:

X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset — per-tier per-minute quotas.
X-RateLimit-Sec-Limit/Remaining/Reset — per-org per-second soft cap (100 req/sec on Free/Starter, 500 Growth, 2,000 Scale, 10,000 Enterprise).
429 includes Retry-After in seconds.

Errors (RFC 7807)

Errors are application/problem+json:

{
  "type": "https://docs.useanima.sh/errors/rate-limit",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit exceeded",
  "instance": "/v1/email/send",
  "code": "RATE_LIMIT",
  "details": { "limit": 60, "remaining": 0, "retryAfter": 12 }
}

The legacy error: { code, message, details } sibling stays through SDK v1.x for back-compat.

Correlation IDs

Every action returns x-correlation-id on the response. Pass the same value into subsequent calls (header or body field) and /v1/audit/events?correlation_id=... renders the full chain across email + voice + vault + phone. Inbound email gets a synthetic ID so reply chains link back to the trigger.

Distinct from x-request-id which is unique per HTTP call.

Most-used endpoints

POST/v1/email/send

Send an outbound email from an agent's mailbox.

curl -X POST https://api.useanima.sh/v1/email/send \
  -H "Authorization: Bearer ak_..." \
  -H "Idempotency-Key: send-1747-abc" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "subject": "Hello",
    "body": "From an agent."
  }'

POST/v1/voice/calls

Place an outbound voice call. TCPA + RND + time-of-day gates run server-side.

curl -X POST https://api.useanima.sh/v1/voice/calls \
  -H "Authorization: Bearer ak_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155550142",
    "tier": "basic",
    "metadata": { "consent_source": "business-relationship" }
  }'

GET/v1/audit/events?correlation_id=...

Fetch the full event chain for a workflow correlation ID.

curl https://api.useanima.sh/v1/audit/events?correlation_id=corr_abc \
  -H "Authorization: Bearer ak_..."

GET/v1/events/stream

Server-Sent Events stream of live agent activity. Backs `am tail`.

curl -N https://api.useanima.sh/v1/events/stream \
  -H "Authorization: Bearer ak_..."

POST/v1/agent/sign-up

Provision a fresh org + agent + inbox + ak_ key in one call.

curl -X POST https://api.useanima.sh/v1/agent/sign-up \
  -H "Content-Type: application/json" \
  -d '{
    "human_email": "you@example.com",
    "username": "shopping-agent"
  }'

Need more?

/docs — full walkthrough with SDK examples for TypeScript, Python, and Go.
/help/launch-day — operator runbook for the first 24 hours in production.
/changelog — release notes and behavior-changing API updates.