# API overview

> The AY Inbox REST API: base URL, authentication, JSON conventions, pagination and a quickstart for driving mailboxes, campaigns, contacts and the unibox.

Source: https://docs.ayinbox.com/api/

The AY Inbox API lets you drive everything you can do in the dashboard programmatically: mailboxes, campaigns, contacts, the unibox, and more. It is a JSON API over HTTPS.

```
https://api.ayinbox.com/v1
```

Quickstart [#quickstart]

Create an API key in your dashboard under Settings, then pass it as a Bearer token on every request:

```bash
curl -X GET "https://api.ayinbox.com/v1/campaigns" \
  -H "Authorization: Bearer aybox_your_api_key_here" \
  -H "Content-Type: application/json"
```

See [Authentication](/api/authentication/) for the key format, scoping, and security guidance. Connecting an AI agent instead? Start with the [agent quickstart](/api/agent-quickstart/).

Versioning [#versioning]

The API is versioned in the URL. The current version is `v1`, and the base URL includes it: every endpoint path in these docs is relative to `https://api.ayinbox.com/v1`.

* **Stability**: within a version, changes are additive (new fields, new endpoints). A breaking change ships as a new version, so code written against `v1` keeps working.
* **Version header**: every response carries an `API-Version` header so you can confirm which version answered.
* **No unversioned alias**: every endpoint lives under `/v1`; there are no bare, unversioned paths. A future breaking change will ship as `/v2` while `/v1` keeps working.

Conventions [#conventions]

* **Permissions**: every key carries an explicit permission set; a request beyond the key's permissions returns `403`. The full list is in the [permissions reference](/api/permissions/).
* **List responses**: list endpoints return a consistent `data` plus `pagination` shape with opaque cursors.
* **Errors**: error responses carry a machine-readable `code` and a `request_id` alongside the human-readable text. Client logic should branch on `code` and HTTP status, never on message text. See [error codes](/api/error-codes/).
* **Endpoint coverage**: the [endpoint scope map](/api/endpoints/) lists every route, whether it accepts API keys, and which permission it requires. The [endpoint reference](/api/reference/mailboxes/) documents each route's request and response structures, grouped by resource.

```json
{
  "data": [],
  "pagination": { "has_more": false, "next_cursor": null }
}
```

Client libraries [#client-libraries]

There are no official client libraries yet. Any HTTP client works against the API directly, and a typed client can be generated from the OpenAPI document. See [SDKs](/api/sdks/).