# Nabrah API reference

The Nabrah API lets you run Arabic-first voice agents from your own code: create agents and the tools they call, place and analyze calls, generate and transcribe speech, and work your WhatsApp, Instagram and TikTok inbox.

## Base URL

Every endpoint in this reference is served from one base URL over HTTPS. Requests and responses are JSON unless an endpoint says otherwise, such as file uploads and generated audio.

```text
https://api.nabrah.ai/api
```

## Authentication

Send your workspace API key in the `X-API-Key` header on every request. A key belongs to one workspace, so it only reaches that workspace’s agents, calls and conversations. Create and rotate keys in the dashboard under API keys, keep them out of public code and repositories, and rotate a key straight away if it leaks.

```text
X-API-Key: <your-api-key>
```

## Make your first request

1. **Create an API key.** In the Nabrah dashboard, open API keys and create a key for your workspace. It is shown once, so store it somewhere safe.
2. **Verify it.** Call the verify endpoint with the key. A `200` response confirms the key and shows which workspace it belongs to.
3. **Build on it.** Create an agent, connect a number, and place a call, or start with speech: generate audio or transcribe a file.

```bash
curl --request GET \
  --url 'https://api.nabrah.ai/api/ext/test' \
  --header 'X-API-Key: <your-api-key>'
```

```json
{
  "status": "success",
  "message": "API key is valid",
  "key_details": {
    "id": "7c0d3f0e-2a52-4b8e-9d3c-5f0e7f4a1b2c",
    "user ID": "0b6f1c0a-3d9e-4c11-8f5e-2e7a9d1c4b6f",
    "project_id": "5e2a9c7d-1f4b-4e8a-a3c6-9d0b2f7e8c1a",
    "created_at": "2026-01-15T12:00:00.000Z"
  }
}
```

## Errors

Errors use standard HTTP status codes with a JSON body. The `detail` field says what went wrong: a message for most errors, and a list of problems for validation errors.

- `200–204`: The request worked. `204` responses have no body.
- `401`: The `X-API-Key` header is missing, or the key is invalid or revoked.
- `404`: The resource does not exist in the workspace your key belongs to.
- `422`: The request failed validation. Each item in `detail` names the field (`loc`) and the problem (`msg`).
- `5xx`: Something failed on our side. Retry with backoff; contact support if it continues.

```json
{
  "detail": [
    {
      "loc": [
        "body",
        "agent_id"
      ],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}
```

## Endpoints

Endpoints are grouped by what they work on. Each page documents its parameters and responses, with samples in cURL, Python, JavaScript and Go, and a playground to send real requests.

- [Authentication](https://www.nabrah.ai/en/docs/api-reference/authentication.md): Check that an API key works and see which workspace it belongs to.
- [Agents](https://www.nabrah.ai/en/docs/api-reference/agents.md): Create and configure voice agents, and choose which analysis groups run after their calls.
- [Tools](https://www.nabrah.ai/en/docs/api-reference/tools.md): Register the HTTP tools an agent can call during a conversation, and link them to agents.
- [Analysis groups](https://www.nabrah.ai/en/docs/api-reference/analysis-groups.md): Define the data extracted from every call, and link analysis groups to agents.
- [Knowledge bases](https://www.nabrah.ai/en/docs/api-reference/knowledge-bases.md): Create the knowledge bases an agent retrieves answers from during a call.
- [Documents](https://www.nabrah.ai/en/docs/api-reference/documents.md): Add documents to a knowledge base and track their ingestion.
- [Calls](https://www.nabrah.ai/en/docs/api-reference/calls.md): Place outbound calls, then search, export and analyze call records and recordings.
- [Web calls](https://www.nabrah.ai/en/docs/api-reference/web-calls.md): Start a browser voice session with an agent and get the token your frontend joins with.
- [SIP inbound](https://www.nabrah.ai/en/docs/api-reference/sip-inbound.md): Manage the inbound SIP trunks that bring calls to your numbers into Nabrah.
- [SIP outbound](https://www.nabrah.ai/en/docs/api-reference/sip-outbound.md): Manage the outbound SIP trunks your agents place calls through.
- [Agent inbound links](https://www.nabrah.ai/en/docs/api-reference/agent-inbound-links.md): Choose which agent answers the calls that arrive on each inbound trunk.
- [Text to speech](https://www.nabrah.ai/en/docs/api-reference/text-to-speech.md): Generate natural Arabic and English speech, and manage the voices you generate with.
- [Speech to text](https://www.nabrah.ai/en/docs/api-reference/speech-to-text.md): Transcribe recorded audio in the background, or stream audio for live transcripts.
- [Contacts](https://www.nabrah.ai/en/docs/api-reference/contacts.md): Create, update and search the contacts your workspace talks to on every channel.
- [Conversations](https://www.nabrah.ai/en/docs/api-reference/conversations.md): Read and reply to inbox conversations, assign them, and change their status and priority.
- [Tickets](https://www.nabrah.ai/en/docs/api-reference/tickets.md): Create and work support tickets, and configure the inboxes they arrive in.
- [WhatsApp](https://www.nabrah.ai/en/docs/api-reference/whatsapp.md): Connect WhatsApp numbers, work their conversations and put an agent on each number.
- [Instagram](https://www.nabrah.ai/en/docs/api-reference/instagram.md): Work the conversations of connected Instagram accounts and put an agent on each account.
- [TikTok](https://www.nabrah.ai/en/docs/api-reference/tiktok.md): Work the conversations of connected TikTok accounts and put an agent on each account.