Zaapi Open API Platform (1.0.0)

1. Generate an API key

API keys are created and managed by you, inside the Zaapi App. There is no separate application or approval step, and no client secret to exchange.

1. Open the Zaapi App and go to Settings → Developers.
2. Select Add API key.
3. Give the key a name that describes where it will be used, for example Warehouse sync or Reporting dashboard.
4. Tick the scopes the key should have — at least one is required. A key can only call endpoints covered by the scopes you grant it — see Scopes below. Ticking a write scope also grants the matching read scope.
5. Select Create, then copy the key.

The key is shown once, at creation. Store it somewhere safe before closing the dialog — you will not be able to see it again. Keys start with zaapi_. The table on the Developers page only shows a masked value (zaapi_•••••••• plus the last four characters).

If you lose the secret you don't have to start over. Use Rotate key on that row: it issues a new secret, keeps the name and scopes, and restarts the 6-month expiry.

Keys expire 6 months after they are created or last rotated. The expiry date is on the Developers page. An expired key is rejected with 401. Rotate before that date if the integration should keep working.

2. Send the key with every request

Pass the key in the x-api-key header. There is no bearer token, no Authorization header, and no token refresh — the key itself is the credential. A signed request, and the 401 / 403 bodies you get back when the header is missing, unrecognised, or under-scoped, are shown in the samples panel.

Every request is authenticated and scope-checked before it reaches your store's data. A request with no x-api-key header, or an unrecognised, inactive, expired, or deleted key, is rejected with 401. A valid key missing the scope an endpoint requires is rejected with 403. On success the request is scoped to your store, so a caller can only ever see their own data.

3. Keep the key safe

A key carries the scopes you granted it and acts on your store, so treat it like a password.

• Send it only from a server you control. Never embed a key in a mobile app, a browser page, or any client-side code, where it can be read by anyone.
• Use a separate key per integration. If one has to be deleted, the others keep working.
• Grant only the scopes an integration actually needs. A reporting tool that only reads data should not hold write scopes. The form has a Read only shortcut that selects every read scope and none of the write scopes.
• Rotate a key if it may have been exposed, if you lost the secret, or before it expires. Rotating is the usual response to a leaked or lost key, and it restarts the 6-month expiry.
• Delete a key when the integration using it is being retired.

4. Edit, rotate, or delete a key

Each of these lives on the key's ⋮ menu on Settings → Developers.

Editing renames the key or changes its scopes. The secret itself does not change, and nothing is shown again — integrations already using the key keep working. Taking a scope away starts failing those calls with 403 on the next request.

Rotating issues a new secret for the same key and leaves the name and scopes untouched. The new secret is shown once, the same as at creation, and the 6-month expiry restarts today.

The old secret stays valid for two hours. Use that window to deploy the new one. After two hours, anything still sending the old secret fails with 401. If your integration reads the key from a secrets store it can re-read without restarting, update it there and the cutover is immediate.

If two hours is not enough, add a second key with the same scopes, move the integration onto it, confirm it's working, then delete the first.

Rotate when a key has been lost, when it may have been exposed, or before it expires.

Deleting removes a key permanently. It takes effect immediately — the next request using that key fails with 401 — and it cannot be undone. Delete when the integration using a key is being retired for good.

Who can do this. Store owners and admins can add, edit, rotate, and delete API keys. The Developers page is not shown to other roles.

5. Handle the common errors

Failed requests return the same envelope. 401 and 403 from a missing, unrecognised, or under-scoped x-api-key header are shown in the samples panel. Application errors (400, 404, and endpoint-specific failures) look like:

{
  "requestId": "<requestId>",
  "requestReceivedAt": "1757580000000",
  "storeId": "<id>",
  "error": {
    "message": "Resource not found",
    "statusCode": 404
  }
}

Four failures can happen on any request, so they are described here once rather than repeated on every endpoint below.

400 — the request was malformed or failed validation. Check the request body and query parameters against the endpoint's schema. error.message names the offending field.

401 — the x-api-key header is missing, or the key is not recognised, inactive, expired, or has been deleted. Check that the header is being sent and that the key is correct. If this started more than two hours after a rotation, the old secret is still deployed somewhere. If the key was lost, rotate it. If it expired, rotate it before the next call. If it was deleted, add a new key.

403 — the x-api-key header is valid but was not granted the scope this endpoint requires. Check the scope listed on the endpoint. Edit the key on Settings → Developers to add that scope, or use a different key that already has it.

404 — no such record in your store, or the key cannot reach it. Check the ID. A record belonging to another store returns 404, not 403.

409 — the request conflicts with current store data. Returned when updating a ticket or contact field with an out-of-date resource timestamp, or when creating a contact whose email or phone is already on the store. Re-read the resource and retry with its latest field timestamp, or use a different email or phone.

Treat 401 and 403 as permanent. Retrying with the same key produces the same result, and a retry loop against 401 will simply generate noise. Both need a change to the key itself.

Endpoints that can fail in ways specific to what they do — a conflicting write, for example — document those responses individually.

Scopes decide what a key is allowed to do. You choose them when the key is created, and you can change them later with Edit on that key. Rotating a key preserves its scopes. Granting a write scope also grants the matching read scope; removing a read scope removes the matching write scope.

Each resource has a read and write pair. Write scopes for accounts, users, labels, and teams are defined so keys issued today do not need reissuing when those routes land.

• tickets:read — read tickets and ticket field definitions
• tickets:write — assign tickets, update ticket fields, and close tickets
• conversations:read — read conversations
• conversations:write — mark conversations read and update labels
• contacts:read — read and search contacts, and read contact field definitions
• contacts:write — create contacts and update contact fields
• messages:read — read, search messages, and read internal comments
• messages:write — send messages, including email and WhatsApp templates, and create internal comments
• accounts:read — read channel accounts and WhatsApp message templates
• accounts:write — reserved for future write endpoints
• users:read — read store users
• users:write — reserved for future write endpoints
• labels:read — read labels
• labels:write — reserved for future write endpoints
• teams:read — read teams
• teams:write — reserved for future write endpoints

Each endpoint below states the scope it requires.

URLs. Every path is relative to the versioned base URL, https://openplatform.zaapi.co/v1. Record IDs travel as query parameters on reads and in the request body on writes, rather than as path segments.

Rate limits. Each key is limited to:

• Throttle — 20 requests per second
• Burst — 40 requests per second
• Quota — 100,000 requests per day

Response envelope. Successful responses wrap the result in data:

{
  "requestId": "<requestId>",
  "requestReceivedAt": "1757580000000",
  "storeId": "<id>",
  "data": { }
}

requestReceivedAt is Unix time in milliseconds, as a string. In JavaScript:

new Date(Number(body.requestReceivedAt))

A single-resource read puts an object in data. A list puts an array in data, including GET /conversations when you look up one conversation by id — that call still returns a one-item array. Failed requests use the same envelope with error instead of data.

Some writes return the updated resource. Others acknowledge the write with { "message": "OK" } inside data and do not echo the resource: marking a conversation read, updating conversation labels, updating a contact field, sending a plain-text message, sending an email, sending a WhatsApp template, and adding an internal comment.

Pagination

Collections that can grow without bound are cursor-paginated. Walk them with pageSize and cursor.

Query parameters on paginated endpoints:

• pageSize — items per page. Optional. Defaults to 20, except GET /messages where it defaults to 15. Maximum is 100 on every endpoint that accepts pageSize. GET /messages/search and GET /contacts/search do not accept pageSize; each page contains 10 results. A value above 100, below 1, or that is not a whole number is rejected with 400.
• cursor — opaque token from the previous page. Omit it on the first page. Pass the previous x-pagination-next-cursor value back verbatim — do not parse, wrap, or reconstruct it. A malformed cursor is rejected with 400.

The response body stays a JSON array inside data. Pagination metadata is returned as headers, not in the body:

• x-pagination-page-size
• x-pagination-next-cursor — present when another page may be available. A page can contain fewer than pageSize items and still include this header. When it is present, request the next page with the same filters and pageSize, plus cursor set to this value. Stop only when the header is missing.

First page:

GET /v1/labels?pageSize=20

Next page — same filters and pageSize, plus the cursor from x-pagination-next-cursor:

GET /v1/labels?pageSize=20&cursor=<cursor>

Keep pageSize and every filter the same across pages. Changing them mid-walk can reject the cursor, skip rows, or repeat rows.

These endpoints are cursor-paginated. All of them accept a pageSize of up to 100:

• POST /tickets/list — newest message first
• GET /conversations — most recent last message first
• POST /contacts/list — most recently updated first without search; relevance first with search
• GET /messages — newest first, default pageSize 15
• GET /messages/internal-comments — newest first
• GET /labels — most recently updated first
• GET /teams — oldest first
• GET /accounts — oldest first

GET /messages/search and GET /contacts/search are also cursor-paginated, in relevance order. Each page contains 10 results. Do not send pageSize. Pass cursor from x-pagination-next-cursor to continue.

Small per-store catalogs are returned in full, with no pagination parameters or x-pagination-* headers:

• GET /tickets/fields — all ticket field definitions, display order
• GET /contacts/fields — all contact field definitions, display order
• GET /users — every user on the store

GET /accounts/whatsapp-templates returns at most 100 templates for one WhatsApp account. It does not take pageSize or cursor.

Expanding related records

Pass expand as a query parameter to resolve related ids into small objects. Send a comma-separated list (expand=account,assignee) or repeat the key (expand=account&expand=assignee). Values are exact and case-sensitive. An unknown value is rejected with 400 (Invalid expand value: …).

Each endpoint accepts only the values listed on it. expand=assignee is valid on a ticket and rejected on a conversation — assignee lives on tickets, not conversations.

Two shapes are used:

Replace the id. On tickets and conversations, the id field is omitted and a related object takes its place.

GET /v1/tickets?ticketId=<id>
# { "accountId": "<id>", "assigneeUserId": "<id>" }

GET /v1/tickets?ticketId=<id>&expand=account,assignee
# { "account": { "id": "<id>", "name": "Line Shop", "channel": "line" },
#   "assignee": { "id": "<id>", "name": "Nadia Prasert" } }

Add a sibling, or replace a nested id. On messages, conversationId stays on the record and account / conversation / sentBy are added beside it. There is no accountId on the message. On an internal comment, expand=createdBy replaces noteData.createdBy in place. On a team, expand=users turns each member id into { id, name } when that user exists on the store — otherwise the raw id is left as-is. On a user, expand=role adds role { id, name } and omits roleId.

If a related record cannot be resolved, the expand is skipped for that field and the original id remains.

Allowed expand values:

Endpoint	Values	Effect
Ticket reads and writes	account, conversation, assignee, handledBy	Replaces accountId, conversationId, assigneeUserId, handledBy
GET /tickets/fields	accounts	Adds accounts (name, accountId, channel)
GET /conversations	account	Replaces accountId
GET /messages	sentBy, conversation, account	Adds those objects. conversationId stays
GET /messages/internal-comments	createdBy, conversation, account	Replaces noteData.createdBy; adds conversation and account
GET /users	role	Adds role; omits roleId
GET /teams	users	Each member becomes { id, name } when known

Related channel objects are { id, name, channel }. Related users are { id, name }, except message sentBy / createdBy, which are { userId, name, roleId }.

Timestamps. Resource timestamps are ISO 8601 in UTC. Envelope requestReceivedAt is Unix milliseconds as a string — see Response envelope above.

Errors. See Handle the common errors above for the shared error shape and the 400, 401, 403, 404, and 409 responses that apply across endpoints.

Install the @zaapi/open-api-mcp server so an assistant such as Claude can call this API on your store. Each operation becomes a tool. The server sends the API key you configure, and that key's scopes decide what the assistant can do.

The assistant starts the server with npx, which comes with Node.js. Install Node.js on the machine that runs the assistant.

1. Create a key for the assistant

1. Open the Zaapi App and go to Settings → Developers.
2. Select Add API key.
3. Name the key for the assistant, for example Claude.
4. Tick the scopes the assistant should have. A reporting assistant that only reads data should not hold write scopes.
5. Select Create, then copy the key.

The key is shown once. Put it in the config below, on the machine that runs the assistant. The same rules in Keep the key safe apply.

2. Add the server in Claude Desktop

Claude Desktop runs the server on your machine.

1. Open Claude Desktop.
2. From the Claude menu in the menu bar, select Settings.
3. Open Developer and select Edit Config.

That opens claude_desktop_config.json. Edit Config creates the file when it is missing.

• macOS — ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows — %APPDATA%\Claude\claude_desktop_config.json

Add a zaapi entry. If mcpServers already lists other servers, add zaapi next to them.

{
  "mcpServers": {
    "zaapi": {
      "command": "npx",
      "args": ["-y", "@zaapi/open-api-mcp"],
      "env": {
        "ZAAPI_API_KEY": "zaapi_…"
      }
    }
  }
}

Save the file. Quit Claude from the menu, then open it again so it reloads the config. In a new chat, Zaapi is listed with the assistant's tools.

Variable	Required	What to set
ZAAPI_API_KEY	Yes	The key from Settings → Developers. The server sends it as x-api-key. Keys start with zaapi_.
ZAAPI_BASE_URL	No	Defaults to https://openplatform.zaapi.co. Set https://openplatform-staging.zaapi.co to call staging.

A missing, expired, or under-scoped key fails the tool call the same way a direct request fails. See Handle the common errors.

Other assistants that accept an mcpServers config use the JSON in Add the server in Claude Desktop.

Individual pieces of work raised against a conversation — listing, reading, assigning, updating fields, and closing.

Channel conversations — finding by conversation or contact, marking read, and applying label changes.

Customer contacts — reading, searching, listing, creating, and updating custom fields.