Skip to content
KelkiDevelopers

API reference

Find the right professional and pass on a call-back request to them, with the person's explicit consent.

Generated from the OpenAPI 3.1.0 specification — version 1.0.0. Address: https://kelki.ai/api/v1.

The Kelki Agent API lets a third-party application (concierge service, property management, assistant, CRM…):

  1. find the trade and the service that match a need, in the person's language and country;
  2. check the place of the job;
  3. prepare a draft request and show it to the person with the consent text;
  4. have the person confirm the request (link sent by e-mail, or consent attestation by an approved partner);
  5. track the request: transmitted, sold to a single professional, call-back confirmed by the person.

Same rules as the “Call me back” form, the MCP connector (https://kelki.ai/mcp) and the Kelki Agent. No response contains a professional's contact details, nor where the request came from.

Errors in RFC 9457 format (application/problem+json). Cursor pagination. Idempotency-Key required on creations. Rate limited per key (RateLimit and RateLimit-Policy headers).

Free for partners. Governed by three texts (12/11/2026, /developers/en/terms/): API terms of use, data processing agreement (GDPR article 28: Kelki is the controller, the partner a processor for collecting and sending requests), acceptable use policy.

Sections

SectionRoutePurpose
CatalogGET /countriesList countries and their languages
CatalogGET /tradesCatalog of trades open to the API
CatalogGET /trades/{trade_id}Trade details (services, timings, consent text)
CatalogGET /trades/{trade_id}/servicesDetailed service catalog of a trade
CatalogPOST /trade-matchesFind the trades that match a need
CatalogGET /placesCheck a place (town or postcode)
CatalogGET /consent-texts/{version}Read a version of the consent text
RequestsPOST /requestsCreate a draft request
RequestsGET /requestsList your requests
RequestsGET /requests/{request_id}Read a request and its status
RequestsPATCH /requests/{request_id}Update a draft
RequestsDELETE /requests/{request_id}Cancel a request that has not been sent
RequestsPOST /requests/{request_id}/confirmationStart the confirmation by the person
RequestsGET /requests/{request_id}/eventsStatus history of a request
RequestsPOST /sandbox/requests/{request_id}/simulateMove a test request forward
AgentPOST /agent/conversationsStart a conversation with the Kelki Agent
AgentGET /agent/conversations/{conversation_id}Read the state of a conversation
AgentPOST /agent/conversations/{conversation_id}/messagesSend a message to the Kelki Agent
Webhooks (reference)GET /webhook-endpointsList your webhook endpoints
Webhooks (reference)POST /webhook-endpointsDeclare a webhook endpoint
Webhooks (reference)GET /webhook-endpoints/{endpoint_id}Read a webhook endpoint
Webhooks (reference)DELETE /webhook-endpoints/{endpoint_id}Delete a webhook endpoint
Webhooks (reference)POST /webhook-endpoints/{endpoint_id}/testSend a “ping” event
Webhooks (reference)POST /webhook-endpoints/{endpoint_id}/rotate-secretReplace the signing secret
AccountGET /accountRead the account, plan and limits
AccountGET /account/usageDaily usage
OAuthPOST /oauth/tokenGet an access token (client credentials)
OAuthPOST /oauth/revokeRevoke an access token (RFC 7009)

Authentication

ApiKey

The partner's API key, in Authorization. Never in the address. Stored hashed by Kelki.

Format: kk_live_… or kk_test_…

OAuth2

Client credentials (RFC 6749 § 4.4). Opaque 15-minute token.

Token: https://kelki.ai/api/v1/oauth/token

ScopeAccess
catalog.readRead the catalog, the account and usage.
requests.readRead your requests and their statuses.
requests.writeCreate, update, cancel and have your requests confirmed.
consent.attestAttest the person's consent (approved partners under contract).
agentConverse with the Kelki Agent.
webhooks.manageManage your webhook endpoints.

ClientBasic

client_id and client_secret of the OAuth client (/oauth/token endpoint only).

Common error responses

CodeNameDescriptionContent
400BadRequest

Malformed request (invalid JSON, unknown parameter, body too large).

Problem
401Unauthorized

Missing, invalid, expired or revoked credentials.

Problem
403Forbidden

Missing scope, account not enabled for live, country not open, account suspended.

Problem
404NotFound

Unknown resource, or one belonging to another account or another mode (same response).

Problem
409Conflict

Impossible transition (e.g. updating a request already transmitted) or idempotent request in progress.

Problem
422ValidationFailed

Value refused by the form's rules (closed lists, place, contact details, consent, anti-abuse limits).

Problem
429TooManyRequests

Rate or quota exceeded.

Problem
503ServiceUnavailable

Service paused or under maintenance (e.g. agent paused, live creation suspended).

Problem

Schemas

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

FieldError

FieldTypeRequiredDescription
pointerstringyes

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

detailstringyes
allowedarray of stringno

Accepted values, when the list is closed.