Skip to content
KelkiDevelopers

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

NameInRequiredTypeDescription
Idempotency-Keyheaderyesstring

8 to 64 characters, unique per operation. Same key + same body within 24 h = same response.

pattern ^[A-Za-z0-9_\-]{8,64}$

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

CodeDescriptionContent
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

NameInRequiredTypeDescription
conversation_idpathyesstring

pattern ^conv_[0-9A-Za-z]{20,40}$

Responses

CodeDescriptionContent
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

NameInRequiredTypeDescription
conversation_idpathyesstring

pattern ^conv_[0-9A-Za-z]{20,40}$

Idempotency-Keyheaderyesstring

8 to 64 characters, unique per operation. Same key + same body within 24 h = same response.

pattern ^[A-Za-z0-9_\-]{8,64}$

Request body

application/json — AgentMessage (required)

{
  "choice": "metier:volets-roulants"
}

Responses

CodeDescriptionContent
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

FieldTypeRequiredDescription
countryCountryCodeno
langLanguageCodeno
first_messagestringno

max. 600 chars

referencePartnerReferenceno
end_user_refstringno

pattern ^[A-Za-z0-9_\-]{6,64}$

Conversation

FieldTypeRequiredDescription
idstringyes
objectstringyes

value: conversation

modestringyes

values: test, live

stepstringyes

values: metier, metier_choix, besoin, besoin_libre, delai, lieu, lieu_choix, coordonnees, recap, envoyee

textstringyes

The agent's text; any e-mail or number in it is masked.

choicesarray of Choiceyes
recapstring | nullno

Masked summary (recap step).

consentConsentText or nullno
request_idstring | nullno

Request created after consent: true.

fallbackstring | nullno

form: the agent hands over (budget, model failure); continue with POST /requests.

values: form,

expires_atstring (date-time)yes

Problem

Problem details (RFC 9457), with extension members.

FieldTypeRequiredDescription
typestring (uri)yes

Stable URI of the problem type; it leads to its documentation.

titlestringyes
statusintegeryes

min. 400 · max. 599

detailstringno
instancestring (uri-reference)no
codestringyes

Stable, machine-readable code.

values: invalid_json, invalid_parameter, payload_too_large, unsupported_media_type, invalid_credentials, expired_token, insufficient_scope, live_not_enabled, account_suspended, country_not_available, trade_not_available, not_found, invalid_state, idempotency_in_progress, idempotency_key_reused, validation_failed, consent_missing, consent_version_outdated, contact_limit_reached, duplicate_request, rate_limited, quota_exceeded, agent_paused, live_creation_paused, service_unavailable, internal_error

request_idstringyes
errorsarray of FieldErrorno

AgentMessage

FieldTypeRequiredDescription
textstringno

max. 600 chars

choicestringno

max. 200 chars

dataobjectno
consentbooleanno

value: True

consent_text_versionstringno

pattern ^v\d{4}-\d{2}-\d{2}$

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

FieldTypeRequiredDescription
valuestringyes
labelstringyes
hintstringno

ConsentText

FieldTypeRequiredDescription
versionstringyes

pattern ^v\d{4}-\d{2}-\d{2}$

langLanguageCodeyes
textstringyes

To display word for word, next to a checkbox left unticked by default.

valid_fromstring (date)yes

FieldError

FieldTypeRequiredDescription
pointerstringyes

JSON Pointer (RFC 6901) of the field at fault.

detailstringyes
allowedarray of stringno

Accepted values, when the list is closed.