# Axis Inbox

> One API for connections, conversations and campaigns across WhatsApp, Meta, SMS, email, live chat
> and the social networks. Applications talk to Inbox only; behind it sit the provider integrations
> they never name in code.

Two things decide every request: the **credential** (an Accounts `sk_` service key, or a user's
session) and the **tenant** (`X-Axis-Tenant: ws_<accountsUserGroupId>`). Omitting the tenant is how
you reach the cross-tenant operator surface; getting it *wrong* silently provisions a new empty
workspace rather than erroring, which is the most common integration bug.

## Integration skill (start here for agents)

- [SKILL.md](/skill/SKILL.md): Complete onboarding runbook — verified against a live service
- [onboard.mjs](/skill/scripts/onboard.mjs): Idempotent end-to-end onboarding script, supports --dry-run
- [config.example.json](/skill/references/config.example.json): Its input format
- [authentication.md](/skill/references/authentication.md): Credentials, tenancy, scopes, operator access
- [consuming-the-api.md](/skill/references/consuming-the-api.md): SDK and raw HTTP, envelopes, idempotency
- [receiving-events.md](/skill/references/receiving-events.md): WebSocket, SSE and outbound webhooks
- [channels.md](/skill/references/channels.md): Connecting WhatsApp, Meta, email, SMS and live chat
- [manual-onboarding.md](/skill/references/manual-onboarding.md): The curl sequence, for debugging
- [troubleshooting.md](/skill/references/troubleshooting.md): Every failure code and its real cause

## Documentation

### Start

- [Overview](/docs)
- [Run it locally](/docs/getting-started/quickstart)
- [Connect an app](/docs/getting-started/connect-an-app)
- [Your first conversation](/docs/getting-started/first-conversation)

### Concepts

- [Architecture](/docs/concepts/architecture)
- [Tenancy](/docs/concepts/tenancy)
- [Data model](/docs/concepts/data-model)
- [Glossary](/docs/concepts/glossary)

### Calling the API

- [Authentication](/docs/api/authentication)
- [Scopes and guards](/docs/api/scopes-and-guards)
- [Envelopes and errors](/docs/api/envelopes)
- [Idempotency](/docs/api/idempotency)
- [Pagination](/docs/api/pagination)
- [Rate limits](/docs/api/rate-limits)

### Channels

- [Connections and bindings](/docs/channels/model)
- [Adapter catalogue](/docs/channels/adapters)
- [Connecting an account](/docs/channels/connecting)
- [WhatsApp](/docs/channels/whatsapp)
- [Email](/docs/channels/email)
- [LiveChat](/docs/channels/livechat)
- [Connection requests](/docs/channels/connection-requests)

### Conversations

- [How a message arrives](/docs/conversations/ingest)
- [Threads and entries](/docs/conversations/threads)
- [Replying](/docs/conversations/replying)
- [Tickets](/docs/conversations/tickets)
- [AI and human routing](/docs/conversations/routing)
- [Labels, notes and canned replies](/docs/conversations/annotations)

### Contacts

- [Identity and deduplication](/docs/contacts/identity)
- [Segments](/docs/contacts/segments)
- [Consent and suppression](/docs/contacts/consent)

### Outbound

- [Campaigns](/docs/outbound/campaigns)
- [Templates](/docs/outbound/templates)
- [Flows](/docs/outbound/flows)
- [Warm-up](/docs/outbound/warmup)
- [Publishing](/docs/outbound/publishing)

### Realtime

- [WebSocket](/docs/realtime/websocket)
- [Server-sent events](/docs/realtime/sse)
- [Outbound webhooks](/docs/realtime/webhooks-out)

### Inbound webhooks

- [Provider webhooks](/docs/webhooks/providers)
- [Signature verification](/docs/webhooks/verification)

### Clients

- [The Node SDK](/docs/clients/sdk)
- [The operator SDK](/docs/clients/operator-sdk)
- [Any language (raw HTTP)](/docs/clients/raw-http)
- [Browser apps and the BFF pattern](/docs/clients/bff)
- [AI agents and LLMs](/docs/clients/llms)

### Operating

- [The operator surface](/docs/operating/operator-surface)
- [Configuration](/docs/operating/configuration)
- [Deployment](/docs/operating/deployment)
- [Queues and workers](/docs/operating/queues)
- [Historical imports](/docs/operating/imports)
- [Reports](/docs/operating/reports)
- [Troubleshooting](/docs/operating/troubleshooting)

### Reference

- [HTTP API](/docs/reference/http-api)
- [Scopes](/docs/reference/scopes)
- [Error codes](/docs/reference/error-codes)
- [Public surface](/docs/reference/public-surface)

## Notes for agents

- Reference pages (HTTP API, scopes, error codes, configuration) are GENERATED from source at build
  time and cannot drift from the running service.
- Every response is `{ data, meta }` and every error is `{ error: { code, message, requestId } }`.
  Unwrap on the PRESENCE of `data`, not its truthiness — `{ "data": null }` is a valid answer.
- Every write needs an `Idempotency-Key`. It is required by HTTP verb, not per route, so some
  POSTs that only read still demand one.
- `admin` satisfies every scope check on tenant-scoped routes and NOTHING on operator routes.
- Threads are never created directly. There is no create-thread endpoint; they appear through
  ingest.
- The SDK is `@~inbox/sdk` on npm. Its README is out of date on credentials — it predates
  Accounts `sk_` keys. These docs are current; the README is not.