Aller au contenu
KelkiDéveloppeurs

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 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

CodeDescriptionContenu
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

NomOùRequisTypeDescription
countryquerynonCountryCode

Pays (ISO 3166-1 alpha-2, majuscules). Défaut FR.

motif ^[A-Z]{2}$ · défaut "FR"

langquerynonLanguageCode

Langue (ISO 639-1). Défaut = langue principale du pays. Accept-Language est lu en repli.

motif ^[a-z]{2}$

familyquerynonstring

Famille de métiers (ex. depannage, maison).

max. 40 car.

scopequerynonTradeScope

Portée du métier.

valeurs : local, national

limitquerynoninteger

Taille de page (1 à 100).

min. 1 · max. 100 · défaut 20

starting_afterquerynonstring

Curseur opaque next_cursor de la page précédente.

max. 200 car.

Réponses

CodeDescriptionContenu
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

NomOùRequisTypeDescription
trade_idpathouistring

Identifiant stable du métier (slug français historique, ex. plombier).

motif ^[a-z0-9-]{2,60}$

countryquerynonCountryCode

Pays (ISO 3166-1 alpha-2, majuscules). Défaut FR.

motif ^[A-Z]{2}$ · défaut "FR"

langquerynonLanguageCode

Langue (ISO 639-1). Défaut = langue principale du pays. Accept-Language est lu en repli.

motif ^[a-z]{2}$

Réponses

CodeDescriptionContenu
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

NomOùRequisTypeDescription
trade_idpathouistring

Identifiant stable du métier (slug français historique, ex. plombier).

motif ^[a-z0-9-]{2,60}$

countryquerynonCountryCode

Pays (ISO 3166-1 alpha-2, majuscules). Défaut FR.

motif ^[A-Z]{2}$ · défaut "FR"

langquerynonLanguageCode

Langue (ISO 639-1). Défaut = langue principale du pays. Accept-Language est lu en repli.

motif ^[a-z]{2}$

limitquerynoninteger

Taille de page (1 à 100).

min. 1 · max. 100 · défaut 20

starting_afterquerynonstring

Curseur opaque next_cursor de la page précédente.

max. 200 car.

Réponses

CodeDescriptionContenu
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

CodeDescriptionContenu
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

NomOùRequisTypeDescription
qqueryouistring

Nom de ville ou code postal (pas d'adresse précise).

min. 2 car. · max. 120 car.

countryquerynonCountryCode

Pays (ISO 3166-1 alpha-2, majuscules). Défaut FR.

motif ^[A-Z]{2}$ · défaut "FR"

langquerynonLanguageCode

Langue (ISO 639-1). Défaut = langue principale du pays. Accept-Language est lu en repli.

motif ^[a-z]{2}$

limitquerynoninteger

Taille de page (1 à 100).

min. 1 · max. 100 · défaut 20

Réponses

CodeDescriptionContenu
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

NomOùRequisTypeDescription
versionpathouistring

motif ^v\d{4}-\d{2}-\d{2}$

langquerynonLanguageCode

Langue (ISO 639-1). Défaut = langue principale du pays. Accept-Language est lu en repli.

motif ^[a-z]{2}$

Réponses

CodeDescriptionContenu
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.

ChampTypeRequisDescription
typestring (uri)oui

URI stable du type de problème ; elle mène à sa documentation.

titlestringoui
statusintegeroui

min. 400 · max. 599

detailstringnon
instancestring (uri-reference)non
codestringoui

Code stable, lisible par une machine.

valeurs : 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_idstringoui
errorstableau de FieldErrornon

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

ChampTypeRequisDescription
needstringoui

Besoin en mots courants. Ni conservé ni journalisé.

min. 3 car. · max. 300 car.

countryCountryCodenon
langLanguageCodenon
limitintegernon

min. 1 · max. 10 · défaut 5

TradeMatchList

Type : ListMeta et object

PlaceList

Type : ListMeta et object

ConsentText

ChampTypeRequisDescription
versionstringoui

motif ^v\d{4}-\d{2}-\d{2}$

langLanguageCodeoui
textstringoui

À afficher mot pour mot, à côté d'une case non cochée par défaut.

valid_fromstring (date)oui

ListMeta

ChampTypeRequisDescription
objectstringoui

valeur : list

has_morebooleanoui
next_cursorstring | nulloui

FieldError

ChampTypeRequisDescription
pointerstringoui

JSON Pointer (RFC 6901) du champ en cause.

detailstringoui
allowedtableau de stringnon

Valeurs acceptées, quand la liste est fermée.

TradeSummary

ChampTypeRequisDescription
idstringoui

Identifiant stable, identique dans toutes les langues.

namestringoui

Nom dans la langue demandée.

familystringoui
scopeTradeScopeoui
page_urlstring (uri)non

Page publique du métier dans le pays et la langue (/{pays}/{langue}/…).