> For the complete documentation index, see [llms.txt](https://help.zaapi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.zaapi.com/developers/open-api.md).

# Open API

The Zaapi Open API lets your own services read and write your workspace data programmatically — pull tickets into a BI dashboard, sync contacts with your CRM, send messages from your own tooling, or push updates back into Zaapi from an internal system.

**The full API reference lives at** [**docs.zaapi.com**](https://docs.zaapi.com/)**.** This page is the short orientation: what the API covers, how to get a key, and where to go next.

### What you can work with

| Resource                 | What you can do                                                                     |
| ------------------------ | ----------------------------------------------------------------------------------- |
| **Tickets**              | List and read tickets, update custom fields, close them                             |
| **Conversations**        | Find conversations by id or contact, mark them read, apply and remove labels        |
| **Contacts**             | Read, list, search and create contacts, and update their custom fields              |
| **Messages**             | List and search customer messages, send messages, read and create internal comments |
| **Accounts**             | List the channel inboxes connected to your store, with health status                |
| **Users, Teams, Labels** | Read-only lists of your seats, teams and labels                                     |

Everything is scoped to a single store — the API key determines which one, so there's no store parameter anywhere.

### Getting started

#### 1. Create an API key

Go to **Settings → Developers → API Keys** in the Zaapi app, click **Add API key**, name it, and choose the scopes it should have.

The key is shown **once**, at creation — copy it before closing the dialog. Keys expire after **6 months**, and you can rotate, edit or delete them at any time.

#### 2. Make a request

The API is at `https://openplatform.zaapi.co/v1`. Authenticate by passing your key in the `x-api-key` header — there's no OAuth flow, no bearer token and no token refresh.

```bash
curl https://openplatform.zaapi.co/v1/tickets \
  -H "x-api-key: zaapi_***"
```

That returns your current ticket queue — open, non-spam, not snoozed.

#### 3. Read the reference

[docs.zaapi.com](https://docs.zaapi.com/) documents every endpoint with parameters, response schemas and copy-paste examples in several languages.

### Scopes

A key carries only the permissions you grant it, as `resource:read` and `resource:write` pairs — `tickets:read`, `contacts:write`, and so on. Selecting a write scope automatically includes the matching read scope.

Grant the minimum you need: a read-only key can't send a message to a customer or close a ticket by mistake.

See [Scopes](https://docs.zaapi.com/#section/Scopes) for the full list and which endpoints each one covers.

### Conventions

|                    |                                                                                                                                            |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **Base URL**       | `https://openplatform.zaapi.co/v1`                                                                                                         |
| **Authentication** | `x-api-key` header                                                                                                                         |
| **Pagination**     | Cursor-based. Pass `pageSize` (max 100) and the `cursor` from the previous response.                                                       |
| **Rate limits**    | 20 requests/second sustained, 40/second burst, 100,000 requests/day per key                                                                |
| **Errors**         | Standard HTTP codes with a consistent JSON envelope — `400` validation, `401` authentication, `403` scope, `404` not found, `409` conflict |

Details, including how to expand related records to save follow-up calls, are in [Conventions](https://docs.zaapi.com/#section/Conventions).

### Webhooks

Rather than polling for changes, you can have Zaapi POST to an HTTPS endpoint you control when something happens in your store. Subscribable events cover messages received and sent, tickets opened, reopened, closed, assigned and unassigned, ticket and contact field updates, and AI escalations.

Set them up in **Settings → Developers → Webhooks**. Each webhook has a signing secret — shown once at creation, used to verify that deliveries genuinely came from Zaapi. Failed deliveries are retried, and delivery logs are kept for 7 days.

Store owners and admins can manage webhooks; the Developers page isn't shown to other roles.

Full setup, payload format, signature verification and retry behaviour: [Webhooks](https://docs.zaapi.com/#section/Webhooks).

### Prefer to skip the code?

If you want to work with your Zaapi data from an AI assistant rather than write an integration, the **Zaapi MCP** server puts the same API behind Claude, Claude Code, Cursor and other MCP-compatible tools — no code required. It uses the same API keys and scopes.

### Getting help

* [**docs.zaapi.com**](https://docs.zaapi.com/) — the complete API reference
* [**Getting started**](https://docs.zaapi.com/#section/Getting-started) — key creation, request format, and the common errors explained
* Stuck on something the reference doesn't cover? Contact Zaapi support with the endpoint you're calling and the error you're getting back.