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

# REST API

> Read your ZynfoAI knowledge base, tickets, leads, contacts, conversations and usage from your own code, and ask your AI agent a question. Authentication, endpoints, errors and limits.

The REST API gives your own code, or a no-code tool such as Zapier or n8n, the same read-only access that
AI assistants get through MCP. It needs the **Pro plan or the 7-day trial** and an
[API key](/api-and-mcp/api-keys).

* **Base address:** `https://app.zynfo.ai/api/v1`
* **Machine-readable description (OpenAPI):** `https://app.zynfo.ai/api/v1/openapi.json`

## Authenticate

Send your key in an `Authorization` header with every request:

```
Authorization: Bearer zk_live_YOUR_KEY
```

The workspace is the one the key belongs to. A key can't read another workspace.

```bash theme={null}
curl https://app.zynfo.ai/api/v1/usage \
  -H "Authorization: Bearer zk_live_YOUR_KEY"
```

## Endpoints

Each endpoint needs the permission shown. Pages hold up to 50 items, and `limit` and `page` choose the
size and the page (default 20 and 1).

| Endpoint | Permission | What it returns |
| - | - | - |
| `GET /knowledge/search?q=` | Search the knowledge base | Matching passages, with a score and the source. Optional `limit` (1 to 10, default 5) |
| `GET /tickets` | Read tickets | A page of tickets. Optional `status`, `priority`, `search` |
| `GET /tickets/{id}` | Read tickets | One ticket |
| `GET /leads` | Read leads | A page of leads. Optional `status`, `search` |
| `GET /contacts` | Read contacts | A page of contacts. Optional `search`, `stage` |
| `GET /conversations` | Read conversations | A page of conversations. Optional `status` (`active` or `ended`) |
| `GET /conversations/{id}` | Read conversations | One conversation with its last 200 messages |
| `GET /usage` | Read plan usage | Plan, AI replies used and knowledge sources |
| `POST /agent/ask` | Ask the AI agent | The agent's answer and its sources. **Uses one AI reply** |

The values for `status`, `priority` and `stage` are listed in [MCP tools](/api-and-mcp/mcp-tools).

## Responses

Every response is JSON with `"success": true` and the result in `data`. Lists also have a `pagination`
object:

```json theme={null}
{
  "success": true,
  "data": [ { "id": 21, "subject": "…", "status": "resolved" } ],
  "pagination": { "page": 1, "limit": 20, "total": 1, "totalPages": 1 }
}
```

Responses are never cached. Tickets, leads, contacts and conversations include your customers' details.

## Ask the AI agent

```bash theme={null}
curl https://app.zynfo.ai/api/v1/agent/ask \
  -H "Authorization: Bearer zk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "Do you ship to Canada?"}'
```

The answer comes back in `data.answer`, with `data.sources`. A question can be up to 2,000 characters.
Each call counts as one AI reply of your monthly allowance.

## Errors

A failed request has `"success": false`, a `code` you can test for and a message:

```json theme={null}
{ "success": false, "code": "insufficient_scope", "error": "This API key does not have the \"leads:read\" scope." }
```

| Status | `code` | Meaning |
| - | - | - |
| 400 | `bad_request` | A missing or wrong parameter, or an id that isn't a number |
| 401 | `invalid_api_key` | No key, or the key is wrong, expired or revoked |
| 403 | `insufficient_scope` | The key doesn't have the permission this endpoint needs |
| 403 | `pro_plan_required` | The workspace isn't on the Pro plan or the trial |
| 403 | `workspace_deleted` | The workspace is scheduled for deletion |
| 404 | `not_found` | No ticket or conversation with that id |
| 429 | `rate_limited` | More than 60 requests a minute. Wait for the number of seconds in the `Retry-After` header |
| 500 | `internal_error` | Something went wrong on our side. Try again |

The permissions are named `kb:read`, `tickets:read`, `leads:read`, `contacts:read`,
`conversations:read`, `usage:read` and `agent:ask`.

## Limits

* 60 requests a minute for each key.
* Read-only: there are no endpoints that create, change or delete anything.
* Up to 20 active keys in a workspace.

## Related topics

* [API keys](/api-and-mcp/api-keys)
* [MCP tools](/api-and-mcp/mcp-tools)
* [Connect AI agents to ZynfoAI](/api-and-mcp/overview)


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