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 :
- trouver le métier et la prestation qui correspondent à un besoin, dans la langue et le pays de la personne ;
- vérifier le lieu de l'intervention ;
- préparer un brouillon de demande, le montrer à la personne avec le texte d'accord ;
- faire confirmer la demande par la personne (lien envoyé par e-mail, ou attestation de consentement d'un partenaire agréé) ;
- 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
| Section | Route | Rôle |
|---|---|---|
| Référentiel | GET /countries | Lister les pays et leurs langues |
| Référentiel | GET /trades | Catalogue des métiers ouverts à l'API |
| Référentiel | GET /trades/{trade_id} | Détail d'un métier (prestations, délais, texte d'accord) |
| Référentiel | GET /trades/{trade_id}/services | Catalogue détaillé des prestations d'un métier |
| Référentiel | POST /trade-matches | Trouver les métiers correspondant à un besoin |
| Référentiel | GET /places | Vérifier un lieu (ville ou code postal) |
| Référentiel | GET /consent-texts/{version} | Lire une version du texte d'accord |
| Demandes | POST /requests | Créer un brouillon de demande |
| Demandes | GET /requests | Lister vos demandes |
| Demandes | GET /requests/{request_id} | Lire une demande et son statut |
| Demandes | PATCH /requests/{request_id} | Modifier un brouillon |
| Demandes | DELETE /requests/{request_id} | Annuler une demande non transmise |
| Demandes | POST /requests/{request_id}/confirmation | Lancer la confirmation par la personne |
| Demandes | GET /requests/{request_id}/events | Historique des statuts d'une demande |
| Demandes | POST /sandbox/requests/{request_id}/simulate | Faire avancer une demande de test |
| Agent | POST /agent/conversations | Démarrer une conversation avec l'Agent Kelki |
| Agent | GET /agent/conversations/{conversation_id} | Lire l'état d'une conversation |
| Agent | POST /agent/conversations/{conversation_id}/messages | Envoyer un message à l'Agent Kelki |
| Webhooks (référence) | GET /webhook-endpoints | Lister vos adresses de webhooks |
| Webhooks (référence) | POST /webhook-endpoints | Dé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}/test | Envoyer un événement « ping » |
| Webhooks (référence) | POST /webhook-endpoints/{endpoint_id}/rotate-secret | Remplacer le secret de signature |
| Compte | GET /account | Lire le compte, le plan et les plafonds |
| Compte | GET /account/usage | Consommation par jour |
| OAuth | POST /oauth/token | Obtenir un jeton d'accès (client credentials) |
| OAuth | POST /oauth/revoke | Ré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ée | Accès |
|---|---|
catalog.read | Lire le référentiel, le compte et la consommation. |
requests.read | Lire vos demandes et leurs statuts. |
requests.write | Créer, modifier, annuler et faire confirmer vos demandes. |
consent.attest | Attester le consentement de la personne (partenaires agréés sous contrat). |
agent | Converser avec l'Agent Kelki. |
webhooks.manage | Gé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
| Code | Nom | Description | Contenu |
|---|---|---|---|
400 | BadRequest | Requête mal formée (JSON invalide, paramètre inconnu, corps trop gros). | Problem |
401 | Unauthorized | Identifiants absents, invalides, expirés ou révoqués. | Problem |
403 | Forbidden | Portée manquante, compte non autorisé en live, pays non ouvert, compte suspendu. | Problem |
404 | NotFound | Ressource inconnue, ou appartenant à un autre compte ou à un autre mode (même réponse). | Problem |
409 | Conflict | Transition impossible (ex. modifier une demande déjà transmise) ou requête idempotente en cours. | Problem |
422 | ValidationFailed | Valeur refusée par les règles du formulaire (listes fermées, lieu, coordonnées, accord, limites anti-abus). | Problem |
429 | TooManyRequests | Débit ou quota dépassé. | Problem |
503 | ServiceUnavailable | 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.
| 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 |
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. |