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

# Introduction

> Overview of the Samora AI API

## Overview

The Samora AI API lets you trigger immediate outbound calls and manage outbound
campaigns through the Samora AI system. Use it to start calls with your AI
agents, pass per-call context, create campaigns, add recipients, and manage
campaign lifecycle from your server.

## Base URL

All requests go to:

```
https://api.samora.ai
```

## Authentication

Every request must include your organization API key in the header:

| Header      | Description                      |
| ----------- | -------------------------------- |
| `X-API-Key` | Your unique organization API key |

<Note>
  These APIs are intended for server-to-server integrations. Do not expose your
  organization API key in browser or mobile clients.
</Note>

Example:

```bash theme={null}
curl -X POST "https://api.samora.ai/v1/call/trigger" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "123e4567-e89b-12d3-a456-426614174000", "to_number": "+919876543210"}'
```

## Endpoints

### Calls

| Method | Path                 | Description                                                                 |
| ------ | -------------------- | --------------------------------------------------------------------------- |
| POST   | `/v1/call/trigger`   | [Trigger an outbound call](/api-reference/endpoint/trigger-call)            |
| GET    | `/v1/call/{call_id}` | [Get details for a specific call](/api-reference/endpoint/get-call-details) |

### Campaigns

| Method | Path                                                              | Description                                                                |
| ------ | ----------------------------------------------------------------- | -------------------------------------------------------------------------- |
| POST   | `/v1/external/campaigns/{agent_id}`                               | [Create a campaign](/api-reference/endpoint/create-campaign)               |
| GET    | `/v1/external/campaigns/{agent_id}`                               | [List campaigns](/api-reference/endpoint/list-campaigns)                   |
| GET    | `/v1/external/campaigns/{agent_id}/{campaign_id}`                 | [Get campaign details](/api-reference/endpoint/get-campaign)               |
| PUT    | `/v1/external/campaigns/{agent_id}/{campaign_id}`                 | [Update campaign settings](/api-reference/endpoint/update-campaign)        |
| POST   | `/v1/external/campaigns/{agent_id}/{campaign_id}/scheduled-calls` | [Add campaign recipients](/api-reference/endpoint/add-campaign-recipients) |
| GET    | `/v1/external/campaigns/{agent_id}/{campaign_id}/calls`           | [List campaign calls](/api-reference/endpoint/list-campaign-calls)         |
| POST   | `/v1/external/campaigns/{agent_id}/{campaign_id}/start`           | [Start a campaign](/api-reference/endpoint/start-campaign)                 |
| POST   | `/v1/external/campaigns/{agent_id}/{campaign_id}/stop`            | [Stop a campaign](/api-reference/endpoint/stop-campaign)                   |
| POST   | `/v1/external/campaigns/{agent_id}/{campaign_id}/cancel`          | [Cancel a campaign](/api-reference/endpoint/cancel-campaign)               |

### Webhooks

| Method | Path                        | Description                                                           |
| ------ | --------------------------- | --------------------------------------------------------------------- |
| POST   | `/v2/webhooks`              | [Create a webhook](/api-reference/endpoint/create-webhook)            |
| GET    | `/v2/webhooks`              | [List webhooks](/api-reference/endpoint/list-webhooks)                |
| GET    | `/v2/webhooks/events`       | [Get webhook event types](/api-reference/endpoint/get-webhook-events) |
| GET    | `/v2/webhooks/{webhook_id}` | [Get webhook details](/api-reference/endpoint/get-webhook)            |
| PUT    | `/v2/webhooks/{webhook_id}` | [Update a webhook](/api-reference/endpoint/update-webhook)            |
| DELETE | `/v2/webhooks/{webhook_id}` | [Delete a webhook](/api-reference/endpoint/delete-webhook)            |

## Phone number format

Destination numbers must be in **E.164** format (e.g. `+919876543210`) and
include the country code. The pattern is: `+` followed by 10–15 digits.

## Call statuses

When you fetch call details, `status` can be:

* `PENDING` — Call request created, not yet initiated
* `TRIGGERED` — Call initiated
* `ONGOING` — Call in progress
* `CALL_FINISHED` — Call completed
* `UNANSWERED` — No answer
* `REJECTED` — Call rejected

## Campaign lifecycle

Campaign `status` can be `DRAFT`, `SCHEDULED`, `IN_PROGRESS`, `PAUSED`,
`FINISHED`, `FAILED`, or `CANCELLED`.

* Add recipients only when campaign status is `DRAFT` or `PAUSED`
* Start campaigns only from `DRAFT` or `PAUSED`
* Stop campaigns only from `IN_PROGRESS`
* Cancel campaigns unless they are already `FINISHED`, `FAILED`, or `CANCELLED`

## Campaign API limits

* Request body size: 2 MiB
* Campaign name: up to 120 characters
* List campaigns `page_size`: up to 100
* Add recipients: up to 5000 phone numbers per request
* Recipient `call_variables`: up to 4 KiB per phone number

## Retry configuration

Campaign create and update endpoints accept an optional `retry_config` object:

```json theme={null}
{
	"max_retries": 2,
	"retry_delay_minutes": 30,
	"retry_on": ["UNANSWERED", "REJECTED", "VOICEMAIL"]
}
```

Supported `retry_on` values are `UNANSWERED`, `REJECTED`, `VOICEMAIL`, and
`FAILED`. When `retry_config` is provided, `max_retries` must be between 1 and
5, `retry_delay_minutes` must be between 1 and 1440, and `retry_on` must include
at least one supported status.

## Transcripts and recordings

For finished calls, the Get call details response can include:

* **transcript\_url** — Presigned URL for the call transcript (valid 60 minutes)
* **recording\_url** — Presigned URL for the call recording (valid 60 minutes)

## Webhooks

Webhooks let you receive real-time notifications when call events occur. You can
subscribe to specific event types:

* `CALL_STARTED` — Triggered when a call begins
* `CALL_FINISHED` — Triggered when a call ends (transcript and recording
  available)
* `CALL_FAILED` — Triggered when a call fails, is rejected, or goes unanswered

Each webhook includes a signing secret (returned only at creation) for verifying
payloads. You can optionally include transcript data and recording URLs in the
webhook payload via `data_options`.

<Note>
  Webhook endpoints use the `/v2/webhooks` base path at `https://api.samora.ai`.
</Note>

## Support

For API support, contact [Samora AI Support](mailto:vineeth@samora.ai).