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

# API Introduction

> Welcome to the Dialgen API documentation. Our API allows you to programmatically initiate and monitor AI-powered voice calls, either one at a time or in high-volume batches.

## API Base URL

All API endpoints are relative to the following base URL:

```bash theme={null}
https://sa.dialgen.ai
```

## OpenAPI Specification

Our API is fully documented using the OpenAPI 3.0 specification. You can:

* View the interactive API playground for each endpoint
* Download the OpenAPI spec for use with API clients
* Test endpoints directly from the documentation

### HTTP Methods

Our API uses standard HTTP methods:

* **GET** - Retrieve data (read operations)
* **POST** - Create or modify data (write operations)

Mintlify automatically displays color-coded indicators for each HTTP method on the endpoint pages.

## Authentication

All API requests must be authenticated using a Bearer Token. Pass your API key in the `Authorization` header:

```bash theme={null}
Authorization: Bearer <YOUR_API_KEY>
```

You can obtain your API key from the [Dialgen API Keys dashboard](https://sa.dialgen.ai/api-keys).

<Info>
  **Important Note on `userId`**

  All endpoints should pass in the `userId` in the request body or query parameters. You can find your `userId` in the [sa.dialgen.ai](https://sa.dialgen.ai) dashboard.
</Info>

## Response Formats

The API uses standard HTTP status codes to indicate the success or failure of a request. All response bodies are returned in JSON format.

| Status Code                 | Description                                        |
| :-------------------------- | :------------------------------------------------- |
| `200 OK`                    | Request succeeded                                  |
| `202 Accepted`              | Request accepted for processing (used for batches) |
| `400 Bad Request`           | Missing or invalid fields/parameters               |
| `401 Unauthorized`          | Missing or invalid API key                         |
| `402 Payment Required`      | Insufficient call minutes/credits                  |
| `404 Not Found`             | The requested resource was not found               |
| `409 Conflict`              | A call is already in progress for this contact     |
| `500 Internal Server Error` | An unexpected server error occurred                |

## Best Practices

### Rate Limiting & Throttling

* **Default Rate**: 10 calls per second (adjustable via `maxCallsPerSecond` in batch options).
* **Recommendation**: Start with lower rates (5-10 CPS) and scale up based on your telephony provider's limits.

### Webhooks

For a fully automated workflow, you can provide a webhook URL when creating a batch or initiating a call.

* **Idempotency**: Your webhook endpoints should handle duplicate calls gracefully.
* **Authentication**: Secure your webhook endpoints with authentication tokens.
* **Timeout**: Respond to webhook calls within 5 seconds to avoid retries.
* **Retry Logic**: We retry failed webhook calls up to 3 times with exponential backoff.