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

# API reference

> Complete reference for the Nedzo REST API. Covers authentication, base URL, request formats, error codes, pagination, and available endpoints.

The Nedzo API is organized around REST. It uses standard HTTP methods, returns JSON responses, and uses standard HTTP status codes.

## Base URL

```
https://api.nedzo.ai/v1
```

## Authentication

All API requests require a Bearer token in the `Authorization` header:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

See [Authentication](/authentication) for more details.

<Note>
  If you're using an **account-scoped** API key, most endpoints require a `workspaceId` in the request body or query string. Workspace-scoped keys infer it automatically. See [Workspace ID and Request Scope](/authentication#workspace-id-and-request-scope) for details on which to use and how to find your workspace ID.
</Note>

## Request Format

For `POST`, `PUT`, and `PATCH` requests, send JSON in the request body:

```bash theme={null}
curl -X POST https://api.nedzo.ai/v1/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Agent", "workspaceId": "789e4567-e89b-12d3-a456-426614174000"}'
```

## Response Format

All responses are JSON. Successful responses return the requested data:

```json theme={null}
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "My Agent",
  "createdAt": "2024-01-15T10:30:00Z"
}
```

## Errors

Errors follow the [RFC 7807](https://tools.ietf.org/html/rfc7807) Problem Details format:

```json theme={null}
{
  "type": "https://api.nedzo.ai/errors/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "Agent not found"
}
```

### HTTP Status Codes

| Code  | Description                                                         |
| ----- | ------------------------------------------------------------------- |
| `200` | Success                                                             |
| `201` | Created                                                             |
| `400` | Bad Request - Invalid parameters                                    |
| `401` | Unauthorized - Invalid or missing API key                           |
| `404` | Not Found - Resource doesn't exist                                  |
| `409` | Conflict - Resource already exists or conflicts with existing state |
| `422` | Validation Error - Request failed validation                        |
| `429` | Too Many Requests - Rate limited                                    |
| `500` | Internal Server Error                                               |
| `502` | Bad Gateway - Upstream service error                                |

## Pagination

List endpoints support pagination via query parameters:

| Parameter | Description              | Default |
| --------- | ------------------------ | ------- |
| `limit`   | Number of items per page | 20      |
| `offset`  | Number of items to skip  | 0       |

```bash theme={null}
GET /v1/contacts?limit=50&offset=100
```

## Rate Limiting

Write requests on the public API (e.g. creating contacts, sending messages, triggering calls) are throttled per API key using a sustained-plus-burst model:

* **Sustained rate:** 1 request per second.
* **Burst capacity:** equal to your account's concurrency limit. Requests above the burst capacity are rejected immediately, not queued.

When you exceed the limit, you'll receive a `429` response with a `Retry-After` header (in seconds) indicating when you can retry. Read endpoints (`GET`) are not subject to this throttle.

If you need a higher burst limit, [contact support](mailto:support@nedzo.ai) or your Nedzo account contact.