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, spend-limit changes.
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, 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) to thread a workflow across email + voice + vault + phone; the org audit log (/v1/orgs/{orgId}/audit-logs) captures it on every entry. 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 '{
    "agentId": "cm...",
    "to": ["user@example.com"],
    "subject": "Hello",
    "body": "From an agent."
  }'

POST/v1/voice/calls

Place an outbound conversational voice call. Runs Anima's hosted voice loop behind a server-side TCPA consent gate.

curl -X POST https://api.useanima.sh/v1/voice/calls \
  -H "Authorization: Bearer ak_..." \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "cm...",
    "to": "+14155550142",
    "greeting": "Hi, this is my Anima agent calling from its own number."
  }'

GET/v1/email

List an agent's email messages (inbound + outbound).

curl "https://api.useanima.sh/v1/email?limit=20" \
  -H "Authorization: Bearer ak_..."

GET/v1/orgs/{orgId}/audit-logs

Query the org's immutable audit log (master key).

curl "https://api.useanima.sh/v1/orgs/cm.../audit-logs?limit=50" \
  -H "Authorization: Bearer mk_..."

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.
/changelog — release notes and behavior-changing API updates.