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

# Simio API reference: conversational REST API

> The Simio REST API lets you send campaigns, trigger automations and manage segments from your own systems. Base URL: https://getsimio.app/api

The Simio API is a REST API that lets you integrate conversational marketing into your own systems. Use it to send campaigns, trigger automations and build segments of contacts. This reference covers every endpoint, parameter and response shape you need to build a production integration.

## Base URL

All API requests are made to the following base URL:

```text theme={null}
https://getsimio.app/api
```

The Simio web application is available at [getsimio.app](https://getsimio.app).

## Authentication

Every request must include your company API key in the `simio-api-key` header. Keys are generated by an admin in the Simio application under **Settings → Integrations & developers → Credentials**. See the [Authentication](/simio/api-reference/authentication) page for full details.

## Request format

Send all request bodies as JSON with the `Content-Type: application/json` header. All string values must be UTF-8 encoded.

```bash theme={null}
curl -X POST https://getsimio.app/api/campaigns/send \
  -H "simio-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "campaign_id": 42, "contacts": ["+33612345678"] }'
```

## Response format

Every response body is JSON. Successful responses use HTTP `2xx` status codes. Sending endpoints are asynchronous: they return `202 Accepted` once the request is queued, and messages are delivered in the background.

Error responses contain a `detail` key with a human-readable message:

```json theme={null}
{
  "detail": "Invalid API key"
}
```

Validation errors (`422`) return `detail` as a list describing each invalid field:

```json theme={null}
{
  "detail": [
    {
      "loc": ["body", "campaign_id"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}
```

## Rate limits

Rate limits are applied per endpoint. When you exceed a limit, the API returns `429 Too Many Requests` with a body of the form `{ "error": "Rate limit exceeded: ..." }`. Wait before retrying, ideally with an exponential backoff.

| Endpoint | Limit |
| - | - |
| `POST /api/campaigns/send` | 10 requests per second |
| `POST /api/automations/send` | 20 requests per second |
| `POST /api/segments/create` | 10 requests per second |
| `POST /api/segments/{segment_id}/contacts` | 1 request per minute |
| `POST /api/batch/send` | 1 request every 10 seconds |
| `POST /api/brevo/send` | 1 request every 10 seconds |

<Note>
  If you need a higher rate limit for a high-volume integration, contact Simio support to discuss an increased quota.
</Note>

## HTTP status codes

| Code | Meaning |
| - | - |
| `200` | Success |
| `201` | Created |
| `202` | Accepted: the request is queued for processing |
| `400` | Bad Request: invalid request body |
| `401` | Unauthorized: missing or invalid API key |
| `403` | Forbidden: no active subscription, or workspace not provisioned |
| `404` | Not Found: unknown campaign, automation or segment, or connector not connected |
| `409` | Conflict: for example, the maximum number of segments is reached |
| `422` | Unprocessable Entity: validation error |
| `429` | Too Many Requests: rate limit exceeded |
| `500` | Internal Server Error |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.