REST API

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.

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.

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.

Responses

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

{
  "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

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:

{ "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.

Getting started

Dashboard

Knowledge

AI agent

Install on your website

Inbox

Leads, tickets and contacts

Automate

Integrations

Connect AI agents

Workspace settings

Billing and plans

Authenticate

Endpoints

Responses

Ask the AI agent

Errors

Limits

​Authenticate

​Endpoints

​Responses

​Ask the AI agent

​Errors

​Limits

​Related topics

Authenticate

Endpoints

Responses

Ask the AI agent

Errors

Limits

Related topics