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…):
- 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 | GET /countries | List countries and their languages |
| Catalog | GET /trades | Catalog of trades open to the API |
| Catalog | GET /trades/{trade_id} | Trade details (services, timings, consent text) |
| Catalog | GET /trades/{trade_id}/services | Detailed service catalog of a trade |
| Catalog | POST /trade-matches | Find the trades that match a need |
| Catalog | GET /places | Check a place (town or postcode) |
| Catalog | GET /consent-texts/{version} | Read a version of the consent text |
| Requests | POST /requests | Create a draft request |
| Requests | GET /requests | List your requests |
| Requests | GET /requests/{request_id} | Read a request and its status |
| Requests | PATCH /requests/{request_id} | Update a draft |
| Requests | DELETE /requests/{request_id} | Cancel a request that has not been sent |
| Requests | POST /requests/{request_id}/confirmation | Start the confirmation by the person |
| Requests | GET /requests/{request_id}/events | Status history of a request |
| Requests | POST /sandbox/requests/{request_id}/simulate | Move a test request forward |
| Agent | POST /agent/conversations | Start a conversation with the Kelki Agent |
| Agent | GET /agent/conversations/{conversation_id} | Read the state of a conversation |
| Agent | POST /agent/conversations/{conversation_id}/messages | Send a message to the Kelki Agent |
| Webhooks (reference) | GET /webhook-endpoints | List your webhook endpoints |
| Webhooks (reference) | POST /webhook-endpoints | Declare 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}/test | Send a “ping” event |
| Webhooks (reference) | POST /webhook-endpoints/{endpoint_id}/rotate-secret | Replace the signing secret |
| Account | GET /account | Read the account, plan and limits |
| Account | GET /account/usage | Daily usage |
| OAuth | POST /oauth/token | Get an access token (client credentials) |
| OAuth | 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: |
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. |