Référentiel
Pays, métiers, prestations, lieux et textes d'accord. Lecture seule, même source que le site et le connecteur MCP.
Adresse de base : https://kelki.ai/api/v1.
GET /countries— Lister les pays et leurs languesGET /trades— Catalogue des métiers ouverts à l'APIGET /trades/{trade_id}— Détail d'un métier (prestations, délais, texte d'accord)GET /trades/{trade_id}/services— Catalogue détaillé des prestations d'un métierPOST /trade-matches— Trouver les métiers correspondant à un besoinGET /places— Vérifier un lieu (ville ou code postal)GET /consent-texts/{version}— Lire une version du texte d'accord
GET /countries
Lister les pays et leurs langues
Pays couverts, langues, devise, et disponibilité (live = demandes acceptées ; preparing = référentiel consultable, demandes refusées).
Authentification : clé API (Authorization: Bearer kk_…) ou jeton OAuth 2.0 (portée catalog.read).
Réponses
| Code | Description | Contenu |
|---|---|---|
200 | Liste des pays. | application/json CountryList |
401 | Identifiants absents, invalides, expirés ou révoqués. | application/problem+json Problem |
429 | Débit ou quota dépassé. | application/problem+json Problem |
Exemple de réponse
{
"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
Catalogue des métiers ouverts à l'API
Métiers ouverts dans le pays, noms dans la langue demandée. Exclus : métiers de santé, métiers en relecture, exclusions propres au compte. Les métiers national n'ont pas de diffusion par distance.
Authentification : clé API (Authorization: Bearer kk_…) ou jeton OAuth 2.0 (portée catalog.read).
Paramètres
| Nom | Où | Requis | Type | Description |
|---|---|---|---|---|
country | query | non | CountryCode | Pays (ISO 3166-1 alpha-2, majuscules). Défaut FR. motif |
lang | query | non | LanguageCode | Langue (ISO 639-1). Défaut = langue principale du pays. motif |
family | query | non | string | Famille de métiers (ex. depannage, maison). max. 40 car. |
scope | query | non | TradeScope | Portée du métier. valeurs : |
limit | query | non | integer | Taille de page (1 à 100). min. 1 · max. 100 · défaut |
starting_after | query | non | string | Curseur opaque max. 200 car. |
Réponses
| Code | Description | Contenu |
|---|---|---|
200 | Une page du catalogue. | application/json TradeList |
400 | Requête mal formée (JSON invalide, paramètre inconnu, corps trop gros). | application/problem+json Problem |
401 | Identifiants absents, invalides, expirés ou révoqués. | application/problem+json Problem |
422 | Valeur refusée par les règles du formulaire (listes fermées, lieu, coordonnées, accord, limites anti-abus). | application/problem+json Problem |
429 | Débit ou quota dépassé. | application/problem+json Problem |
Exemple de réponse
{
"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}
Détail d'un métier (prestations, délais, texte d'accord)
Équivalent de l'outil MCP lister_prestations. Les listes sont fermées, comme dans le formulaire.
Authentification : clé API (Authorization: Bearer kk_…) ou jeton OAuth 2.0 (portée catalog.read).
Paramètres
| Nom | Où | Requis | Type | Description |
|---|---|---|---|---|
trade_id | path | oui | string | Identifiant stable du métier (slug français historique, ex. plombier). motif |
country | query | non | CountryCode | Pays (ISO 3166-1 alpha-2, majuscules). Défaut FR. motif |
lang | query | non | LanguageCode | Langue (ISO 639-1). Défaut = langue principale du pays. motif |
Réponses
| Code | Description | Contenu |
|---|---|---|
200 | Le métier. | application/json Trade |
401 | Identifiants absents, invalides, expirés ou révoqués. | application/problem+json Problem |
404 | Ressource inconnue, ou appartenant à un autre compte ou à un autre mode (même réponse). | application/problem+json Problem |
429 | Débit ou quota dépassé. | application/problem+json Problem |
Exemple de réponse
{
"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
Catalogue détaillé des prestations d'un métier
Catalogue de prestations du métier (intitulés simples, data/datasets/). Les intitulés utilisables dans une demande sont ceux qui ont requestable: true ; « Autre besoin » est toujours possible avec other_need.
Authentification : clé API (Authorization: Bearer kk_…) ou jeton OAuth 2.0 (portée catalog.read).
Paramètres
| Nom | Où | Requis | Type | Description |
|---|---|---|---|---|
trade_id | path | oui | string | Identifiant stable du métier (slug français historique, ex. plombier). motif |
country | query | non | CountryCode | Pays (ISO 3166-1 alpha-2, majuscules). Défaut FR. motif |
lang | query | non | LanguageCode | Langue (ISO 639-1). Défaut = langue principale du pays. motif |
limit | query | non | integer | Taille de page (1 à 100). min. 1 · max. 100 · défaut |
starting_after | query | non | string | Curseur opaque max. 200 car. |
Réponses
| Code | Description | Contenu |
|---|---|---|
200 | Une page de prestations. | application/json ServiceList |
401 | Identifiants absents, invalides, expirés ou révoqués. | application/problem+json Problem |
404 | Ressource inconnue, ou appartenant à un autre compte ou à un autre mode (même réponse). | application/problem+json Problem |
429 | Débit ou quota dépassé. | application/problem+json Problem |
Exemple de réponse
{
"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
Trouver les métiers correspondant à un besoin
Équivalent de l'outil MCP trouver_service. Le besoin passe dans le corps (jamais dans l'adresse) : il peut contenir des détails personnels. Il n'est ni conservé ni journalisé. Proposez les 2 ou 3 premiers résultats à la personne et laissez-la choisir. Lecture seule : pas d'Idempotency-Key.
Authentification : clé API (Authorization: Bearer kk_…) ou jeton OAuth 2.0 (portée catalog.read).
Corps de la requête
application/json — TradeMatchQuery (obligatoire)
{
"need": "Fuite d'eau sous l'évier de la cuisine",
"country": "FR",
"lang": "fr"
}Réponses
| Code | Description | Contenu |
|---|---|---|
200 | Métiers probables, du plus pertinent au moins pertinent. | application/json TradeMatchList |
400 | Requête mal formée (JSON invalide, paramètre inconnu, corps trop gros). | application/problem+json Problem |
401 | Identifiants absents, invalides, expirés ou révoqués. | application/problem+json Problem |
422 | Valeur refusée par les règles du formulaire (listes fermées, lieu, coordonnées, accord, limites anti-abus). | application/problem+json Problem |
429 | Débit ou quota dépassé. | application/problem+json Problem |
Exemple de réponse
{
"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
Vérifier un lieu (ville ou code postal)
Équivalent de l'outil MCP verifier_lieu. Renvoie des lieux existants ; utilisez leur id dans la demande.
Authentification : clé API (Authorization: Bearer kk_…) ou jeton OAuth 2.0 (portée catalog.read).
Paramètres
| Nom | Où | Requis | Type | Description |
|---|---|---|---|---|
q | query | oui | string | Nom de ville ou code postal (pas d'adresse précise). min. 2 car. · max. 120 car. |
country | query | non | CountryCode | Pays (ISO 3166-1 alpha-2, majuscules). Défaut FR. motif |
lang | query | non | LanguageCode | Langue (ISO 639-1). Défaut = langue principale du pays. motif |
limit | query | non | integer | Taille de page (1 à 100). min. 1 · max. 100 · défaut |
Réponses
| Code | Description | Contenu |
|---|---|---|
200 | Lieux correspondants. | application/json PlaceList |
400 | Requête mal formée (JSON invalide, paramètre inconnu, corps trop gros). | application/problem+json Problem |
401 | Identifiants absents, invalides, expirés ou révoqués. | application/problem+json Problem |
429 | Débit ou quota dépassé. | application/problem+json Problem |
Exemple de réponse
{
"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}
Lire une version du texte d'accord
Versions datées et immuables. Le texte à afficher pour une demande est celui renvoyé dans son brouillon (consent).
Authentification : clé API (Authorization: Bearer kk_…) ou jeton OAuth 2.0 (portée catalog.read).
Paramètres
| Nom | Où | Requis | Type | Description |
|---|---|---|---|---|
version | path | oui | string | motif |
lang | query | non | LanguageCode | Langue (ISO 639-1). Défaut = langue principale du pays. motif |
Réponses
| Code | Description | Contenu |
|---|---|---|
200 | Le texte d'accord. | application/json ConsentText |
401 | Identifiants absents, invalides, expirés ou révoqués. | application/problem+json Problem |
404 | Ressource inconnue, ou appartenant à un autre compte ou à un autre mode (même réponse). | application/problem+json Problem |
Exemple de réponse
{
"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"
}Schémas
CountryList
Type : ListMeta et object
Problem
Détails d'un problème (RFC 9457), avec des membres d'extension.
| Champ | Type | Requis | Description |
|---|---|---|---|
type | string (uri) | oui | URI stable du type de problème ; elle mène à sa documentation. |
title | string | oui | |
status | integer | oui | min. 400 · max. 599 |
detail | string | non | |
instance | string (uri-reference) | non | |
code | string | oui | Code stable, lisible par une machine. valeurs : |
request_id | string | oui | |
errors | tableau de FieldError | non |
CountryCode
Type : string — motif ^[A-Z]{2}$ · défaut "FR"
LanguageCode
Type : string — motif ^[a-z]{2}$
TradeScope
local : diffusion par cercles de distance ; national : diffusion triée par avis, sans distance. Le lieu reste obligatoire.
Type : string — valeurs : local, national
TradeList
Type : ListMeta et object
Trade
Type : TradeSummary et object
ServiceList
Type : ListMeta et object
TradeMatchQuery
| Champ | Type | Requis | Description |
|---|---|---|---|
need | string | oui | Besoin en mots courants. Ni conservé ni journalisé. min. 3 car. · max. 300 car. |
country | CountryCode | non | |
lang | LanguageCode | non | |
limit | integer | non | min. 1 · max. 10 · défaut |
TradeMatchList
Type : ListMeta et object
PlaceList
Type : ListMeta et object
ConsentText
| Champ | Type | Requis | Description |
|---|---|---|---|
version | string | oui | motif |
lang | LanguageCode | oui | |
text | string | oui | À afficher mot pour mot, à côté d'une case non cochée par défaut. |
valid_from | string (date) | oui |
ListMeta
| Champ | Type | Requis | Description |
|---|---|---|---|
object | string | oui | valeur : |
has_more | boolean | oui | |
next_cursor | string | null | oui |
FieldError
| Champ | Type | Requis | Description |
|---|---|---|---|
pointer | string | oui | JSON Pointer (RFC 6901) du champ en cause. |
detail | string | oui | |
allowed | tableau de string | non | Valeurs acceptées, quand la liste est fermée. |
TradeSummary
| Champ | Type | Requis | Description |
|---|---|---|---|
id | string | oui | Identifiant stable, identique dans toutes les langues. |
name | string | oui | Nom dans la langue demandée. |
family | string | oui | |
scope | TradeScope | oui | |
page_url | string (uri) | non | Page publique du métier dans le pays et la langue ( |