Skip to content
KelkiDevelopers

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

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

CodeDescriptionContent
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

NameInRequiredTypeDescription
countryquerynoCountryCode

Country (ISO 3166-1 alpha-2, upper case). Default FR.

pattern ^[A-Z]{2}$ · default "FR"

langquerynoLanguageCode

Language (ISO 639-1). Default = main language of the country. Accept-Language is read as a fallback.

pattern ^[a-z]{2}$

familyquerynostring

Trade family (e.g. depannage, maison).

max. 40 chars

scopequerynoTradeScope

Scope of the trade.

values: local, national

limitquerynointeger

Page size (1 to 100).

min. 1 · max. 100 · default 20

starting_afterquerynostring

Opaque next_cursor cursor from the previous page.

max. 200 chars

Responses

CodeDescriptionContent
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

NameInRequiredTypeDescription
trade_idpathyesstring

Stable identifier of the trade (historical French slug, e.g. plombier).

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

countryquerynoCountryCode

Country (ISO 3166-1 alpha-2, upper case). Default FR.

pattern ^[A-Z]{2}$ · default "FR"

langquerynoLanguageCode

Language (ISO 639-1). Default = main language of the country. Accept-Language is read as a fallback.

pattern ^[a-z]{2}$

Responses

CodeDescriptionContent
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

NameInRequiredTypeDescription
trade_idpathyesstring

Stable identifier of the trade (historical French slug, e.g. plombier).

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

countryquerynoCountryCode

Country (ISO 3166-1 alpha-2, upper case). Default FR.

pattern ^[A-Z]{2}$ · default "FR"

langquerynoLanguageCode

Language (ISO 639-1). Default = main language of the country. Accept-Language is read as a fallback.

pattern ^[a-z]{2}$

limitquerynointeger

Page size (1 to 100).

min. 1 · max. 100 · default 20

starting_afterquerynostring

Opaque next_cursor cursor from the previous page.

max. 200 chars

Responses

CodeDescriptionContent
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

CodeDescriptionContent
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

NameInRequiredTypeDescription
qqueryyesstring

Town name or postcode (no precise address).

min. 2 chars · max. 120 chars

countryquerynoCountryCode

Country (ISO 3166-1 alpha-2, upper case). Default FR.

pattern ^[A-Z]{2}$ · default "FR"

langquerynoLanguageCode

Language (ISO 639-1). Default = main language of the country. Accept-Language is read as a fallback.

pattern ^[a-z]{2}$

limitquerynointeger

Page size (1 to 100).

min. 1 · max. 100 · default 20

Responses

CodeDescriptionContent
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

NameInRequiredTypeDescription
versionpathyesstring

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

langquerynoLanguageCode

Language (ISO 639-1). Default = main language of the country. Accept-Language is read as a fallback.

pattern ^[a-z]{2}$

Responses

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

FieldTypeRequiredDescription
typestring (uri)yes

Stable URI of the problem type; it leads to its documentation.

titlestringyes
statusintegeryes

min. 400 · max. 599

detailstringno
instancestring (uri-reference)no
codestringyes

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_idstringyes
errorsarray of FieldErrorno

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

FieldTypeRequiredDescription
needstringyes

Need in everyday words. Neither stored nor logged.

min. 3 chars · max. 300 chars

countryCountryCodeno
langLanguageCodeno
limitintegerno

min. 1 · max. 10 · default 5

TradeMatchList

Type: ListMeta and object

PlaceList

Type: ListMeta and object

ConsentText

FieldTypeRequiredDescription
versionstringyes

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

langLanguageCodeyes
textstringyes

To display word for word, next to a checkbox left unticked by default.

valid_fromstring (date)yes

ListMeta

FieldTypeRequiredDescription
objectstringyes

value: list

has_morebooleanyes
next_cursorstring | nullyes

FieldError

FieldTypeRequiredDescription
pointerstringyes

JSON Pointer (RFC 6901) of the field at fault.

detailstringyes
allowedarray of stringno

Accepted values, when the list is closed.

TradeSummary

FieldTypeRequiredDescription
idstringyes

Stable identifier, the same in every language.

namestringyes

Name in the requested language.

familystringyes
scopeTradeScopeyes
page_urlstring (uri)no

Public page of the trade in the country and language (/{country}/{language}/…).