Agent
Conversation with the Kelki Agent (same brain as the website chat bubble and A2A).
Base URL: https://kelki.ai/api/v1.
POST /agent/conversations— Start a conversation with the Kelki AgentGET /agent/conversations/{conversation_id}— Read the state of a conversationPOST /agent/conversations/{conversation_id}/messages— Send a message to the Kelki Agent
POST /agent/conversations
Start a conversation with the Kelki Agent
Conversation tied to the account and the mode. Forgotten 2 hours after the last message.
Authentication: API key (Authorization: Bearer kk_…) or OAuth 2.0 token (scope agent).
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
Idempotency-Key | header | yes | string | 8 to 64 characters, unique per operation. Same key + same body within 24 h = same response. pattern |
Request body
application/json — ConversationCreate
{
"country": "FR",
"lang": "fr",
"first_message": "Le volet roulant du salon est bloqué en position basse.",
"reference": "resa-2026-0042"
}Responses
| Code | Description | Content |
|---|---|---|
201 | Conversation created, with the agent's first reply. | application/json Conversation |
401 | Missing, invalid, expired or revoked credentials. | application/problem+json Problem |
403 | Missing scope, account not enabled for live, country not open, account suspended. | application/problem+json Problem |
429 | Rate or quota exceeded. | application/problem+json Problem |
503 | Service paused or under maintenance (e.g. agent paused, live creation suspended). | application/problem+json Problem |
Response example
{
"id": "conv_01JC00000000000000000000CV",
"object": "conversation",
"mode": "test",
"step": "metier_choix",
"text": "Lequel de ces professionnels correspond à votre besoin ?",
"choices": [
{
"value": "metier:volets-roulants",
"label": "Réparateur de volets roulants"
},
{
"value": "metier:serrurier",
"label": "Serrurier"
}
],
"recap": null,
"consent": null,
"request_id": null,
"fallback": null,
"expires_at": "2026-11-11T11:43:00Z"
}GET /agent/conversations/{conversation_id}
Read the state of a conversation
Authentication: API key (Authorization: Bearer kk_…) or OAuth 2.0 token (scope agent).
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
conversation_id | path | yes | string | pattern |
Responses
| Code | Description | Content |
|---|---|---|
200 | State of the conversation. | application/json Conversation |
401 | Missing, invalid, expired or revoked credentials. | application/problem+json Problem |
404 | Unknown resource, or one belonging to another account or another mode (same response). | application/problem+json Problem |
POST /agent/conversations/{conversation_id}/messages
Send a message to the Kelki Agent
A message contains only one of: text (free text, goes through the model), choice (value of a button), data (structured fields), consent (the person's consent at the recap step). consent: true creates a draft then starts the e-mail confirmation, exactly like POST /requests + POST /requests/{id}/confirmation (scope requests.write also required).
Authentication: API key (Authorization: Bearer kk_…) or OAuth 2.0 token (scope agent) or OAuth 2.0 token (scope agent, requests.write).
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
conversation_id | path | yes | string | pattern |
Idempotency-Key | header | yes | string | 8 to 64 characters, unique per operation. Same key + same body within 24 h = same response. pattern |
Request body
application/json — AgentMessage (required)
{
"choice": "metier:volets-roulants"
}Responses
| Code | Description | Content |
|---|---|---|
200 | The agent's reply. | application/json Conversation |
401 | Missing, invalid, expired or revoked credentials. | application/problem+json Problem |
403 | Missing scope, account not enabled for live, country not open, account suspended. | application/problem+json Problem |
404 | Unknown resource, or one belonging to another account or another mode (same response). | application/problem+json Problem |
422 | Value refused by the form's rules (closed lists, place, contact details, consent, anti-abuse limits). | application/problem+json Problem |
429 | Rate or quota exceeded. | application/problem+json Problem |
503 | Service paused or under maintenance (e.g. agent paused, live creation suspended). | application/problem+json Problem |
Schemas
ConversationCreate
| Field | Type | Required | Description |
|---|---|---|---|
country | CountryCode | no | |
lang | LanguageCode | no | |
first_message | string | no | max. 600 chars |
reference | PartnerReference | no | |
end_user_ref | string | no | pattern |
Conversation
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | |
object | string | yes | value: |
mode | string | yes | values: |
step | string | yes | values: |
text | string | yes | The agent's text; any e-mail or number in it is masked. |
choices | array of Choice | yes | |
recap | string | null | no | Masked summary (recap step). |
consent | ConsentText or null | no | |
request_id | string | null | no | Request created after |
fallback | string | null | no |
values: |
expires_at | string (date-time) | yes |
Problem
Problem details (RFC 9457), with extension members.
| Field | Type | Required | Description |
|---|---|---|---|
type | string (uri) | yes | Stable URI of the problem type; it leads to its documentation. |
title | string | yes | |
status | integer | yes | min. 400 · max. 599 |
detail | string | no | |
instance | string (uri-reference) | no | |
code | string | yes | Stable, machine-readable code. values: |
request_id | string | yes | |
errors | array of FieldError | no |
AgentMessage
| Field | Type | Required | Description |
|---|---|---|---|
text | string | no | max. 600 chars |
choice | string | no | max. 200 chars |
data | object | no | |
consent | boolean | no | value: |
consent_text_version | string | no | pattern |
CountryCode
Type: string — pattern ^[A-Z]{2}$ · default "FR"
LanguageCode
Type: string — pattern ^[a-z]{2}$
PartnerReference
Your reference (e.g. booking number). No personal data. Returned in webhooks.
Type: string — pattern ^[A-Za-z0-9._:\-]{1,64}$
Choice
| Field | Type | Required | Description |
|---|---|---|---|
value | string | yes | |
label | string | yes | |
hint | string | no |
ConsentText
| Field | Type | Required | Description |
|---|---|---|---|
version | string | yes | pattern |
lang | LanguageCode | yes | |
text | string | yes | To display word for word, next to a checkbox left unticked by default. |
valid_from | string (date) | yes |
FieldError
| Field | Type | Required | Description |
|---|---|---|---|
pointer | string | yes | JSON Pointer (RFC 6901) of the field at fault. |
detail | string | yes | |
allowed | array of string | no | Accepted values, when the list is closed. |