# 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 languages - GET /trades — Catalog of trades open to the API - GET /trades/{trade_id} — Trade details (services, timings, consent text) - GET /trades/{trade_id}/services — Detailed service catalog of a trade - POST /trade-matches — Find the trades that match a need - GET /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 `^[A-Z]{2}$` · default `"FR"` | | `lang` | query | no | LanguageCode | Language (ISO 639-1). Default = main language of the country. `Accept-Language` is read as a fallback. pattern `^[a-z]{2}$` | | `family` | query | no | string | Trade family (e.g. depannage, maison). max. 40 chars | | `scope` | query | no | TradeScope | Scope of the trade. values: `local`, `national` | | `limit` | query | no | integer | Page size (1 to 100). min. 1 · max. 100 · default `20` | | `starting_after` | query | no | string | Opaque `next_cursor` cursor from the previous page. 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 `^[a-z0-9-]{2,60}$` | | `country` | query | no | CountryCode | Country (ISO 3166-1 alpha-2, upper case). Default FR. pattern `^[A-Z]{2}$` · default `"FR"` | | `lang` | query | no | LanguageCode | Language (ISO 639-1). Default = main language of the country. `Accept-Language` is read as a fallback. pattern `^[a-z]{2}$` | ### 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 `^[a-z0-9-]{2,60}$` | | `country` | query | no | CountryCode | Country (ISO 3166-1 alpha-2, upper case). Default FR. pattern `^[A-Z]{2}$` · default `"FR"` | | `lang` | query | no | LanguageCode | Language (ISO 639-1). Default = main language of the country. `Accept-Language` is read as a fallback. pattern `^[a-z]{2}$` | | `limit` | query | no | integer | Page size (1 to 100). min. 1 · max. 100 · default `20` | | `starting_after` | query | no | string | Opaque `next_cursor` cursor from the previous page. 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 `^[A-Z]{2}$` · default `"FR"` | | `lang` | query | no | LanguageCode | Language (ISO 639-1). Default = main language of the country. `Accept-Language` is read as a fallback. pattern `^[a-z]{2}$` | | `limit` | query | no | integer | Page size (1 to 100). min. 1 · max. 100 · default `20` | ### 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 `^v\d{4}-\d{2}-\d{2}$` | | `lang` | query | no | LanguageCode | Language (ISO 639-1). Default = main language of the country. `Accept-Language` is read as a fallback. pattern `^[a-z]{2}$` | ### 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: `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 | | ### `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 `5` | ### `TradeMatchList` Type: ListMeta and object ### `PlaceList` Type: ListMeta and object ### `ConsentText` | Field | Type | Required | Description | | `version` | string | yes | pattern `^v\d{4}-\d{2}-\d{2}$` | | `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: `list` | | `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 (`/{country}/{language}/…`). | ## About this page - URL : https://kelki.ai/developers/en/reference/catalog/ - Language : en - fr : https://kelki.ai/developers/fr/reference/catalog/ - en : https://kelki.ai/developers/en/reference/catalog/ - x-default : https://kelki.ai/developers/ - Portal : https://kelki.ai/developers/llms.txt