Authentification par clé API
Chaque appel à l'API utilise un identifiant dans l'en-tête Authorization. Un identifiant se compose d'un préfixe public et d'un secret, ensemble sous la forme kp_<préfixe>_<secret>.
Étape 1
Créez un identifiant
Allez dans Paramètres, Intégrations et créez une clé API avec un libellé et un ensemble de scopes. La clé complète n'est affichée qu'une seule fois, conservez-la immédiatement en lieu sûr.
Étape 2
Utilisez des scopes minimaux
N'accordez à une clé que les scopes dont votre intégration a besoin. Un appel sans le scope requis reçoit un 403 avec le code insufficient_scope.
Étape 3
Appelez l'API
Envoyez la clé comme token Bearer dans l'en-tête Authorization. Traitez-la comme un mot de passe : quiconque la détient peut agir au nom de votre compte dans ses scopes.
curl https://www.keypilot.eu/api/v1/properties?limit=25 \ -H "Authorization: Bearer kp_<prefix>_<secret>"
Scopes
Les scopes limitent ce qu'un identifiant peut faire. Vous combinez les droits de lecture et d'écriture par ressource et pouvez renouveler ou révoquer une clé à tout moment.
properties:read
Lister et consulter les biens.
properties:write
Créer et modifier des biens.
contacts:read
Lister et consulter les contacts (locataires et entrepreneurs).
contacts:write
Créer et modifier des contacts.
contracts:read
Lister et consulter les contrats.
contracts:write
Créer et modifier des contrats.
tasks:read
Lister et consulter les tâches.
tasks:write
Créer et modifier des tâches.
maintenance:read
Lister et consulter les demandes d'entretien.
maintenance:write
Créer et modifier des demandes d'entretien.
webhooks:manage
Gérer les abonnements webhook (aujourd'hui via Paramètres, Intégrations).
Pagination
Les endpoints de liste utilisent la pagination par curseur et renvoient les résultats par id croissant.
Passez limit (1 à 100, 25 par défaut) pour la taille de page. Tant que nextCursor n'est pas null, récupérez la page suivante avec cursor=<nextCursor>. Vous parcourez ainsi toute la collection sans doublons ni trous.
{ "data": [ { "id": 42, "address": "Grote Markt 1", "...": "…" } ], "pagination": { "limit": 25, "nextCursor": 42 } }
Erreurs et limites
Chaque erreur suit la même enveloppe : un code lisible par machine, un message lisible et un requestId pour le support.
{ "error": { "code": "insufficient_scope", "message": "This endpoint requires contacts:write.", "requestId": "9f1c…" } }
unauthorized
Identifiant invalide ou clé révoquée (401).
insufficient_scope
L'identifiant n'a pas le scope requis pour cet endpoint (403).
invalid_request
La charge utile ou les paramètres ne passent pas la validation (400).
not_found
La ressource n'existe pas ou n'appartient pas à votre compte (404).
idempotency_conflict
Cette Idempotency-Key a déjà été utilisée pour une autre requête (409).
idempotency_in_progress
Une requête avec cette Idempotency-Key est encore en cours (409).
rate_limited
Trop de requêtes dans la fenêtre de temps (429).
Limite : 900 requêtes par 15 minutes par identifiant. Les en-têtes RateLimit de chaque réponse indiquent ce qu'il reste.
Les appels POST et PATCH acceptent un en-tête Idempotency-Key. Renvoyez la même clé et vous recevez la réponse enregistrée sans que la mutation soit exécutée une seconde fois. Les retries ne peuvent ainsi jamais créer de doublons.
Webhooks
Abonnez un endpoint HTTPS aux changements de votre compte. Gérez les abonnements dans Paramètres, Intégrations. Chaque livraison est un POST avec un événement JSON, signé avec le secret affiché une seule fois à la création.
Événements
property.created
property.updated
contact.created
contact.updated
contract.created
contract.updated
task.created
task.updated
maintenance.created
maintenance.updated
Si votre endpoint répond 2xx, la livraison réussit. Sinon nous réessayons jusqu'à 5 fois avec un backoff exponentiel (max 60 secondes entre les tentatives), puis la livraison est marquée failed.
{ "id": "evt_9f1c…", "type": "property.updated", "createdAt": "2026-08-16T09:30:00.000Z", "data": { "id": 42, "address": "Grote Markt 1", "...": "…" } }
Vérifier la signature
Chaque livraison envoie les en-têtes x-keypilot-event, x-keypilot-event-id, x-keypilot-timestamp et x-keypilot-signature. La signature est v1= suivi du HMAC-SHA256 hexadécimal de "<timestamp>.<corps brut>" avec votre secret webhook. Comparez de façon timing-safe et ne traitez chaque id d'événement qu'une seule fois.
import crypto from "node:crypto"; // rawBody: the exact request body string, before JSON.parse function verifyKeypilotWebhook(rawBody, secret, timestamp, signature) { const expected = "v1=" + crypto.createHmac("sha256", secret) .update(timestamp + "." + rawBody) .digest("hex"); return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected)); }
Référence des endpoints
Cette référence est rendue directement depuis la spécification OpenAPI et ne peut donc jamais être obsolète. URL de base de tous les endpoints v1 : https://www.keypilot.eu/api/v1.
Properties
Buildings and units for rent or sale.
GET
/api/v1/properties
properties:read
List properties
Returns your properties ordered by id, with cursor pagination.
Paramètres:
limit (query), cursor (query)
POST
/api/v1/properties
properties:write
Create a property
Creates a property and emits a `property.created` webhook event.
Paramètres:
Idempotency-Key (header)
GET
/api/v1/properties/{id}
properties:read
Retrieve a property
Paramètres:
id (path)
PATCH
/api/v1/properties/{id}
properties:write
Update a property
Partial update: only the supplied fields change. Emits a `property.updated` webhook event.
Paramètres:
id (path), Idempotency-Key (header)
Contacts
Tenants and contractors. Reads of this resource are audit-logged.
GET
/api/v1/contacts
contacts:read
List contacts
Returns your contacts ordered by id, with cursor pagination.
Paramètres:
limit (query), cursor (query)
POST
/api/v1/contacts
contacts:write
Create a contact
Creates a contact and emits a `contact.created` webhook event. When `propertyId` is supplied it must reference one of your properties.
Paramètres:
Idempotency-Key (header)
GET
/api/v1/contacts/{id}
contacts:read
Retrieve a contact
Paramètres:
id (path)
PATCH
/api/v1/contacts/{id}
contacts:write
Update a contact
Partial update: only the supplied fields change. Emits a `contact.updated` webhook event.
Paramètres:
id (path), Idempotency-Key (header)
Contracts
Rental contracts linked to properties and tenants.
GET
/api/v1/contracts
contracts:read
List contracts
Returns your contracts ordered by id, with cursor pagination.
Paramètres:
limit (query), cursor (query)
POST
/api/v1/contracts
contracts:write
Create a contract
Creates a contract and emits a `contract.created` webhook event. `contractNumber` must be unique per account; new contracts are created as drafts.
Paramètres:
Idempotency-Key (header)
GET
/api/v1/contracts/{id}
contracts:read
Retrieve a contract
Paramètres:
id (path)
PATCH
/api/v1/contracts/{id}
contracts:write
Update a contract
Partial update: only the supplied fields change. Emits a `contract.updated` webhook event. `contractNumber` cannot be changed.
Paramètres:
id (path), Idempotency-Key (header)
Tasks
To-dos, optionally linked to a property or contractor.
GET
/api/v1/tasks
tasks:read
List tasks
Returns your tasks ordered by id, with cursor pagination.
Paramètres:
limit (query), cursor (query)
POST
/api/v1/tasks
tasks:write
Create a task
Creates a task and emits a `task.created` webhook event.
Paramètres:
Idempotency-Key (header)
GET
/api/v1/tasks/{id}
tasks:read
Retrieve a task
Paramètres:
id (path)
PATCH
/api/v1/tasks/{id}
tasks:write
Update a task
Partial update: only the supplied fields change. Emits a `task.updated` webhook event.
Paramètres:
id (path), Idempotency-Key (header)
Maintenance requests
Tenant-reported or API-created maintenance tickets.
GET
/api/v1/maintenance-requests
maintenance:read
List maintenance requests
Returns your maintenance requests ordered by id, with cursor pagination. The resource path is `/api/v1/maintenance-requests`.
Paramètres:
limit (query), cursor (query)
POST
/api/v1/maintenance-requests
maintenance:write
Create a maintenance
Creates a maintenance and emits a `maintenance.created` webhook event. `tenantId` is required and must reference one of your tenants.
Paramètres:
Idempotency-Key (header)
GET
/api/v1/maintenance-requests/{id}
maintenance:read
Retrieve a maintenance
Paramètres:
id (path)
PATCH
/api/v1/maintenance-requests/{id}
maintenance:write
Update a maintenance
Partial update: only the supplied fields change. Emits a `maintenance.updated` webhook event. `tenantId`, `propertyId` and `contractId` cannot be changed.
Paramètres:
id (path), Idempotency-Key (header)
Credentials
API credential management. These endpoints use the web app session (cookie) authentication, not an API key.
GET
/api/integrations/api-credentials
session (app web)
List API credentials
Returns all credentials of the signed-in account, most recent first. Secrets are never returned after creation.
POST
/api/integrations/api-credentials
session (app web)
Create an API credential
The full secret (`kp_<prefix>_<secret>`) is returned exactly once, in this response.
POST
/api/integrations/api-credentials/{id}/rotate
session (app web)
Rotate an API credential
Revokes the credential and issues a new one with the same label and scopes. The new secret is returned once.
Paramètres:
id (path)
DELETE
/api/integrations/api-credentials/{id}
session (app web)
Revoke an API credential
Paramètres:
id (path)
Webhooks
Subscription management (session-authenticated) and the event envelope delivered to your endpoint. Deliveries are signed: `x-keypilot-signature: v1=<hex HMAC-SHA256 of "<timestamp>.<raw body>"` with the subscription secret; verify with `x-keypilot-timestamp`. Failed deliveries retry up to 5 times with exponential backoff (max 60 s).
GET
/api/integrations/webhooks
session (app web)
List webhook subscriptions
POST
/api/integrations/webhooks
session (app web)
Create a webhook subscription
The URL must be HTTPS and resolve to a public address (validated again at every delivery). The signing secret is returned exactly once.
PATCH
/api/integrations/webhooks/{id}
session (app web)
Update a webhook subscription
Enable/disable a subscription, rename it or change the subscribed events.
Paramètres:
id (path)
GET
/api/integrations/webhooks/{id}/deliveries
session (app web)
List recent deliveries
Returns the 100 most recent delivery attempts for a subscription, newest first.
Paramètres:
id (path)
Lisible par machine
Pour les outils, assistants IA et catalogues d'API, Keypilot publie la spécification sur des URLs fixes.