API introduction

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

Base URL

https://api.inbox.adraa.ai

Authentication

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

curl https://api.inbox.adraa.ai/api/v1/me \
  -H "Authorization: Bearer adraa_..."

Workspace admins create tokens in Settings → API. See Authentication for the full setup guide.

Errors

All errors share one envelope:

{
  "error": {
    "code": "CONVERSATION_NOT_FOUND",
    "message": "Conversation not found"
  }
}

Validation failures include field-level details:

{
  "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.

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.

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:

https://app.inbox.adraa.ai/<workspace>/conversations/<conversationId>

API reference

Tokens

Agents

Contacts

Tags

Conversations

Broadcast

WhatsApp

Base URL

Authentication

Errors

Rate limits

IDs

​Base URL

​Authentication

​Errors

​Rate limits

​IDs

Base URL

Authentication

Errors

Rate limits

IDs