Catalog
Countries, trades, services, places and consent texts. Read-only, same source as the website and the MCP connector.
Base URL: https://kelki.ai/api/v1.
GET /countries— List countries and their languagesGET /trades— Catalog of trades open to the APIGET /trades/{trade_id}— Trade details (services, timings, consent text)GET /trades/{trade_id}/services— Detailed service catalog of a tradePOST /trade-matches— Find the trades that match a needGET /places— Check a place (town or postcode)GET /consent-texts/{version}— Read a version of the consent text
GET /countries
List countries and their languages
Countries covered, languages, currency and availability (live = requests accepted; preparing = catalog readable, requests refused).
Authentication: API key (Authorization: Bearer kk_…) or OAuth 2.0 token (scope catalog.read).
Responses
| Code | Description | Content |
|---|---|---|
200 | List of countries. | application/json CountryList |
401 | Missing, invalid, expired or revoked credentials. | application/problem+json Problem |
429 | Rate or quota exceeded. | application/problem+json Problem |
Response example
{
"object": "list",
"has_more": false,
"next_cursor": null,
"data": [
{
"code": "FR",
"name": "France",
"languages": [
"fr"
],
"default_language": "fr",
"currency": "EUR",
"availability": "live"
},
{
"code": "BE",
"name": "Belgique",
"languages": [
"fr",
"nl"
],
"default_language": "fr",
"currency": "EUR",
"availability": "preparing"
}
]
}GET /trades
Catalog of trades open to the API
Trades open in the country, names in the requested language. Excluded: health trades, trades under review, exclusions specific to the account. national trades are not dispatched by distance.
Authentication: API key (Authorization: Bearer kk_…) or OAuth 2.0 token (scope catalog.read).
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
country | query | no | CountryCode | Country (ISO 3166-1 alpha-2, upper case). Default FR. pattern |
lang | query | no | LanguageCode | Language (ISO 639-1). Default = main language of the country. pattern |
family | query | no | string | Trade family (e.g. depannage, maison). max. 40 chars |
scope | query | no | TradeScope | Scope of the trade. values: |
limit | query | no | integer | Page size (1 to 100). min. 1 · max. 100 · default |
starting_after | query | no | string | Opaque max. 200 chars |
Responses
| Code | Description | Content |
|---|---|---|
200 | One page of the catalog. | application/json TradeList |
400 | Malformed request (invalid JSON, unknown parameter, body too large). | application/problem+json Problem |
401 | Missing, invalid, expired or revoked credentials. | 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 |
Response example
{
"object": "list",
"has_more": true,
"next_cursor": "cur_plombier",
"data": [
{
"id": "plombier",
"name": "Plombier",
"family": "depannage",
"scope": "local",
"page_url": "https://kelki.ai/fr/fr/plombier/"
}
]
}GET /trades/{trade_id}
Trade details (services, timings, consent text)
Equivalent of the MCP tool lister_prestations. The lists are closed, as in the form.
Authentication: API key (Authorization: Bearer kk_…) or OAuth 2.0 token (scope catalog.read).
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
trade_id | path | yes | string | Stable identifier of the trade (historical French slug, e.g. plombier). pattern |
country | query | no | CountryCode | Country (ISO 3166-1 alpha-2, upper case). Default FR. pattern |
lang | query | no | LanguageCode | Language (ISO 639-1). Default = main language of the country. pattern |
Responses
| Code | Description | Content |
|---|---|---|
200 | The trade. | application/json Trade |
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 |
429 | Rate or quota exceeded. | application/problem+json Problem |
Response example
{
"id": "plombier",
"name": "Plombier",
"family": "depannage",
"scope": "local",
"page_url": "https://kelki.ai/fr/fr/plombier/",
"country": "FR",
"lang": "fr",
"services": [
"Recherche de fuite",
"Réparation de fuite",
"Débouchage",
"Remplacement de chauffe-eau",
"Autre besoin"
],
"other_need_label": "Autre besoin",
"delays": [
{
"label": "Dès que possible",
"urgent": true
},
{
"label": "Dans la semaine",
"urgent": false
},
{
"label": "Dans le mois",
"urgent": false
}
],
"consent": {
"version": "v2026-10-18",
"lang": "fr",
"text": "J’accepte que ma demande et mes coordonnées soient transmises à un ou plusieurs professionnels du métier de mon secteur, qui pourront me rappeler à ce sujet.",
"valid_from": "2026-11-10"
}
}GET /trades/{trade_id}/services
Detailed service catalog of a trade
Service catalog of the trade (plain titles, data/datasets/). The titles usable in a request are those with requestable: true; “Autre besoin” (other need) is always possible with other_need.
Authentication: API key (Authorization: Bearer kk_…) or OAuth 2.0 token (scope catalog.read).
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
trade_id | path | yes | string | Stable identifier of the trade (historical French slug, e.g. plombier). pattern |
country | query | no | CountryCode | Country (ISO 3166-1 alpha-2, upper case). Default FR. pattern |
lang | query | no | LanguageCode | Language (ISO 639-1). Default = main language of the country. pattern |
limit | query | no | integer | Page size (1 to 100). min. 1 · max. 100 · default |
starting_after | query | no | string | Opaque max. 200 chars |
Responses
| Code | Description | Content |
|---|---|---|
200 | One page of services. | application/json ServiceList |
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 |
429 | Rate or quota exceeded. | application/problem+json Problem |
Response example
{
"object": "list",
"has_more": false,
"next_cursor": null,
"data": [
{
"id": "recherche-de-fuite",
"label": "Recherche de fuite",
"requestable": true
},
{
"id": "debouchage-canalisation",
"label": "Débouchage de canalisation",
"requestable": true
}
]
}POST /trade-matches
Find the trades that match a need
Equivalent of the MCP tool trouver_service. The need goes in the body (never in the address): it may contain personal details. It is neither stored nor logged. Offer the first 2 or 3 results to the person and let them choose. Read-only: no Idempotency-Key.
Authentication: API key (Authorization: Bearer kk_…) or OAuth 2.0 token (scope catalog.read).
Request body
application/json — TradeMatchQuery (required)
{
"need": "Fuite d'eau sous l'évier de la cuisine",
"country": "FR",
"lang": "fr"
}Responses
| Code | Description | Content |
|---|---|---|
200 | Likely trades, from most to least relevant. | application/json TradeMatchList |
400 | Malformed request (invalid JSON, unknown parameter, body too large). | application/problem+json Problem |
401 | Missing, invalid, expired or revoked credentials. | 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 |
Response example
{
"object": "list",
"has_more": false,
"next_cursor": null,
"data": [
{
"rank": 1,
"trade": {
"id": "plombier",
"name": "Plombier",
"family": "depannage",
"scope": "local",
"page_url": "https://kelki.ai/fr/fr/plombier/"
},
"suggested_services": [
"Recherche de fuite",
"Réparation de fuite"
]
},
{
"rank": 2,
"trade": {
"id": "cuisiniste",
"name": "Cuisiniste",
"family": "maison",
"scope": "local",
"page_url": "https://kelki.ai/fr/fr/cuisiniste/"
},
"suggested_services": []
}
]
}GET /places
Check a place (town or postcode)
Equivalent of the MCP tool verifier_lieu. Returns existing places; use their id in the request.
Authentication: API key (Authorization: Bearer kk_…) or OAuth 2.0 token (scope catalog.read).
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
q | query | yes | string | Town name or postcode (no precise address). min. 2 chars · max. 120 chars |
country | query | no | CountryCode | Country (ISO 3166-1 alpha-2, upper case). Default FR. pattern |
lang | query | no | LanguageCode | Language (ISO 639-1). Default = main language of the country. pattern |
limit | query | no | integer | Page size (1 to 100). min. 1 · max. 100 · default |
Responses
| Code | Description | Content |
|---|---|---|
200 | Matching places. | application/json PlaceList |
400 | Malformed request (invalid JSON, unknown parameter, body too large). | application/problem+json Problem |
401 | Missing, invalid, expired or revoked credentials. | application/problem+json Problem |
429 | Rate or quota exceeded. | application/problem+json Problem |
Response example
{
"object": "list",
"has_more": false,
"next_cursor": null,
"data": [
{
"id": "fr-creteil-94000",
"city": "Créteil",
"postal_code": "94000",
"label": "Créteil (94000)",
"region": "Île-de-France",
"subdivision": "Val-de-Marne",
"subdivision_code": "94",
"country": "FR"
}
]
}GET /consent-texts/{version}
Read a version of the consent text
Dated, immutable versions. The text to display for a request is the one returned in its draft (consent).
Authentication: API key (Authorization: Bearer kk_…) or OAuth 2.0 token (scope catalog.read).
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
version | path | yes | string | pattern |
lang | query | no | LanguageCode | Language (ISO 639-1). Default = main language of the country. pattern |
Responses
| Code | Description | Content |
|---|---|---|
200 | The consent text. | application/json ConsentText |
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 |
Response example
{
"version": "v2026-10-18",
"lang": "fr",
"text": "J’accepte que ma demande et mes coordonnées soient transmises à un ou plusieurs professionnels du métier de mon secteur, qui pourront me rappeler à ce sujet.",
"valid_from": "2026-11-10"
}Schemas
CountryList
Type: ListMeta and object
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 |
CountryCode
Type: string — pattern ^[A-Z]{2}$ · default "FR"
LanguageCode
Type: string — pattern ^[a-z]{2}$
TradeScope
local: dispatched by distance circles; national: dispatched by reviews, without distance. The place remains required.
Type: string — values: local, national
TradeList
Type: ListMeta and object
Trade
Type: TradeSummary and object
ServiceList
Type: ListMeta and object
TradeMatchQuery
| Field | Type | Required | Description |
|---|---|---|---|
need | string | yes | Need in everyday words. Neither stored nor logged. min. 3 chars · max. 300 chars |
country | CountryCode | no | |
lang | LanguageCode | no | |
limit | integer | no | min. 1 · max. 10 · default |
TradeMatchList
Type: ListMeta and object
PlaceList
Type: ListMeta and object
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 |
ListMeta
| Field | Type | Required | Description |
|---|---|---|---|
object | string | yes | value: |
has_more | boolean | yes | |
next_cursor | string | null | 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. |
TradeSummary
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | Stable identifier, the same in every language. |
name | string | yes | Name in the requested language. |
family | string | yes | |
scope | TradeScope | yes | |
page_url | string (uri) | no | Public page of the trade in the country and language ( |