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

# Conventions

> How every Wiredesk API endpoint behaves: JSON bodies, the data envelope, request ids, error codes, cursor pagination and rate limits.

## Requests and responses

Send JSON bodies with `Content-Type: application/json`. A single object comes back as `{ "data": { … } }`. Timestamps are ISO 8601 in UTC, and ids are strings.

Every response has an `x-request-id` header, errors included. Look it up under **Developers → Logs** to see how that request went, and include it when you contact support about a request. See [Request logs](https://wiredesk.ai/docs/developers/logs.md).

## Errors

An error has a status and a body with a machine-readable `code`:

```json theme={null}
{ "error": { "code": "not_found", "message": "no agent with that id" } }
```

| Status | `code` | Meaning |
| - | - | - |
| 400 | `invalid_request` | A parameter or the body is wrong. `message` says which. |
| 401 | `unauthorized` | No key, a malformed key, or a revoked one. |
| 402 | `spend_cap_reached` | The workspace hit its [spend cap](https://wiredesk.ai/docs/account/spend-cap.md). Only sending messages is affected. |
| 403 | `read_only_key` | A read-only key tried to change something. |
| 403 | `channel_disabled` | The agent's chat channel is switched off, so it does not answer messages sent to it. |
| 403 | `knowledge_full` | Adding this knowledge would go past the workspace plan's [knowledge allowance](https://wiredesk.ai/docs/knowledge/overview.md#how-much-knowledge-your-plan-holds). `message` says how much room is left. |
| 404 | `not_found` | No such endpoint, or nothing with that id in your workspace. |
| 405 | `method_not_allowed` | The path exists but does not take this method. |
| 409 | `already_exists` | A contact with that phone number or email exists. `contact_id` names it. |
| 409 | `conflict` | The onboarding was already claimed, deleted or expired. |
| 429 | `rate_limited` | Too many requests for this key, or too many onboardings from your address. Wait for `Retry-After` seconds. |
| 500 | `internal_error` | Something failed on our side. Retry. |
| 502 | `upstream_error` | The agent could not reply, or text could not be indexed. Retry. |
| 503 | `not_configured` | Chat is not set up on this deployment. |

An id from another workspace gets `404`, the same as an id that does not exist.

## Pagination

List endpoints return a page, newest first, with a cursor for the next one:

```json theme={null}
{ "data": [ … ], "next_cursor": "WzE3NjAwMDAwMDAwMDAsImM…", "has_more": true }
```

Pass `limit` (1 to 100, 20 by default) and the `next_cursor` you got back as `cursor`. When `has_more` is false, `next_cursor` is `null` and you have everything. Cursors are opaque: do not build or edit them. A conversation's messages come oldest first, the order a transcript is read in.

## Rate limits

Each key can make 120 requests a minute. Past that, requests get `429` with a `Retry-After` header until the minute is up. A sync that needs more should spread its work out.


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