Get an API key
Keys are made by a workspace owner or admin in the console.
- 1Open Settings → API keys and click Create API key.
- 2Name it, tick what it may do (Chat, Read conversations) and pick its agents.
- 3Copy the key. It starts with
cvn_sk_and is shown only once.
Send it on every request as Authorization: Bearer cvn_sk_…. To check it works, call GET /v1/me. GET /v1/agents lists the agents it can reach, with their IDs.
Send a message
Post the customer's message to an agent. The reply comes back in the same response.
curl https://api.cevanos.ai/v1/agents/AGENT_ID/chat \
-H "Authorization: Bearer $CEVANOS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"message": "When are you open on Sunday?"}'{
"data": {
"outcome": "answered",
"reply": "We are closed on Sundays. We open again Monday at 9am.",
"conversation_id": "01a12779-b041-728a-9b1d-2797cc84a905",
"message_id": "01a12779-defc-7a33-88d5-5a79cddb6d5f",
"usage": { "credits": 3.7 }
}
}outcome is answered when the agent replied. It can also be handed_over (a person will take it from here), could_not_answer, or no_reply (someone on your team is already handling the conversation).
Continue a conversation
Send back the conversation_id from the last reply. Leave it out to start a new conversation.
curl https://api.cevanos.ai/v1/agents/AGENT_ID/chat \
-H "Authorization: Bearer $CEVANOS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"message": "And on Saturday?",
"conversation_id": "01a12779-b041-728a-9b1d-2797cc84a905"}'Stream the reply
Add "stream": true to get the reply word by word as server-sent events.
| Event | What to do |
|---|---|
delta | Add its text to what you show. |
restart | Clear what you have shown; the agent is starting its answer again. |
done | The final reply, the same object a normal request returns. |
error | The reply could not be finished. |
Read conversations
Needs a key with Read conversations. You see the conversations your agents had through the API.
Newest first, 20 at a time. Pass next_cursor back as ?cursor= for the next page.
Every message in one conversation, oldest first.
Rate an answer
Pass on your customer's thumbs up or down for an answer, using its message_id. Send helpful or not_helpful; rating again replaces the earlier rating. It needs the Chat permission.
curl -X PATCH \
https://api.cevanos.ai/v1/agents/AGENT_ID/conversations/CONVERSATION_ID/messages/MESSAGE_ID/feedback \
-H "Authorization: Bearer $CEVANOS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"rating": "helpful"}'As in the chat widget, helpful on the last answer closes the conversation.
Credits and limits
Each reply uses credits from your plan, like any other chat. usage.credits tells you how many. API usage is shown under Plans and billing.
Per key. Responses carry X-RateLimit-Remaining and X-RateLimit-Reset. Over the limit, wait Retry-After seconds.
Errors
Errors come back as { "error": { "code": "…", "message": "…" } }. The ones you'll meet:
| Status | Code | Meaning |
|---|---|---|
| 401 | unauthorized | Missing, wrong or revoked key. |
| 403 | missing_scope | The key can't do this. Tick it when you create the key. |
| 403 | feature_not_in_plan | Your plan doesn't include the API. |
| 404 | agent_not_found | This agent isn't on the key. |
| 404 | message_not_found | Not an agent answer in that conversation. |
| 409 | conversation_not_ongoing | That conversation ended. Start a new one. |
| 429 | rate_limited | Too many requests. Wait and retry. |
Keep your key safe
- Use it only on your server. Never put it in a web page or a mobile app.
- One key per app, so you can replace one without touching the others.
- If a key leaks, rotate it or revoke it in Settings → API keys. The old key stops working straight away.
Ready to try it?
Create a key and send your first message in a couple of minutes.