# 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`. [openapi.yaml](https://kelki.ai/assets/developers/openapi.yaml)[openapi.json](https://kelki.ai/assets/developers/openapi.json) 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](https://kelki.ai/developers/fr/reference/catalog/#listCountries) | GET `/countries` | Lister les pays et leurs langues | | [Référentiel](https://kelki.ai/developers/fr/reference/catalog/#listTrades) | GET `/trades` | Catalogue des métiers ouverts à l'API | | [Référentiel](https://kelki.ai/developers/fr/reference/catalog/#getTrade) | GET `/trades/{trade_id}` | Détail d'un métier (prestations, délais, texte d'accord) | | [Référentiel](https://kelki.ai/developers/fr/reference/catalog/#listTradeServices) | GET `/trades/{trade_id}/services` | Catalogue détaillé des prestations d'un métier | | [Référentiel](https://kelki.ai/developers/fr/reference/catalog/#matchTrades) | POST `/trade-matches` | Trouver les métiers correspondant à un besoin | | [Référentiel](https://kelki.ai/developers/fr/reference/catalog/#searchPlaces) | GET `/places` | Vérifier un lieu (ville ou code postal) | | [Référentiel](https://kelki.ai/developers/fr/reference/catalog/#getConsentText) | GET `/consent-texts/{version}` | Lire une version du texte d'accord | | [Demandes](https://kelki.ai/developers/fr/reference/requests/#createRequest) | POST `/requests` | Créer un brouillon de demande | | [Demandes](https://kelki.ai/developers/fr/reference/requests/#listRequests) | GET `/requests` | Lister vos demandes | | [Demandes](https://kelki.ai/developers/fr/reference/requests/#getRequest) | GET `/requests/{request_id}` | Lire une demande et son statut | | [Demandes](https://kelki.ai/developers/fr/reference/requests/#updateRequest) | PATCH `/requests/{request_id}` | Modifier un brouillon | | [Demandes](https://kelki.ai/developers/fr/reference/requests/#cancelRequest) | DELETE `/requests/{request_id}` | Annuler une demande non transmise | | [Demandes](https://kelki.ai/developers/fr/reference/requests/#confirmRequest) | POST `/requests/{request_id}/confirmation` | Lancer la confirmation par la personne | | [Demandes](https://kelki.ai/developers/fr/reference/requests/#listRequestEvents) | GET `/requests/{request_id}/events` | Historique des statuts d'une demande | | [Demandes](https://kelki.ai/developers/fr/reference/requests/#simulateRequestStatus) | POST `/sandbox/requests/{request_id}/simulate` | Faire avancer une demande de test | | [Agent](https://kelki.ai/developers/fr/reference/agent/#createConversation) | POST `/agent/conversations` | Démarrer une conversation avec l'Agent Kelki | | [Agent](https://kelki.ai/developers/fr/reference/agent/#getConversation) | GET `/agent/conversations/{conversation_id}` | Lire l'état d'une conversation | | [Agent](https://kelki.ai/developers/fr/reference/agent/#sendConversationMessage) | POST `/agent/conversations/{conversation_id}/messages` | Envoyer un message à l'Agent Kelki | | [Webhooks (référence)](https://kelki.ai/developers/fr/reference/webhooks/#listWebhookEndpoints) | GET `/webhook-endpoints` | Lister vos adresses de webhooks | | [Webhooks (référence)](https://kelki.ai/developers/fr/reference/webhooks/#createWebhookEndpoint) | POST `/webhook-endpoints` | Déclarer une adresse de webhook | | [Webhooks (référence)](https://kelki.ai/developers/fr/reference/webhooks/#getWebhookEndpoint) | GET `/webhook-endpoints/{endpoint_id}` | Lire une adresse de webhook | | [Webhooks (référence)](https://kelki.ai/developers/fr/reference/webhooks/#deleteWebhookEndpoint) | DELETE `/webhook-endpoints/{endpoint_id}` | Supprimer une adresse de webhook | | [Webhooks (référence)](https://kelki.ai/developers/fr/reference/webhooks/#testWebhookEndpoint) | POST `/webhook-endpoints/{endpoint_id}/test` | Envoyer un événement « ping » | | [Webhooks (référence)](https://kelki.ai/developers/fr/reference/webhooks/#rotateWebhookSecret) | POST `/webhook-endpoints/{endpoint_id}/rotate-secret` | Remplacer le secret de signature | | [Compte](https://kelki.ai/developers/fr/reference/account/#getAccount) | GET `/account` | Lire le compte, le plan et les plafonds | | [Compte](https://kelki.ai/developers/fr/reference/account/#getAccountUsage) | GET `/account/usage` | Consommation par jour | | [OAuth](https://kelki.ai/developers/fr/reference/oauth/#createAccessToken) | POST `/oauth/token` | Obtenir un jeton d'accès (client credentials) | | [OAuth](https://kelki.ai/developers/fr/reference/oauth/#revokeAccessToken) | 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 : `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_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. | ## Sur cette page - URL : https://kelki.ai/developers/fr/reference/ - Langue : fr - fr : https://kelki.ai/developers/fr/reference/ - en : https://kelki.ai/developers/en/reference/ - x-default : https://kelki.ai/developers/ - Portail : https://kelki.ai/developers/llms.txt