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

# API Overview

> Understand the structure, versioning, and usage patterns of the Ringg AI API

The Ringg AI API lets your backend create assistants, initiate calls, run campaigns, manage numbers, and retrieve post-call results. Use this page as the mental model before jumping into individual endpoints.

## API Architecture

Ringg AI provides REST-style APIs that allow you to:

* Create and manage AI voice assistants
* Initiate individual and bulk calls
* Embed voice assistants on websites
* Manage reusable contact lists and phone numbers
* Access call history and analytics
* Subscribe assistants to webhook events

## Base URL

All API requests should be made to the following base URL:

```
https://prod-api.ringg.ai/ca/api/v0
```

## Available Resources

The Ringg AI API is organized around the following main resources:

* **Workspace**: Verify authentication, manage workspace metadata, users, credits, and API keys.
* **Assistant**: Create, list, fetch, and configure AI voice assistants.
* **Numbers**: Fetch caller numbers available for outbound calls and campaigns.
* **Calling**: Initiate individual outbound calls and inspect call history.
* **Campaigns**: Upload campaign CSVs, start bulk calls, and monitor campaign state.
* **Webhooks**: Subscribe assistants to call, recording, and analysis events.
* **Analytics**: Build dashboards from call, number, duration, and classification metrics.

## Request and Response Formats

Most Ringg API endpoints accept and return JSON. Use this header for `POST` and `PATCH` requests with JSON bodies:

```
Content-Type: application/json
```

For campaign CSV uploads and contact CSV uploads, send `multipart/form-data` and let your HTTP client set the `Content-Type` boundary.

## Common Headers

All API requests require the following headers:

* `X-API-KEY`: Workspace API key for authentication.
* `Content-Type`: Set to `application/json` for JSON requests. Omit it for `FormData`/multipart requests unless your HTTP client requires otherwise.

## Core ID fields

Store these IDs in your application. They are how Ringg APIs and webhooks connect.

| ID                         | Where it comes from                     | Where it is used                                    |
| -------------------------- | --------------------------------------- | --------------------------------------------------- |
| `agent_id`                 | Assistant APIs or dashboard             | Individual calls, campaigns, webhook subscriptions  |
| `from_number_id`           | `GET /workspace/numbers`                | Individual outbound calls                           |
| `list_id` / `bulk_list_id` | Campaign upload                         | Campaign start, campaign analytics, history filters |
| `call_id`                  | Call initiation, call history, webhooks | Webhook dedupe, call details, support debugging     |

## Error Handling

The Ringg AI API uses conventional HTTP response codes to indicate the success or failure of requests:

* `2xx`: Success
* `4xx`: Client errors (invalid request, authentication issues)
* `5xx`: Server errors

Error responses include a JSON body with details about what went wrong:

```json theme={null}
{
  "error": {
    "code": "invalid_request",
    "message": "The mobile_number parameter is required"
  }
}
```

### Common Error Codes

* **400**: Bad Request – Invalid parameters or request format
* **401**: Unauthorized – Invalid or missing API key
* **404**: Not Found – Resource doesn’t exist
* **429**: Too Many Requests – Rate limit exceeded
* **500**: Internal Server Error – Something went wrong on our end

## API Versioning

The current version of the Ringg AI API is `v0`. The version is included in the base URL:

```
https://prod-api.ringg.ai/ca/api/v0
```

Future versions will follow the pattern `v1`, `v2`, etc. We’ll provide ample notice before deprecating any API version to ensure a smooth transition for your applications.

## Pagination

For endpoints that return lists of objects, the API supports pagination through the following query parameters:

* **limit**: Number of items to return (default: 20, max: 100)
* **offset**: Number of items to skip (default: 0)

## Recommended integration order

1. Verify API key with `GET /workspace`.
2. Select an assistant with `GET /agent/all`.
3. Select a number with `GET /workspace/numbers`.
4. Make one call with `POST /calling/outbound/individual`.
5. Configure webhooks for post-call events.
6. Add campaigns, analytics, and history views.

## Next Steps

Now that you understand the basics of the Ringg AI API, you’re ready to start building!

> Check out our detailed documentation for each resource to learn more about specific endpoints and capabilities.