API reference

Conventions

Base URL, authentication, request shape, errors, idempotency, and pagination.

Base URL

The API is served from a single host per environment.

Environment	Base URL
Staging	`https://staging-api-raven-cloud.autotribes.app`
Production	`https://api-raven-cloud.autotribes.app`

All endpoints are prefixed with /v1.

Authentication

There are two ways to authenticate, depending on whether you're acting as a service or a human.

API key (services)

For machine-to-machine calls — anything your back-end does on behalf of customers. Pass the key in the X-Raven-Key header:

bash

curl https://api-raven-cloud.autotribes.app/v1/messages \
  -H "X-Raven-Key: rk_live_a3f7b2c1_..."

API keys are tenant-scoped. The tenant is implied by the key — no X-Tenant-Slug header needed.

Bearer token (humans)

For dashboard and admin endpoints, authenticate with an a sign-in session token:

bash

curl https://api-raven-cloud.autotribes.app/v1/admin/me \
  -H "Authorization: Bearer eyJ..." \
  -H "X-App-Name: raven-cloud" \
  -H "X-Tenant-Slug: acme-co"

Bearer tokens come from our single sign-on — see Authentication. The X-Tenant-Slugheader tells us which of the user's tenants you're acting on (omit it for tenant-agnostic endpoints like /v1/admin/me).

Request and response shape

Every request is JSON. Every response is JSON. Timestamps are ISO 8601 with timezone (always UTC). IDs are UUIDv4.

Field names use camelCase in responses and accept camelCase or snake_case in requests.

jsonexample response

{
  "id": "8ad4f7c2-9e3b-4a1c-bc2f-1d8e3a9b7c4d",
  "name": "Acme Co",
  "slug": "acme-co",
  "createdAt": "2026-05-01T10:23:18.114Z"
}

Errors

Errors are HTTP status codes plus a JSON body with statusCode, message, and a path.

jsonexample 401

{
  "statusCode": 401,
  "timestamp": "2026-05-01T10:24:02.812Z",
  "path": "/v1/admin/tenants",
  "message": "Invalid API key"
}

Status	Meaning	What to do
`400`	Bad request	Fix payload
`401`	Missing / invalid auth	Re-issue token, rotate key
`403`	Authenticated but not allowed	Check role or tenant suspension
`404`	Resource not found	Verify ID + tenant scope
`409`	Conflict (e.g. slug taken)	Pick a different value
`429`	Rate limit hit	Backoff per `Retry-After`
`500`	Server error	Retry with backoff; if persistent, file an issue

Idempotency

POST endpoints that create resources accept an idempotency_key. Repeat calls with the same key + same payload return the original response without re-creating the resource.

WHEN TO USE

Always set an idempotency key for sends. If your service retries a timed-out request, you don't want two SMS landing on the customer's phone. Use your own internal IDs (e.g. order-AC-1042).

Pagination

List endpoints use cursor-based pagination via ?limit= and ?cursor=. Responses include a nextCursor field; pass it back to fetch the next page. limit defaults to 50 and maxes at 200.

Rate limits

Per-tenant defaults:

60 requests/minute on Live now endpoints (admin, tenant management)
10,000 messages/day on the free Hatchling plan (Live now onwards)

Per-key overrides available via POST /v1/admin/api-keys with rateLimitRpm. Rate-limit responses set Retry-After in seconds.