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

# Using the API

> Shared conventions for authentication, identifiers, pagination, errors, and message delivery.

## Base URL and authentication

All routes in this reference are relative to:

```text theme={null}
https://platform-api.visitoai.com/m2m/v1
```

Send `Authorization: Bearer <API_KEY>` with every request. A key belongs to one business and needs the scopes required by each endpoint. Write permissions do not imply read access. See [authentication](https://docs.visitoai.com/api-docs/authentication.md) and [permissions](https://docs.visitoai.com/api-docs/permissions.md) to create and limit access.

## Identifiers and current state

Use the identifiers returned by Visito. A channel's stored `id`, for example, is different from a provider phone, page, or WABA identifier. The credential establishes the business boundary; adding a tenant ID to a request does not switch businesses.

When an endpoint requires a version or update timestamp, obtain it from a fresh read. After a `409` conflict, reload the resource and reconcile changes before saving.

## Pagination

Check each endpoint's parameters and response shape. For cursor-based lists, pass the returned `nextCursor` as the next `cursor`, preserve the filters, and continue while `hasMore` is true. Limits and fields can differ by resource.

## Sends and retries

Send endpoints that require `Idempotency-Key` need a stable key for the same intended operation. When retrying, keep the exact same key and body. Use a new key when the recipient or content changes.

A `202 Accepted` response means work was accepted and queued. Store the returned identifiers and use the [delivery status endpoints](https://docs.visitoai.com/api-reference/messaging/overview) to check the outcome. Check each operation's requirements before retrying a write; not every write is idempotent.

## Errors

Error responses contain a structured code and a message:

```json theme={null}
{
  "error": {
    "code": "M2M_AUTH_INSUFFICIENT_SCOPE",
    "message": "M2M credential does not have required scope."
  }
}
```

`error.details` is optional. It can include missing scopes or `retryAfterSeconds`.

| Status | What to check |
| - | - |
| `400` | Parameters, body, and required headers. |
| `401` / `403` | The credential and the endpoint's required scopes. |
| `404` | The resource ID and the business it belongs to. |
| `409` | Current state, version fields, and the retry contract. |
| `429` | The limit reached; honor `retryAfterSeconds` when present. |
| `5xx` | The transient failure; reconcile any accepted write before retrying. |

For transient read failures, use exponential backoff with jitter. Avoid automatically retrying validation, permission, or conflict errors. Each endpoint page documents its specific responses.


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