> ## Documentation Index
> Fetch the complete documentation index at: https://docs.inbox.adraa.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API introduction

> Base URL, authentication, errors, and rate limits for the Adraa Inbox API.

The Adraa Inbox API is a REST API served over HTTPS. Requests and responses use JSON.

## Base URL

```text theme={null}
https://api.inbox.adraa.ai
```

## Authentication

Every request requires a workspace API token in the `Authorization` header:

```bash theme={null}
curl https://api.inbox.adraa.ai/api/v1/me \
  -H "Authorization: Bearer adraa_..."
```

Workspace admins create tokens in **Settings → API**. See [Authentication](/authentication) for the full setup guide.

## Errors

All errors share one envelope:

```json theme={null}
{
  "error": {
    "code": "CONVERSATION_NOT_FOUND",
    "message": "Conversation not found"
  }
}
```

Validation failures include field-level `details`:

```json theme={null}
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request data",
    "details": [{ "field": "body", "message": "Message body cannot be empty" }]
  }
}
```

Common codes:

| Status | Code                             | Meaning                                                                  |
| ------ | -------------------------------- | ------------------------------------------------------------------------ |
| 400    | `VALIDATION_ERROR`               | The request body failed validation. Check `details`.                     |
| 400    | `WHATSAPP_SERVICE_WINDOW_CLOSED` | WhatsApp's 24-hour reply window has closed for this conversation.        |
| 400    | `LAST_ADMIN`                     | The change would leave the workspace without an admin.                   |
| 400    | `AGENT_MANAGED`                  | The agent is managed by Adraa Inbox (the AI agent) and can't be changed. |
| 401    | `MISSING_TOKEN`                  | No `Authorization` header was sent.                                      |
| 401    | `INVALID_API_TOKEN`              | The token is unknown or has been revoked.                                |
| 403    | `COMPANY_MISMATCH`               | The agent belongs to a different workspace than the conversation.        |
| 404    | `CONVERSATION_NOT_FOUND`         | The conversation does not exist in your workspace.                       |
| 404    | `AGENT_NOT_FOUND`                | The agent is not an active member of your workspace.                     |
| 404    | `CONTACT_NOT_FOUND`              | The contact has never messaged your workspace.                           |
| 409    | `AGENT_ALREADY_MEMBER`           | The email already belongs to a workspace member.                         |
| 409    | `NICKNAME_TAKEN`                 | The display name is already in use across Adraa Inbox.                   |
| 429    | `RATE_LIMIT_EXCEEDED`            | Too many requests. Back off and retry.                                   |

<Note>
  A `404` is returned for conversations that exist but belong to another
  workspace. The API never reveals whether a resource exists outside the
  token's workspace.
</Note>

## Rate limits

Write endpoints are rate limited — 60 requests per minute for conversation writes (assign, send message), 30 per minute for agent and contact writes, and 10 per minute for sending a broadcast; each endpoint's reference page lists its limit. All other endpoints accept 100 requests per minute per IP. Exceeding a limit returns `429 RATE_LIMIT_EXCEEDED`.

## IDs

Resources use cuid identifiers like `cmbxgz9pq0003ph01m4n5o6p7`. To find a conversation's ID, open it in the agent console — it's the last segment of the URL:

```text theme={null}
https://app.inbox.adraa.ai/<workspace>/conversations/<conversationId>
```