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.
-
Select New key and name it after what will use it, for example "Backend".
-
Choose its Permissions. Give only what it needs:
Permission Scope Allows Chat with agents chatStart conversations and send messages Read conversations conversations.readList and read conversations and messages Read contacts contacts.readList and read contacts Add and change contacts contacts.writeCreate and update contacts Read agents agents.readList and read agents Change agents agents.writeUpdate an agent's settings -
Optionally limit it to only these agents. With none checked, it can use every agent.
-
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:
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.
- 1POST /agents/{agentId}/conversationsreturns a conversation id
- 2POST /conversations/{id}/messagesyour customer's message
- 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.
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" }'
{ "id": "0199…", "agentId": "…", "channel": "api", "status": "new", "title": null,
"contactId": "…", "createdAt": "…", "lastMessageAt": "…" }
Send a message and wait for the whole reply:
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?" }'
{
"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:
type | Meaning |
|---|---|
start | The reply has begun; includes citations |
activity | An action is running, for example "Checking your order…" |
delta | The next piece of text: append text |
done | Finished |
error | Failed; message is safe to show. Nothing is charged. |
received | A person has this conversation; no agent reply follows |
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
| Request | Returns |
|---|---|
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
| Request | Permission | Does |
|---|---|---|
GET /agents · GET /agents/{id} | agents.read | Read agents |
PATCH /agents/{id} | agents.write | Change any of name, description, instructions, modelId, temperature |
GET /contacts?search=&limit=&cursor= | contacts.read | List or search contacts |
GET /contacts/{id} | contacts.read | One contact |
POST /contacts · PATCH /contacts/{id} | contacts.write | Create 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.
{ "statusCode": 403, "code": "API_SCOPE", "message": "…", "requestId": "…" }
| Status | code | Meaning |
|---|---|---|
| 400 | VALIDATION_FAILED | The body or query is invalid; details.violations lists each problem |
| 401 | API_KEY_INVALID | No key, an unknown key, or a revoked key |
| 402 | OUT_OF_CREDITS | The workspace has no credits left |
| 403 | API_SCOPE | The key lacks that permission, or that agent |
| 403 | API_NOT_ON_PLAN | The workspace's plan does not include the API |
| 429 | API_RATE_LIMITED | Over 60 requests a minute; wait for Retry-After |
Include the requestId when you contact support; it points us straight to the request.
Related
Something not working as described here? See Troubleshooting.