Skip to content

REST API

Use agents, conversations and contacts from your own systems with an API key.

On this page

The REST API lets your own systems use ikazebot: chat with an agent from your mobile app or backend, read conversations into your CRM, and keep contacts in sync. It is available on paid plans.

  • Base URL: https://api.ikazebot.com/api/v2
  • Format: JSON in, JSON out
  • Rate limit: 60 requests a minute per key
  • Cost: replies cost credits, exactly as in the widget

1. Create an API key

Owners and admins manage keys in Settings → API & webhooks.

  1. Select New key and name it after what will use it, for example "Backend".

  2. Choose its Permissions. Give only what it needs:

    PermissionScopeAllows
    Chat with agentschatStart conversations and send messages
    Read conversationsconversations.readList and read conversations and messages
    Read contactscontacts.readList and read contacts
    Add and change contactscontacts.writeCreate and update contacts
    Read agentsagents.readList and read agents
    Change agentsagents.writeUpdate an agent's settings
  3. Optionally limit it to only these agents. With none checked, it can use every agent.

  4. Create it and copy the key now; it is not shown again. Keys start with ikb_.

Keep keys on your server. Never put an API key in a web page or mobile app bundle; anyone could read it there. Revoke a key at any time from the same page.

2. Authenticate

Send the key as a bearer token on every request:

bash
curl https://api.ikazebot.com/api/v2/agents \
  -H "Authorization: Bearer ikb_your_key"

3. Chat with an agent

Chatting takes two calls: start a conversation, then send messages to it.

  1. 1POST /agents/{agentId}/conversationsreturns a conversation id
  2. 2POST /conversations/{id}/messagesyour customer's message
  3. 3Agent's replywhole, or streamed

Start a conversation. externalUserId is optional: your own id for the person, so their conversations are linked to a contact.

bash
curl -X POST https://api.ikazebot.com/api/v2/agents/AGENT_ID/conversations \
  -H "Authorization: Bearer ikb_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "externalUserId": "customer-1042" }'
json
{ "id": "0199…", "agentId": "…", "channel": "api", "status": "new", "title": null,
  "contactId": "…", "createdAt": "…", "lastMessageAt": "…" }

Send a message and wait for the whole reply:

bash
curl -X POST https://api.ikazebot.com/api/v2/conversations/CONVERSATION_ID/messages \
  -H "Authorization: Bearer ikb_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "content": "Where is my order KS-1042?" }'
json
{
  "conversationId": "…",
  "reply": {
    "id": "…", "role": "assistant",
    "content": "Your order KS-1042 shipped yesterday…",
    "citations": [{ "n": 1, "sourceId": "…", "title": "Delivery times", "url": null }],
    "createdAt": "…"
  }
}

reply is null when a person on your team has taken the conversation over. They answer from the Inbox, not the agent.

Streaming the reply

Add "stream": true to receive the reply word by word as Server-Sent Events, as the widget does. Each event's data is JSON:

typeMeaning
startThe reply has begun; includes citations
activityAn action is running, for example "Checking your order…"
deltaThe next piece of text: append text
doneFinished
errorFailed; message is safe to show. Nothing is charged.
receivedA person has this conversation; no agent reply follows
js
const res = await fetch(`${BASE}/conversations/${id}/messages`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ content: 'Hello', stream: true }),
});
// Read res.body line by line; each "data: {...}" line is one event.

Read conversations

RequestReturns
GET /conversations?agentId=&limit=&cursor=Conversations, newest first
GET /conversations/{id}One conversation
GET /conversations/{id}/messages?limit=&cursor=Its messages, with role user, assistant or human (your team)

Agents and contacts

RequestPermissionDoes
GET /agents · GET /agents/{id}agents.readRead agents
PATCH /agents/{id}agents.writeChange any of name, description, instructions, modelId, temperature
GET /contacts?search=&limit=&cursor=contacts.readList or search contacts
GET /contacts/{id}contacts.readOne contact
POST /contacts · PATCH /contacts/{id}contacts.writeCreate or update: name, email, phone, externalUserId, attributes

Pagination

Lists return { "items": [...], "nextCursor": "…" }. Pass nextCursor back as ?cursor= for the next page. When it is null, you have everything. limit is 1–100, with a default of 50.

Errors

Every error has the same shape. Switch on code, not message; the message is written for people and may change.

json
{ "statusCode": 403, "code": "API_SCOPE", "message": "…", "requestId": "…" }
StatuscodeMeaning
400VALIDATION_FAILEDThe body or query is invalid; details.violations lists each problem
401API_KEY_INVALIDNo key, an unknown key, or a revoked key
402OUT_OF_CREDITSThe workspace has no credits left
403API_SCOPEThe key lacks that permission, or that agent
403API_NOT_ON_PLANThe workspace's plan does not include the API
429API_RATE_LIMITEDOver 60 requests a minute; wait for Retry-After

Include the requestId when you contact support; it points us straight to the request.

Something not working as described here? See Troubleshooting.

Get started free — 50 credits a month