Aller au contenu
KelkiDéveloppeurs

Référence de l'API

Trouver le bon professionnel et lui transmettre une demande de rappel, avec l'accord explicite de la personne.

Générée depuis la spécification OpenAPI 3.1.0 — version 1.0.0. Adresse : https://kelki.ai/api/v1.

L'API de l'Agent Kelki permet à une application tierce (conciergerie, gestion locative, assistant, CRM…) de :

  1. trouver le métier et la prestation qui correspondent à un besoin, dans la langue et le pays de la personne ;
  2. vérifier le lieu de l'intervention ;
  3. préparer un brouillon de demande, le montrer à la personne avec le texte d'accord ;
  4. faire confirmer la demande par la personne (lien envoyé par e-mail, ou attestation de consentement d'un partenaire agréé) ;
  5. suivre la demande : transmise, vendue à un seul professionnel, rappel confirmé par la personne.

Mêmes règles que le formulaire « Rappelez-moi », le connecteur MCP (https://kelki.ai/mcp) et l'Agent Kelki. Aucune réponse ne contient la coordonnée d'un professionnel, ni la source d'acquisition de la demande.

Erreurs au format RFC 9457 (application/problem+json). Pagination par curseur. Idempotency-Key obligatoire sur les créations. Débit limité par clé (en-têtes RateLimit et RateLimit-Policy).

Gratuite pour les partenaires. Encadrée par trois textes (12/11/2026, /developers/fr/terms/) : conditions d'utilisation de l'API, accord de traitement des données (article 28 du RGPD : Kelki responsable du traitement, partenaire sous-traitant pour la collecte et l'envoi des demandes), politique d'usage acceptable.

Sections

SectionRouteRôle
RéférentielGET /countriesLister les pays et leurs langues
RéférentielGET /tradesCatalogue des métiers ouverts à l'API
RéférentielGET /trades/{trade_id}Détail d'un métier (prestations, délais, texte d'accord)
RéférentielGET /trades/{trade_id}/servicesCatalogue détaillé des prestations d'un métier
RéférentielPOST /trade-matchesTrouver les métiers correspondant à un besoin
RéférentielGET /placesVérifier un lieu (ville ou code postal)
RéférentielGET /consent-texts/{version}Lire une version du texte d'accord
DemandesPOST /requestsCréer un brouillon de demande
DemandesGET /requestsLister vos demandes
DemandesGET /requests/{request_id}Lire une demande et son statut
DemandesPATCH /requests/{request_id}Modifier un brouillon
DemandesDELETE /requests/{request_id}Annuler une demande non transmise
DemandesPOST /requests/{request_id}/confirmationLancer la confirmation par la personne
DemandesGET /requests/{request_id}/eventsHistorique des statuts d'une demande
DemandesPOST /sandbox/requests/{request_id}/simulateFaire avancer une demande de test
AgentPOST /agent/conversationsDémarrer une conversation avec l'Agent Kelki
AgentGET /agent/conversations/{conversation_id}Lire l'état d'une conversation
AgentPOST /agent/conversations/{conversation_id}/messagesEnvoyer un message à l'Agent Kelki
Webhooks (référence)GET /webhook-endpointsLister vos adresses de webhooks
Webhooks (référence)POST /webhook-endpointsDéclarer une adresse de webhook
Webhooks (référence)GET /webhook-endpoints/{endpoint_id}Lire une adresse de webhook
Webhooks (référence)DELETE /webhook-endpoints/{endpoint_id}Supprimer une adresse de webhook
Webhooks (référence)POST /webhook-endpoints/{endpoint_id}/testEnvoyer un événement « ping »
Webhooks (référence)POST /webhook-endpoints/{endpoint_id}/rotate-secretRemplacer le secret de signature
CompteGET /accountLire le compte, le plan et les plafonds
CompteGET /account/usageConsommation par jour
OAuthPOST /oauth/tokenObtenir un jeton d'accès (client credentials)
OAuthPOST /oauth/revokeRévoquer un jeton d'accès (RFC 7009)

Authentification

ApiKey

Clé API du partenaire, dans Authorization. Jamais dans l'adresse. Stockée hachée chez Kelki.

Format : kk_live_… ou kk_test_…

OAuth2

Client credentials (RFC 6749 § 4.4). Jeton opaque de 15 minutes.

Jeton : https://kelki.ai/api/v1/oauth/token

PortéeAccès
catalog.readLire le référentiel, le compte et la consommation.
requests.readLire vos demandes et leurs statuts.
requests.writeCréer, modifier, annuler et faire confirmer vos demandes.
consent.attestAttester le consentement de la personne (partenaires agréés sous contrat).
agentConverser avec l'Agent Kelki.
webhooks.manageGérer vos adresses de webhooks.

ClientBasic

client_id et client_secret du client OAuth (point d'accès /oauth/token seulement).

Réponses d'erreur communes

CodeNomDescriptionContenu
400BadRequest

Requête mal formée (JSON invalide, paramètre inconnu, corps trop gros).

Problem
401Unauthorized

Identifiants absents, invalides, expirés ou révoqués.

Problem
403Forbidden

Portée manquante, compte non autorisé en live, pays non ouvert, compte suspendu.

Problem
404NotFound

Ressource inconnue, ou appartenant à un autre compte ou à un autre mode (même réponse).

Problem
409Conflict

Transition impossible (ex. modifier une demande déjà transmise) ou requête idempotente en cours.

Problem
422ValidationFailed

Valeur refusée par les règles du formulaire (listes fermées, lieu, coordonnées, accord, limites anti-abus).

Problem
429TooManyRequests

Débit ou quota dépassé.

Problem
503ServiceUnavailable

Service en pause ou en maintenance (ex. agent en pause, création live suspendue).

Problem

Schémas

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

FieldError

ChampTypeRequisDescription
pointerstringoui

JSON Pointer (RFC 6901) du champ en cause.

detailstringoui
allowedtableau de stringnon

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