# 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`. [openapi.yaml](https://kelki.ai/assets/developers/openapi.yaml)[openapi.json](https://kelki.ai/assets/developers/openapi.json) The Kelki Agent API lets a third-party application (concierge service, property management, assistant, CRM…): - find the trade and the service that match a need, in the person's language and country; - check the place of the job; - prepare a draft request and show it to the person with the consent text; - have the person confirm the request (link sent by e-mail, or consent attestation by an approved partner); - 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 | Section | Route | Purpose | | [Catalog](https://kelki.ai/developers/en/reference/catalog/#listCountries) | GET `/countries` | List countries and their languages | | [Catalog](https://kelki.ai/developers/en/reference/catalog/#listTrades) | GET `/trades` | Catalog of trades open to the API | | [Catalog](https://kelki.ai/developers/en/reference/catalog/#getTrade) | GET `/trades/{trade_id}` | Trade details (services, timings, consent text) | | [Catalog](https://kelki.ai/developers/en/reference/catalog/#listTradeServices) | GET `/trades/{trade_id}/services` | Detailed service catalog of a trade | | [Catalog](https://kelki.ai/developers/en/reference/catalog/#matchTrades) | POST `/trade-matches` | Find the trades that match a need | | [Catalog](https://kelki.ai/developers/en/reference/catalog/#searchPlaces) | GET `/places` | Check a place (town or postcode) | | [Catalog](https://kelki.ai/developers/en/reference/catalog/#getConsentText) | GET `/consent-texts/{version}` | Read a version of the consent text | | [Requests](https://kelki.ai/developers/en/reference/requests/#createRequest) | POST `/requests` | Create a draft request | | [Requests](https://kelki.ai/developers/en/reference/requests/#listRequests) | GET `/requests` | List your requests | | [Requests](https://kelki.ai/developers/en/reference/requests/#getRequest) | GET `/requests/{request_id}` | Read a request and its status | | [Requests](https://kelki.ai/developers/en/reference/requests/#updateRequest) | PATCH `/requests/{request_id}` | Update a draft | | [Requests](https://kelki.ai/developers/en/reference/requests/#cancelRequest) | DELETE `/requests/{request_id}` | Cancel a request that has not been sent | | [Requests](https://kelki.ai/developers/en/reference/requests/#confirmRequest) | POST `/requests/{request_id}/confirmation` | Start the confirmation by the person | | [Requests](https://kelki.ai/developers/en/reference/requests/#listRequestEvents) | GET `/requests/{request_id}/events` | Status history of a request | | [Requests](https://kelki.ai/developers/en/reference/requests/#simulateRequestStatus) | POST `/sandbox/requests/{request_id}/simulate` | Move a test request forward | | [Agent](https://kelki.ai/developers/en/reference/agent/#createConversation) | POST `/agent/conversations` | Start a conversation with the Kelki Agent | | [Agent](https://kelki.ai/developers/en/reference/agent/#getConversation) | GET `/agent/conversations/{conversation_id}` | Read the state of a conversation | | [Agent](https://kelki.ai/developers/en/reference/agent/#sendConversationMessage) | POST `/agent/conversations/{conversation_id}/messages` | Send a message to the Kelki Agent | | [Webhooks (reference)](https://kelki.ai/developers/en/reference/webhooks/#listWebhookEndpoints) | GET `/webhook-endpoints` | List your webhook endpoints | | [Webhooks (reference)](https://kelki.ai/developers/en/reference/webhooks/#createWebhookEndpoint) | POST `/webhook-endpoints` | Declare a webhook endpoint | | [Webhooks (reference)](https://kelki.ai/developers/en/reference/webhooks/#getWebhookEndpoint) | GET `/webhook-endpoints/{endpoint_id}` | Read a webhook endpoint | | [Webhooks (reference)](https://kelki.ai/developers/en/reference/webhooks/#deleteWebhookEndpoint) | DELETE `/webhook-endpoints/{endpoint_id}` | Delete a webhook endpoint | | [Webhooks (reference)](https://kelki.ai/developers/en/reference/webhooks/#testWebhookEndpoint) | POST `/webhook-endpoints/{endpoint_id}/test` | Send a “ping” event | | [Webhooks (reference)](https://kelki.ai/developers/en/reference/webhooks/#rotateWebhookSecret) | POST `/webhook-endpoints/{endpoint_id}/rotate-secret` | Replace the signing secret | | [Account](https://kelki.ai/developers/en/reference/account/#getAccount) | GET `/account` | Read the account, plan and limits | | [Account](https://kelki.ai/developers/en/reference/account/#getAccountUsage) | GET `/account/usage` | Daily usage | | [OAuth](https://kelki.ai/developers/en/reference/oauth/#createAccessToken) | POST `/oauth/token` | Get an access token (client credentials) | | [OAuth](https://kelki.ai/developers/en/reference/oauth/#revokeAccessToken) | POST `/oauth/revoke` | Revoke 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` | Scope | Access | | `catalog.read` | Read the catalog, the account and usage. | | `requests.read` | Read your requests and their statuses. | | `requests.write` | Create, update, cancel and have your requests confirmed. | | `consent.attest` | Attest the person's consent (approved partners under contract). | | `agent` | Converse with the Kelki Agent. | | `webhooks.manage` | Manage your webhook endpoints. | ### `ClientBasic` client_id and client_secret of the OAuth client (/oauth/token endpoint only). ## Common error responses | Code | Name | Description | Content | | `400` | `BadRequest` | Malformed request (invalid JSON, unknown parameter, body too large). | Problem | | `401` | `Unauthorized` | Missing, invalid, expired or revoked credentials. | Problem | | `403` | `Forbidden` | Missing scope, account not enabled for live, country not open, account suspended. | Problem | | `404` | `NotFound` | Unknown resource, or one belonging to another account or another mode (same response). | Problem | | `409` | `Conflict` | Impossible transition (e.g. updating a request already transmitted) or idempotent request in progress. | Problem | | `422` | `ValidationFailed` | Value refused by the form's rules (closed lists, place, contact details, consent, anti-abuse limits). | Problem | | `429` | `TooManyRequests` | Rate or quota exceeded. | Problem | | `503` | `ServiceUnavailable` | Service paused or under maintenance (e.g. agent paused, live creation suspended). | Problem | ## Schemas ### `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: `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_id` | string | yes | | | `errors` | array of FieldError | no | | ### `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. | ## About this page - URL : https://kelki.ai/developers/en/reference/ - Language : en - fr : https://kelki.ai/developers/fr/reference/ - en : https://kelki.ai/developers/en/reference/ - x-default : https://kelki.ai/developers/ - Portal : https://kelki.ai/developers/llms.txt