RÉFÉRENCE API — REST v1

Référence API

Gérez vos bases de données PostgreSQL, branches, computes, et plus via REST. URL de base : https://api.lampion.cloud/v1/

Chaque requête nécessite :

Authorization: Bearer lmp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Créez une clé dans Paramètres > Clés API.

CLI lampion projects list MCP Agents IA (Claude, Cursor)

§ 01 — Général

Authentification

Toutes les requêtes API nécessitent un token Bearer. Créez une clé API depuis Paramètres > Clés API dans la console. Les clés sont scopées à votre organisation avec les permissions developer. Elles expirent après 90 jours par défaut. Hiérarchie des rôles RBAC : analyst < viewer < developer < admin/owner. Les analysts n'ont accès qu'aux branches où l'anonymisation est activée et reçoivent une connection string dédiée avec des données masquées.

Projets

Un projet est une base de données PostgreSQL avec branching, monitoring et auto-suspend. Créer un projet provisionne un compute et retourne une connection string prête à l'emploi. Supprimer un projet ne détruit rien tout de suite : il reste restaurable pendant un délai de grâce de 7 jours, puis il est effacé définitivement.

GET /v1/projects

Lister tous les projets.

Requête

curl -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/projects

Réponse

[{"id":"abc123","name":"my-app","region":"fr-par-1"}]

POST /v1/projects

Créer un projet. Retourne la connection string, l'endpoint et le mot de passe.

Requête

curl -X POST -H "Authorization: Bearer $TOKEN"   -H "Content-Type: application/json" \
  -d '{"name":"my-app","region":"fr-par-1"}' https://api.lampion.cloud/v1/projects

Réponse

{"id":"abc123","name":"my-app","endpoint_id":"ep-abc",
 "connection_string":"postgresql://cloud_admin:[email protected]:5432/ep-abc.postgres?sslmode=require",
 "pg_password":"YaQYfbg...","host":"db.lampion.cloud","port":5432}

GET /v1/projects/{project_id}

Récupérer un projet par ID.

Requête

curl -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/projects/{id}

Réponse

{"id":"abc123","name":"my-app","region":"fr-par-1"}

PATCH /v1/projects/{project_id}

Mettre à jour un projet (renommer, modifier les paramètres).

Requête

curl -X PATCH -H "Authorization: Bearer $TOKEN"   -H "Content-Type: application/json" -d '{"name":"my-new-name"}' https://api.lampion.cloud/v1/projects/{id}

Réponse

{"id":"abc123","name":"my-new-name","region":"fr-par-1"}

DELETE /v1/projects/{project_id}

Supprimer un projet (rôle admin). La suppression n'est pas immédiate : le projet passe en `pending_deletion` pour un délai de grâce de 7 jours. Pendant ce délai, ses computes sont arrêtés, les connexions sont refusées, et le projet disparaît des listes (ses routes renvoient 404) ; il reste restaurable. Une fois `purge_after` atteint, une tâche horaire l'efface définitivement : computes, branches, stockage et données associées. Répond 202 Accepted. Journal d'audit : `project.deletion_requested`, puis `project.deleted` à l'effacement définitif.

Requête

curl -X DELETE -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/projects/{id}

Réponse

202 Accepted
{"id":"abc123","status":"pending_deletion",
 "deleted_at":"2026-10-14T09:12:00+00:00","purge_after":"2026-10-21T09:12:00+00:00"}

GET /v1/projects/deleted

Lister les projets de l'organisation en attente de suppression, avec la date de la demande (`deleted_at`) et celle de l'effacement définitif (`purge_after`). Rôle admin.

Requête

curl -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/projects/deleted

Réponse

[{"id":"abc123","name":"my-app",
  "deleted_at":"2026-10-14T09:12:00+00:00","purge_after":"2026-10-21T09:12:00+00:00"}]

POST /v1/projects/{project_id}/restore

Restaurer un projet en attente de suppression (rôle admin). Renvoie le projet, sous la même forme que `GET /v1/projects/{project_id}`. Ses computes restent suspendus et se réveillent à la prochaine connexion. 404 si le projet est inconnu, 409 s'il n'est pas en attente de suppression ou si le restaurer dépasserait le quota de projets ou de computes du plan, 410 si le délai de grâce est écoulé. Journal d'audit : `project.restored`.

Requête

curl -X POST -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/projects/{id}/restore

Réponse

{"id":"abc123","name":"my-app","region":"fr-par-1"}

Branches

Forks en copy-on-write. Créées en moins d'une seconde pour les tests, le staging, ou la CI. Les scripts seed s'exécutent automatiquement sur les nouvelles branches. Une branch garde son identifiant pour toujours ; celui de la branch main est l'identifiant du projet.

GET /v1/projects/{id}/branches

Lister toutes les branches.

Requête

curl -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/projects/{id}/branches

Réponse

[{"id":"{id}","name":"main","is_primary":true},{"id":"feat","name":"staging"}]

POST /v1/projects/{id}/branches

Créer une branch (fork). Provisionne un nouveau compute. ttl_hours optionnel (1 à 720 h ; 0 ou absent = pas d'expiration, 400 hors bornes). Le nom doit être unique dans le projet : 409 s'il est déjà pris. Une branch créée depuis une branch masquée hérite de son anonymisation (statut et règles).

Requête

curl -X POST -H "Authorization: Bearer $TOKEN"   -H "Content-Type: application/json" \
  -d '{"name":"staging","parent_id":"{id}","ttl_hours":24}' https://api.lampion.cloud/v1/projects/{id}/branches

Réponse

{"id":"feat","name":"staging","ttl_hours":24,"anon_enabled":false,"compute_id":"ep-new"}

PATCH /v1/projects/{id}/branches/{bid}

Mettre à jour les paramètres d'une branch : TTL de suppression automatique (ttl_hours de 1 à 720 h, 0 ou null le retire, 400 hors bornes) et statut protected. À expiration du TTL, la branch est supprimée comme par DELETE : compute, données et métadonnées.

Requête

curl -X PATCH -H "Authorization: Bearer $TOKEN"   -H "Content-Type: application/json" -d '{"ttl_hours":24,"protected":true}' https://api.lampion.cloud/v1/projects/{id}/branches/{bid}

Réponse

{"id":"feat","name":"staging","ttl_hours":24,"protected":true}

POST .../{bid}/reset

Réinitialiser une branch à l'état actuel de son parent (comme git reset --hard). La branch reçoit des données neuves et un nouveau compute, et garde son identifiant et ses paramètres ; rien ne change si la réinitialisation échoue.

Requête

curl -X POST -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/projects/{id}/branches/{bid}/reset

Réponse

{"id":"feat","name":"staging","compute_id":"ep-new2"}

POST .../{bid}/merge

Fusionner les changements de schéma (DDL uniquement) de cette branch vers son parent. Utilisez dry_run=true pour prévisualiser le SQL.

Requête

curl -X POST -H "Authorization: Bearer $TOKEN"   -H "Content-Type: application/json" \
  -d '{"dry_run":true}' https://api.lampion.cloud/v1/projects/{id}/branches/{bid}/merge

Réponse

{"success":true,"dry_run":true,
 "migration_sql":"ALTER TABLE users ADD COLUMN avatar TEXT;",
 "changes":{"total_changes":1},"duration_ms":0}

DELETE /v1/projects/{id}/branches/{bid}

Supprimer une branch et son compute.

Requête

curl -X DELETE -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/projects/{id}/branches/{bid}

Réponse

204 No Content

POST .../{bid}/promote

Promouvoir une branch en main : main reprend les données actuelles de la branch et garde son identifiant. Opération destructive : les anciennes données et le compute de main sont remplacés. Rôle admin requis.

Requête

curl -X POST -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/projects/{id}/branches/{bid}/promote

Réponse

{"success":true,"promoted_from":"staging",
 "new_main":{"id":"{id}","name":"main","is_primary":true}}

POST .../migration-preview

Prévisualiser le SQL de migration entre une branch et son parent, sans rien appliquer.

Requête

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"branch_id":"feat"}' https://api.lampion.cloud/v1/projects/{id}/migration-preview

Réponse

{"migration_sql":"ALTER TABLE users ADD COLUMN avatar TEXT;",
 "changes":{"total_changes":1}}

Endpoints (Computes)

Instances compute PostgreSQL. Suspendez/reprenez, redimensionnez à chaud, configurez l'auto-suspend, gérez les listes d'autorisation IP.

GET /v1/projects/{id}/endpoints/{eid}

Récupérer un endpoint par ID (statut, connection string, paramètres).

Requête

curl -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/projects/{id}/endpoints/{eid}

Réponse

{"id":"ep-abc","status":"running","connection_string":"postgresql://...","auto_suspend_seconds":300,"compute_cu":0.25}

GET /v1/projects/{id}/endpoints

Lister les endpoints avec leurs connection strings. Le mot de passe cloud_admin (pg_password, et celui inclus dans connection_string) n'est renvoyé qu'aux rôles developer et au-dessus ; viewer et analyst reçoivent null et la forme masquée ********.

Requête

curl -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/projects/{id}/endpoints

Réponse

[{"id":"ep-abc","status":"running",
  "connection_string":"postgresql://cloud_admin:********@db.lampion.cloud:5432/ep-abc.postgres?sslmode=require",
  "pg_password":null}]
// viewer / analyst : masque. developer et au-dessus : valeur en clair.

POST .../{eid}/suspend

Suspendre (scale to zero).

Requête

curl -X POST -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/projects/{id}/endpoints/{eid}/suspend

Réponse

{"id":"ep-abc","status":"suspended"}

POST .../{eid}/resume

Reprendre un compute suspendu.

Requête

curl -X POST -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/projects/{id}/endpoints/{eid}/resume

Réponse

{"id":"ep-abc","status":"running"}

PATCH .../{eid}

Mettre à jour les paramètres (auto_suspend_seconds). Durée en secondes ; 0 = ne jamais suspendre (plans payants uniquement) ; les valeurs négatives sont refusées.

Requête

curl -X PATCH -H "Authorization: Bearer $TOKEN"   -H "Content-Type: application/json" -d '{"auto_suspend_seconds":600}' https://api.lampion.cloud/v1/projects/{id}/endpoints/{eid}

Réponse

{"id":"ep-abc","auto_suspend_seconds":600}

GET .../{eid}/allowlist

Récupérer la liste d'autorisation IP.

Requête

curl -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/projects/{id}/endpoints/{eid}/allowlist

Réponse

{"cidrs":["10.0.0.0/8"],"allow_console_access":true}

PUT .../{eid}/allowlist

Remplacer la liste d'autorisation IP.

Requête

curl -X PUT -H "Authorization: Bearer $TOKEN"   -H "Content-Type: application/json" -d '{"allowlist":["10.0.0.0/8"]}' https://api.lampion.cloud/v1/projects/{id}/endpoints/{eid}/allowlist

Réponse

{"cidrs":["10.0.0.0/8"],"allow_console_access":true}

GET /v1/projects/{id}/endpoints/compute-sizes

Lister les tailles de compute disponibles (paliers CU), avec le max_connections réellement appliqué (100 à 3357).

Requête

curl -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/projects/{id}/endpoints/compute-sizes

Réponse

[{"cu":0.25,"label":"0.25 CU","vcpu":0.25,"memory_gb":0.5,"shared_buffers_mb":64,"max_connections":100},{"cu":1,"label":"1 CU","vcpu":1,"memory_gb":4,"shared_buffers_mb":512,"max_connections":419},{"cu":4,"label":"4 CU","vcpu":4,"memory_gb":16,"shared_buffers_mb":2048,"max_connections":1678}]

PATCH .../{eid}

Changer la taille du compute (compute_cu, parmi les paliers de compute-sizes ; 1 CU = 1 vCPU + 4 Gio). Le compute est redimensionné aussitôt, à chaud et sans couper une connexion chaque fois que c'est possible : toute hausse, et une baisse modérée. Sinon il redémarre brièvement à la nouvelle taille ; un compute suspendu la prend à son prochain réveil. Le champ resize_method de la réponse dit ce qui s'est passé : in_place (à chaud), restart (redémarrage court) ou deferred (appliquée au prochain démarrage). 409 si la capacité manque pour l'instant : la taille actuelle est conservée, réessayez plus tard. Bornes d'autoscaling min_cu/max_cu : des paliers de compute-sizes, min_cu ≤ max_cu et max_cu ≤ 8 × min_cu, 0 ou moins efface la borne — validées et enregistrées dès maintenant pour l'autoscaling automatique, en préparation. 400 si une valeur est invalide, 403 si votre plan est limité à 0.25 CU, 502 en cas d'erreur interne. Une requête refusée ne modifie rien.

Requête

curl -X PATCH -H "Authorization: Bearer $TOKEN"   -H "Content-Type: application/json" \
  -d '{"compute_cu":2,"min_cu":0.5,"max_cu":4}' https://api.lampion.cloud/v1/projects/{id}/endpoints/{eid}

Réponse

{"id":"ep-abc","compute_cu":2,"min_cu":0.5,"max_cu":4,"resize_method":"in_place"}

§ 02 — SQL & Schéma

Exécution SQL

Exécutez des requêtes via l'API. Prend en charge les scripts multi-instructions et les méta-commandes psql.

POST .../{eid}/sql

Exécuter du SQL. Retourne les colonnes, les lignes, la durée.

Requête

curl -X POST -H "Authorization: Bearer $TOKEN"   -H "Content-Type: application/json" \
  -d '{"query":"SELECT * FROM users LIMIT 5"}' https://api.lampion.cloud/v1/projects/{id}/endpoints/{eid}/sql

Réponse

{"columns":["id","name"],"rows":[{"id":1,"name":"Alice"}],"duration":12}

Introspection de schéma

Parcourez les databases, schémas, tables et colonnes.

GET /v1/projects/{id}/schema

Sans paramètre = databases. ?database=X = schémas. ?database=X&schema=Y = tables + colonnes.

Requête

curl -H "Authorization: Bearer $TOKEN" "https://api.lampion.cloud/v1/projects/{id}/schema?database=postgres&schema=public"

Réponse

{"type":"tables","items":[{"name":"users","columns":[{"name":"id","type":"integer"},{"name":"email","type":"text"}]}]}

Bases de données

CRUD des bases de données PostgreSQL au sein d'un endpoint.

GET .../{eid}/databases

Lister les bases de données.

Requête

curl -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/projects/{id}/endpoints/{eid}/databases

Réponse

[{"name":"postgres","encoding":"UTF8","size_bytes":8945664}]

POST .../{eid}/databases

Créer une base de données.

Requête

curl -X POST -H "Authorization: Bearer $TOKEN"   -H "Content-Type: application/json" -d '{"name":"myapp"}' https://api.lampion.cloud/v1/projects/{id}/endpoints/{eid}/databases

Réponse

{"name":"myapp"}

DELETE .../{eid}/databases/{name}

Supprimer une base de données.

Requête

curl -X DELETE -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/projects/{id}/endpoints/{eid}/databases/myapp

Réponse

204 No Content

Rôles

Gérez les rôles PostgreSQL.

GET .../{eid}/roles

Lister les rôles.

Requête

curl -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/projects/{id}/endpoints/{eid}/roles

Réponse

[{"name":"cloud_admin","superuser":true,"can_login":true,
  "createdb":true,"connection_limit":-1,"password":null}]
// password : renseigne pour cloud_admin a partir du role developer.

POST .../{eid}/roles

Créer un rôle. password optionnel (16 à 128 caractères, rôle avec can_login uniquement, 422 hors bornes) ; sans lui, un mot de passe est généré et renvoyé une seule fois. Un mot de passe fourni n'est jamais renvoyé. Sur une branch dont l'anonymisation est activée, le rôle reçoit le label MASKED (masked: true) et ne voit que des données masquées ; si le label ne peut pas être posé, le rôle n'est pas créé (502).

Requête

curl -X POST -H "Authorization: Bearer $TOKEN"   -H "Content-Type: application/json" -d '{"name":"appuser","can_login":true}' https://api.lampion.cloud/v1/projects/{id}/endpoints/{eid}/roles

Réponse

{"name":"appuser","can_login":true,"superuser":false,
 "password":"genere-visible-une-seule-fois","masked":false}

DELETE .../{eid}/roles/{name}

Supprimer un rôle.

Requête

curl -X DELETE -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/projects/{id}/endpoints/{eid}/roles/appuser

Réponse

204 No Content

POST .../{eid}/roles/{name}/reset-password

Générer un nouveau mot de passe pour un rôle. Visible une seule fois dans la réponse.

Requête

curl -X POST -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/projects/{id}/endpoints/{eid}/roles/appuser/reset-password

Réponse

{"name":"appuser","password":"new-generated-password-xyz"}

Permissions

Gérez les privilèges au niveau des tables (GRANT/REVOKE). Privilèges pris en charge : SELECT, INSERT, UPDATE, DELETE, TRUNCATE, REFERENCES, TRIGGER, ALL.

GET .../{eid}/permissions

Lister les grants au niveau des tables pour l'endpoint.

Requête

curl -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/projects/{id}/endpoints/{eid}/permissions

Réponse

[{"table":"public.users","role":"appuser","privileges":["SELECT","INSERT","UPDATE"]},{"table":"public.orders","role":"appuser","privileges":["SELECT"]}]

GET .../{eid}/permissions/tables

Lister les tables disponibles pour l'attribution de permissions.

Requête

curl -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/projects/{id}/endpoints/{eid}/permissions/tables

Réponse

[{"table_schema":"public","table_name":"users"},
 {"table_schema":"public","table_name":"orders"}]

POST .../{eid}/permissions/grant

Accorder des privilèges sur une table à un rôle.

Requête

curl -X POST -H "Authorization: Bearer $TOKEN"   -H "Content-Type: application/json" \
  -d '{"role":"appuser","table_schema":"public","table_name":"users","privileges":["SELECT","INSERT"]}' \
  https://api.lampion.cloud/v1/projects/{id}/endpoints/{eid}/permissions/grant

Réponse

{"status":"granted","privileges":["SELECT","INSERT"],"target":"users","role":"appuser"}

POST .../{eid}/permissions/revoke

Révoquer des privilèges sur une table à un rôle.

Requête

curl -X POST -H "Authorization: Bearer $TOKEN"   -H "Content-Type: application/json" \
  -d '{"role":"appuser","table_schema":"public","table_name":"users","privileges":["INSERT"]}' \
  https://api.lampion.cloud/v1/projects/{id}/endpoints/{eid}/permissions/revoke

Réponse

{"status":"revoked","privileges":["INSERT"],"target":"users","role":"appuser"}

Tables (DDL)

Créez, supprimez et modifiez des tables et colonnes via l'API. Toutes les opérations exécutent des instructions DDL sur l'endpoint cible.

POST .../{eid}/tables

Créer une table avec des colonnes (nom, type, clé primaire, NOT NULL).

Requête

curl -X POST -H "Authorization: Bearer $TOKEN"   -H "Content-Type: application/json" \
  -d '{"name":"orders","columns":[{"name":"id","type":"serial","primary_key":true},{"name":"total","type":"numeric","nullable":false}]}' \
  https://api.lampion.cloud/v1/projects/{id}/endpoints/{eid}/tables

Réponse

{"name":"orders","schema":"public","columns":2}

DELETE .../{eid}/tables/{table}

Supprimer une table. Irréversible.

Requête

curl -X DELETE -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/projects/{id}/endpoints/{eid}/tables/orders

Réponse

204 No Content

POST .../{eid}/tables/{table}/rename

Renommer une table.

Requête

curl -X POST -H "Authorization: Bearer $TOKEN"   -H "Content-Type: application/json" \
  -d '{"new_name":"customer_orders"}' https://api.lampion.cloud/v1/projects/{id}/endpoints/{eid}/tables/orders/rename

Réponse

{"old_name":"orders","new_name":"customer_orders"}

POST .../{eid}/tables/{table}/columns

Ajouter une colonne à une table.

Requête

curl -X POST -H "Authorization: Bearer $TOKEN"   -H "Content-Type: application/json" \
  -d '{"name":"status","type":"text","nullable":true,"default":"'pending'"}' \
  https://api.lampion.cloud/v1/projects/{id}/endpoints/{eid}/tables/orders/columns

Réponse

{"column":"status","type":"text"}

DELETE .../{eid}/tables/{table}/columns/{col}

Supprimer une colonne d'une table.

Requête

curl -X DELETE -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/projects/{id}/endpoints/{eid}/tables/orders/columns/status

Réponse

204 No Content

POST .../{eid}/tables/{table}/columns/rename

Renommer une colonne.

Requête

curl -X POST -H "Authorization: Bearer $TOKEN"   -H "Content-Type: application/json" \
  -d '{"old_name":"total","new_name":"total_amount"}' \
  https://api.lampion.cloud/v1/projects/{id}/endpoints/{eid}/tables/orders/columns/rename

Réponse

{"old_name":"total","new_name":"total_amount"}

PATCH .../{eid}/tables/{table}/columns/{col}

Modifier une colonne (type, nullable, valeur par défaut).

Requête

curl -X PATCH -H "Authorization: Bearer $TOKEN"   -H "Content-Type: application/json" \
  -d '{"column":"total","new_type":"numeric(10,2)","set_nullable":false,"set_default":"0"}' \
  https://api.lampion.cloud/v1/projects/{id}/endpoints/{eid}/tables/orders/columns/total

Réponse

{"table":"orders","column":"total","changes":2}

Extensions

Installez et gérez les extensions PostgreSQL.

GET .../{eid}/extensions

Lister les extensions.

Requête

curl -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/projects/{id}/endpoints/{eid}/extensions

Réponse

[{"name":"plpgsql","default_version":"1.0","installed_version":"1.0","comment":"PL/pgSQL"},
 {"name":"pgvector","default_version":"0.7.0","installed_version":null,"comment":"vector types"}]

POST .../{eid}/extensions

Installer une extension.

Requête

curl -X POST -H "Authorization: Bearer $TOKEN"   -H "Content-Type: application/json" -d '{"name":"pgvector"}' https://api.lampion.cloud/v1/projects/{id}/endpoints/{eid}/extensions

Réponse

{"name":"pgvector","default_version":"0.7.0","installed_version":"0.7.0","comment":"vector types"}

DELETE .../{eid}/extensions/{name}

Désinstaller une extension.

Requête

curl -X DELETE -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/projects/{id}/endpoints/{eid}/extensions/pgvector

Réponse

204 No Content

§ 03 — Gestion des données

Seeds de base de données

Attachez jusqu'à 10 scripts SQL ordonnés par projet. Ils s'exécutent automatiquement sur chaque nouvelle branch — données de test, fixtures, extensions. Réordonnez-les, activez/désactivez-les individuellement.

GET /v1/projects/{id}/seeds

Lister tous les scripts seed de ce projet.

Requête

curl -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/projects/{id}/seeds

Réponse

[{"id":"seed-1","name":"fixtures","sql":"INSERT INTO ...","position":1,"enabled":true}]

POST /v1/projects/{id}/seeds

Créer un nouveau script seed.

Requête

curl -X POST -H "Authorization: Bearer $TOKEN"   -H "Content-Type: application/json" \
  -d '{"name":"fixtures","sql":"INSERT INTO users (name) VALUES (\'Alice\');"}' \
  https://api.lampion.cloud/v1/projects/{id}/seeds

Réponse

{"id":"seed-1","name":"fixtures","position":1,"enabled":true}

PATCH /v1/projects/{id}/seeds/{seed_id}

Mettre à jour un seed (nom, sql, activation).

Requête

curl -X PATCH -H "Authorization: Bearer $TOKEN"   -H "Content-Type: application/json" \
  -d '{"enabled":false}' https://api.lampion.cloud/v1/projects/{id}/seeds/{seed_id}

Réponse

{"id":"seed-1","enabled":false}

DELETE /v1/projects/{id}/seeds/{seed_id}

Supprimer un script seed.

Requête

curl -X DELETE -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/projects/{id}/seeds/{seed_id}

Réponse

204 No Content

POST /v1/projects/{id}/seeds/reorder

Réordonner les scripts seed.

Requête

curl -X POST -H "Authorization: Bearer $TOKEN"   -H "Content-Type: application/json" \
  -d '{"ids":["seed-2","seed-1","seed-3"]}' https://api.lampion.cloud/v1/projects/{id}/seeds/reorder

Réponse

{"ok":true}

GET /v1/projects/{id}/seed

Lire le seed historique du projet — un unique script, antérieur aux seeds ordonnés ci-dessus. Renvoie une chaîne vide si aucun n'est défini.

Requête

curl -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/projects/{id}/seed

Réponse

{"seed_sql":"CREATE EXTENSION IF NOT EXISTS pgvector;"}

PUT /v1/projects/{id}/seed

Définir ou effacer ce seed historique. Envoyer `null` l'efface.

Requête

curl -X PUT -H "Authorization: Bearer $TOKEN"   -H "Content-Type: application/json"   -d '{"seed_sql":"CREATE EXTENSION IF NOT EXISTS pgvector;"}'   https://api.lampion.cloud/v1/projects/{id}/seed

Réponse

{"seed_sql":"CREATE EXTENSION IF NOT EXISTS pgvector;"}

Replay de requêtes

Capturez les requêtes les plus fréquentes d'une branch (via pg_stat_statements) et rejouez-les sur une autre pour détecter des régressions de performance après une migration.

POST /v1/projects/{id}/replay

Rejoue les N requêtes principales de la source sur la cible. Retourne une comparaison des temps avec détection de régression.

Requête

curl -X POST -H "Authorization: Bearer $TOKEN"   -H "Content-Type: application/json" \
  -d '{"source_endpoint_id":"ep-main","target_endpoint_id":"ep-staging","limit":20}' \
  https://api.lampion.cloud/v1/projects/{id}/replay

Réponse

{"queries":[{"query":"SELECT...","source_mean_ms":1.2,"target_mean_ms":3.8,"ratio":3.17,"status":"regression"}],"summary":{"total":20,"regressions":2,"improvements":5,"stable":13}}

Backups & PITR

Prenez un snapshot de votre base de données à tout moment. Restaurez vers une nouvelle branch sans toucher à la production.

GET /v1/projects/{id}/backups

Lister les snapshots de sauvegarde.

Requête

curl -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/projects/{id}/backups

Réponse

[{"id":"bk-42","name":"before-migration","branch_id":"main-tid","lsn":"0/15A2C08","created_at":"2026-04-01T10:00:00Z"}]

GET /v1/projects/{id}/backups/{bid}

Récupérer une sauvegarde par ID.

Requête

curl -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/projects/{id}/backups/{bid}

Réponse

{"id":"bk-42","name":"before-migration","lsn":"0/15A2C08"}

POST /v1/projects/{id}/backups

Créer un snapshot de sauvegarde.

Requête

curl -X POST -H "Authorization: Bearer $TOKEN"   -H "Content-Type: application/json" \
  -d '{"name":"before-migration","branch_id":"main-tid"}' https://api.lampion.cloud/v1/projects/{id}/backups

Réponse

{"id":"bk-42","name":"before-migration","lsn":"0/15A2C08"}

DELETE /v1/projects/{id}/backups/{bid}

Supprimer une sauvegarde.

Requête

curl -X DELETE -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/projects/{id}/backups/{bid}

Réponse

204 No Content

POST /v1/projects/{id}/backups/{bid}/restore

Restaurer vers une nouvelle branch à ce LSN.

Requête

curl -X POST -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/projects/{id}/backups/{bid}/restore

Réponse

{"id":"tl-restored","project_id":"abc123","name":"restored-bk-42",
 "restored_from_backup":"bk-42","lsn":"0/15A2C08","compute_id":"ep-new"}

Export de base de données

Exportez votre base de données dans plusieurs formats via pg_dump. Filtrable par database ou table. Trois formats : SQL brut (.sql), compressé personnalisé (.dump pour pg_restore), et CSV (export d'une seule table).

GET .../{eid}/dump

Télécharger l'export de la base de données. ?format=plain|custom|csv (plain par défaut). ?database=X&table=Y pour une seule table. Le format CSV requiert le paramètre table.

Requête

curl -H "Authorization: Bearer $TOKEN" "https://api.lampion.cloud/v1/projects/{id}/endpoints/{eid}/dump?format=plain" -o dump.sql

Réponse

-- SQL dump saved to dump.sql

GET .../{eid}/dump

Exporter au format custom (compressé, pour pg_restore).

Requête

curl -H "Authorization: Bearer $TOKEN" "https://api.lampion.cloud/v1/projects/{id}/endpoints/{eid}/dump?format=custom" -o dump.dump

Réponse

-- Binary dump saved to dump.dump (restore with pg_restore)

GET .../{eid}/dump

Exporter une seule table en CSV (COPY TO STDOUT).

Requête

curl -H "Authorization: Bearer $TOKEN" "https://api.lampion.cloud/v1/projects/{id}/endpoints/{eid}/dump?format=csv&database=postgres&table=users" -o users.csv

Réponse

-- CSV saved to users.csv

GET .../{eid}/export

Export complet de l'endpoint en une archive `.tar.gz` : un manifeste portant l'empreinte SHA-256 de chaque fichier, les rôles (sans mots de passe) et un fichier pg_dump au format custom par base de données. Rôle `developer` minimum. Équivalent CLI : `lampion export`.

Requête

curl -H "Authorization: Bearer $TOKEN" -o export.tar.gz "https://api.lampion.cloud/v1/projects/{id}/endpoints/{eid}/export"
# CLI
lampion export <pid> <eid>

Réponse

HTTP/1.1 200 OK
Content-Type: application/gzip
-- export.tar.gz: manifest (SHA-256 per file) + roles (no passwords)
-- + one pg_dump custom-format file per database (restore with pg_restore)

Replicas en lecture

Ajoutez des replicas en lecture seule à n'importe quelle branch. Chaque replica a sa propre connection string et peut être suspendu indépendamment.

GET /v1/projects/{id}/branches/{bid}/replicas

Lister les replicas d'une branch.

Requête

curl -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/projects/{id}/branches/{bid}/replicas

Réponse

[{"id":"rep-1","status":"running","connection_string":"postgresql://...","type":"read_only"}]

POST /v1/projects/{id}/branches/{bid}/replicas

Créer un replica en lecture.

Requête

curl -X POST -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/projects/{id}/branches/{bid}/replicas

Réponse

{"id":"rep-1","status":"running","connection_string":"postgresql://...","type":"read_only"}

DELETE .../{rid}

Supprimer un replica.

Requête

curl -X DELETE -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/projects/{id}/branches/{bid}/replicas/{rid}

Réponse

204 No Content

POST .../{rid}/suspend

Suspendre un replica.

Requête

curl -X POST -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/projects/{id}/branches/{bid}/replicas/{rid}/suspend

Réponse

{"id":"rep-1","status":"suspended"}

POST .../{rid}/resume

Reprendre un replica suspendu.

Requête

curl -X POST -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/projects/{id}/branches/{bid}/replicas/{rid}/resume

Réponse

{"id":"rep-1","status":"running"}

Import de base de données

Importez une base de données PostgreSQL externe dans une nouvelle branch via pg_dump | psql. Valide la source, vérifie la compatibilité des extensions, et crée la branch automatiquement.

POST /v1/projects/{id}/import/validate

Valider le DSN source : teste la connexion, vérifie la version PG, la taille, la compatibilité des extensions.

Requête

curl -X POST -H "Authorization: Bearer $TOKEN"   -H "Content-Type: application/json" \
  -d '{"source_dsn":"postgresql://user:pass@host:5432/mydb"}' \
  https://api.lampion.cloud/v1/projects/{id}/import/validate

Réponse

{"ok":true,"errors":[],"source":{"pg_version":"17.5","size_mb":142,"table_count":12,"extensions":[{"name":"pgvector","version":"0.8.0","available_on_target":true}]}}

POST /v1/projects/{id}/import/start

Démarrer l'import. Crée une nouvelle branch et pipe pg_dump | psql depuis le DSN source.

Requête

curl -X POST -H "Authorization: Bearer $TOKEN"   -H "Content-Type: application/json" \
  -d '{"source_dsn":"postgresql://user:pass@host:5432/mydb","branch_name":"imported"}' \
  https://api.lampion.cloud/v1/projects/{id}/import/start

Réponse

{"branch_id":"imp-tid","branch_name":"imported","compute_id":"ep-imp",
 "restore_stats":{"tables":12},"extensions_installed":["pgvector"],"extensions_skipped":[]}
// Appel synchrone : la reponse arrive une fois l'import termine.

§ 04 — Sécurité & Confidentialité

Masquage PII (Anonymisation)

Masquez dynamiquement des colonnes sensibles sur une branch avec postgresql_anonymizer. Activez par branch (jamais en production : refusé avec un 400 sur la branch primaire), définissez des règles par colonne, choisissez parmi une allowlist stricte de fonctions de masquage. Une fois activé, un rôle PostgreSQL lampion_analyst avec le label MASKED est créé automatiquement. Les utilisateurs avec le rôle RBAC analyst reçoivent un analyst_connection_string dédié qui se connecte en tant que lampion_analyst et ne voit que les données anonymisées. Ce champ est exposé par GET /v1/projects/{id}/endpoints, pas par les routes d'anonymisation. Les rôles créés après l'activation sont masqués eux aussi, et une branch créée depuis une branch masquée hérite du masquage.

GET .../branches/{bid}/anonymization

Récupérer le statut d'anonymisation et les règles actives.

Requête

curl -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/projects/{id}/branches/{bid}/anonymization

Réponse

{"enabled":true,"rules":[{"id":"r-1","schema_name":"public","table_name":"users","column_name":"email","masking_function":"anon.fake_email()"}]}

POST .../anonymization/enable

Activer le masquage dynamique sur cette branch. Installe l'extension anon, applique toutes les règles, et crée un rôle PostgreSQL lampion_analyst avec le label MASKED. L'analyst_connection_string correspondant devient alors disponible sur GET /v1/projects/{id}/endpoints. 400 sur la branch primaire.

Requête

curl -X POST -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/projects/{id}/branches/{bid}/anonymization/enable

Réponse

{"enabled":true}

POST .../anonymization/disable

Désactiver le masquage et supprimer tous les labels de sécurité.

Requête

curl -X POST -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/projects/{id}/branches/{bid}/anonymization/disable

Réponse

{"enabled":false}

GET .../anonymization/functions

Lister les fonctions de masquage autorisées (allowlist anti-injection).

Requête

curl -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/projects/{id}/branches/{bid}/anonymization/functions

Réponse

[{"function":"anon.fake_email()","description":"Fake email address"},{"function":"anon.fake_iban()","description":"Fake IBAN"},{"function":"anon.hash({COL})","description":"SHA256 hash"}]

GET .../anonymization/rules

Lister les règles de masquage de cette branch.

Requête

curl -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/projects/{id}/branches/{bid}/anonymization/rules

Réponse

[{"id":"r-1","schema_name":"public","table_name":"users","column_name":"email","masking_function":"anon.fake_email()"}]

POST .../anonymization/rules

Ajouter une règle de masquage. Si l'anonymisation est activée, la règle est appliquée immédiatement ; si elle ne peut pas l'être (colonne inexistante, compute injoignable), elle n'est pas enregistrée et l'API répond 502. 400 sur la branch primaire.

Requête

curl -X POST -H "Authorization: Bearer $TOKEN"   -H "Content-Type: application/json" \
  -d '{"table_name":"users","column_name":"email","masking_function":"anon.fake_email()"}' \
  https://api.lampion.cloud/v1/projects/{id}/branches/{bid}/anonymization/rules

Réponse

{"id":"r-1","schema_name":"public","table_name":"users","column_name":"email","masking_function":"anon.fake_email()"}

DELETE .../anonymization/rules/{rule_id}

Supprimer une règle de masquage. Retire le label de sécurité en direct si activé.

Requête

curl -X DELETE -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/projects/{id}/branches/{bid}/anonymization/rules/{rule_id}

Réponse

204 No Content

§ 05 — Observabilité

Métriques & Usage

Métriques en temps réel et usage mensuel pour la facturation.

GET /v1/projects/{id}/metrics

En direct : connexions, ratio de cache, stockage, CPU, mémoire.

Requête

curl -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/projects/{id}/metrics

Réponse

{"connections_total":5,"cache_hit_ratio":98.5,"storage_logical_mb":42.3,"compute_cpu_seconds":123.4}

GET /v1/projects/{id}/metrics/history

Métriques historiques (24h max, toutes les 30s).

Requête

curl -H "Authorization: Bearer $TOKEN" "https://api.lampion.cloud/v1/projects/{id}/metrics/history?hours=6"

Réponse

[{"snapshot_at":"...","connections_total":3,"storage_logical_mb":42.1}]

GET /v1/projects/{id}/usage

Mensuel : heures de compute, stockage en Go, transfert en Go.

Requête

curl -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/projects/{id}/usage

Réponse

{"compute_hours":12.5,"storage_gb":0.042,"transfer_total_gb":0.001,"period":"2026-03"}

GET /v1/usage

Usage à l'échelle de l'organisation avec les informations du plan et une estimation des coûts.

Requête

curl -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/usage

Réponse

{"plan":{"name":"startup"},"total":{"compute_hours":25},"estimated_cost":{"total_eur":2.50}}

GET /v1/projects/{id}/metrics/compute-history

Historique d'usage du compute (événements suspend/resume).

Requête

curl -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/projects/{id}/metrics/compute-history

Réponse

[{"id":"csl-1","project_id":"abc123","endpoint_id":"ep-abc",
  "state":"running","trigger":"resume","created_at":"2026-09-20T10:00:00Z"}]

GET /v1/projects/{id}/metrics/vacuum

Statistiques vacuum et autovacuum par table.

Requête

curl -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/projects/{id}/metrics/vacuum

Réponse

{"tables":[{"schema":"public","table":"users","live_tuples":1200,"dead_tuples":42,
   "dead_pct":3.4,"last_autovacuum":"2026-09-19T22:00:00Z","autovacuum_count":3}],
 "transaction_id":{"oldest_xid_age":120,"wraparound_pct":0.01,"warning":false}}

Analyse des requêtes

Tableau de bord des requêtes lentes via pg_stat_statements. Top des requêtes par temps total, temps moyen, ou nombre d'appels.

GET .../{eid}/analyse/slow-queries

Top des requêtes lentes. ?order_by=total_time|mean_time|calls&limit=30

Requête

curl -H "Authorization: Bearer $TOKEN" "https://api.lampion.cloud/v1/projects/{id}/endpoints/{eid}/analyse/slow-queries?order_by=mean_time"

Réponse

[{"query":"SELECT...","calls":150,"mean_time_ms":12.3,"total_time_ms":1845,"cache_hit_pct":98.5}]

POST .../{eid}/analyse/reset-stats

Réinitialiser tous les compteurs pg_stat_statements.

Requête

curl -X POST -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/projects/{id}/endpoints/{eid}/analyse/reset-stats

Réponse

{"ok":true}

Logs

Logs du serveur PostgreSQL.

GET .../{eid}/logs

Suivre les logs PG en direct. ?lines=N (200 par défaut, max 5000).

Requête

curl -H "Authorization: Bearer $TOKEN" "https://api.lampion.cloud/v1/projects/{id}/endpoints/{eid}/logs?lines=50"

Réponse

{"lines":["2026-03-30 LOG: connection authorized"],"count":50}

Événements du projet

Fil des événements d'un projet : création du projet, de ses endpoints et de ses branches. Déduit de l'état courant des branches, pas d'un journal d'audit — les 20 événements les plus récents, sans pagination, et une suppression n'y laisse pas de trace. Pour un journal complet et horodaté, voir le journal d'audit de l'organisation.

GET /v1/projects/{id}/events

Lister les 20 événements les plus récents du projet, du plus récent au plus ancien.

Requête

curl -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/projects/{id}/events

Réponse

[{"id":"ev-a1b2c3d4","project_id":"abc123","type":"branch.created",
   "message":"Branch staging created","created_at":"2026-09-20T14:02:11+00:00"},
 {"id":"ev-e5f6a7b8-ep","project_id":"abc123","type":"endpoint.created",
   "message":"Endpoint created on branch main","created_at":"2026-09-18T09:41:02+00:00"}]

§ 06 — Organisation

Webhooks

Notifications HTTP sur événements. Payloads signés en HMAC-SHA256.

GET /v1/orgs/webhooks

Lister les webhooks.

Requête

curl -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/orgs/webhooks

Réponse

[{"id":"wh-abc","url":"https://...","events":["*"],"enabled":true}]

POST /v1/orgs/webhooks

Créer un webhook. Retourne le secret de signature.

Requête

curl -X POST -H "Authorization: Bearer $TOKEN"   -H "Content-Type: application/json" \
  -d '{"url":"https://hook.example.com","events":["project.created"]}' https://api.lampion.cloud/v1/orgs/webhooks

Réponse

{"id":"wh-abc","secret":"a1b2c3...","events":["project.created"]}

PATCH /v1/orgs/webhooks/{id}

Mettre à jour un webhook.

Requête

curl -X PATCH -H "Authorization: Bearer $TOKEN"   -H "Content-Type: application/json" -d '{"enabled":false}' https://api.lampion.cloud/v1/orgs/webhooks/{id}

Réponse

{"id":"wh-abc","enabled":false}

DELETE /v1/orgs/webhooks/{id}

Supprimer un webhook.

Requête

curl -X DELETE -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/orgs/webhooks/{id}

Réponse

204 No Content

Membres & Invitations

Gérez les membres de l'organisation, invitez des collaborateurs, transférez la propriété, supprimez l'organisation (restaurable pendant 7 jours). Rôles : owner, admin, developer, viewer, analyst. Le rôle analyst restreint l'accès aux branches avec l'anonymisation activée — les analysts ne voient que les données masquées via une connection string dédiée.

GET /v1/orgs/members

Lister les membres de l'organisation.

Requête

curl -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/orgs/members

Réponse

[{"id":"u-1","email":"[email protected]","role":"owner"},{"id":"u-2","email":"[email protected]","role":"developer"},{"id":"u-3","email":"[email protected]","role":"analyst"}]

PATCH /v1/orgs/members/{uid}/role

Changer le rôle d'un membre. Rôles valides : owner, admin, developer, viewer, analyst.

Requête

curl -X PATCH -H "Authorization: Bearer $TOKEN"   -H "Content-Type: application/json" -d '{"role":"analyst"}' https://api.lampion.cloud/v1/orgs/members/{uid}/role

Réponse

{"id":"u-3","email":"[email protected]","name":"Carol","org_id":"org-1","role":"analyst"}

DELETE /v1/orgs/members/{uid}

Retirer un membre de l'organisation.

Requête

curl -X DELETE -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/orgs/members/{uid}

Réponse

204 No Content

POST /v1/orgs/transfer-ownership

Transférer la propriété à un autre membre.

Requête

curl -X POST -H "Authorization: Bearer $TOKEN"   -H "Content-Type: application/json" -d '{"new_owner_id":"u-2"}' https://api.lampion.cloud/v1/orgs/transfer-ownership

Réponse

{"ok":true}

GET /v1/orgs/invitations

Lister les invitations en attente.

Requête

curl -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/orgs/invitations

Réponse

[{"id":"inv-1","email":"[email protected]","role":"developer","status":"pending"}]

POST /v1/orgs/invitations

Inviter un utilisateur par email.

Requête

curl -X POST -H "Authorization: Bearer $TOKEN"   -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","role":"developer"}' https://api.lampion.cloud/v1/orgs/invitations

Réponse

{"id":"inv-1","email":"[email protected]","role":"developer","status":"pending"}

DELETE /v1/orgs/invitations/{inv_id}

Annuler une invitation en attente.

Requête

curl -X DELETE -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/orgs/invitations/{inv_id}

Réponse

204 No Content

DELETE /v1/orgs

Supprimer l'organisation et toutes ses données (RGPD) : l'organisation visée est celle du token (pour une API key, celle de la clé). Aucun corps. La suppression n'est pas immédiate : l'organisation et tous ses projets passent en `pending_deletion` pour un délai de grâce de 7 jours. Pendant ce délai, les computes sont arrêtés, les connexions sont refusées, et tout autre appel API pour cette organisation renvoie 403 `"Organization is pending deletion"`, sauf la restauration et le statut. Une fois `purge_after` atteint, une tâche horaire efface définitivement chaque projet (branches, computes, stockage, données), puis les webhooks, API keys, invitations, journal d'audit et appartenances. Répond 202 Accepted. Réservé à l'`owner` (403 pour tout autre rôle, `admin` compris). Journal d'audit : `org.deletion_requested`, puis `org.deleted` à l'effacement définitif.

Requête

curl -X DELETE -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/orgs

Réponse

202 Accepted
{"id":"org-1","status":"pending_deletion",
 "deleted_at":"2026-10-14T09:12:00+00:00","purge_after":"2026-10-21T09:12:00+00:00"}

POST /v1/orgs/restore

Restaurer l'organisation pendant le délai de grâce. Les projets supprimés avec elle sont restaurés aussi (`restored_projects`) ; ceux supprimés individuellement avant elle restent en attente de suppression. Réservé à l'`owner`. 409 si l'organisation n'est pas en attente de suppression, 410 si le délai de grâce est écoulé. Journal d'audit : `org.restored`.

Requête

curl -X POST -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/orgs/restore

Réponse

{"id":"org-1","name":"Acme","status":"active","restored_projects":["abc123","def456"]}

GET /v1/orgs/status

Statut de l'organisation : `active` ou `pending_deletion`, avec la date de la demande de suppression (`deleted_at`) et celle de l'effacement définitif (`purge_after`). Ouvert à tout rôle, y compris pendant le délai de grâce.

Requête

curl -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/orgs/status

Réponse

{"id":"org-1","name":"Acme","status":"pending_deletion",
 "deleted_at":"2026-10-14T09:12:00+00:00","purge_after":"2026-10-21T09:12:00+00:00"}

Clés API

Gérez les clés API de votre organisation. Les clés utilisent le préfixe lmp_live_ et ont des permissions de niveau developer.

GET /v1/api-keys

Lister les clés API (valeurs tronquées).

Requête

curl -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/api-keys

Réponse

[{"id":"key-1","name":"CI/CD","key_prefix":"lmp_live_abc...","created_at":"2026-04-01T10:00:00Z"}]

POST /v1/api-keys

Créer une nouvelle clé API. La clé complète n'est retournée qu'une seule fois.

Requête

curl -X POST -H "Authorization: Bearer $TOKEN"   -H "Content-Type: application/json" -d '{"name":"CI/CD"}' https://api.lampion.cloud/v1/api-keys

Réponse

{"id":"key-1","name":"CI/CD","key_value":"lmp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"}
// key_value : visible une seule fois, a la creation.

DELETE /v1/api-keys/{key_id}

Révoquer une clé API.

Requête

curl -X DELETE -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/api-keys/{key_id}

Réponse

204 No Content

Journal d'audit

Chaque organisation dispose d'un journal d'audit horodaté, conservé 12 mois : actions de la console sur les projets, les branches, les API keys, les membres, les rôles et l'anonymisation, ainsi que les exports complets d'endpoint. Disponible pour les rôles admin et owner.

GET /v1/orgs/audit-log

Lister les événements d'audit. ?limit=N&offset=N pour la pagination.

Requête

curl -H "Authorization: Bearer $TOKEN" "https://api.lampion.cloud/v1/orgs/audit-log?limit=10"

Réponse

[{"id":"al-1","action":"project.created","user_email":"[email protected]",
  "resource":"project","resource_id":"my-app","ip_address":"203.0.113.4",
  "created_at":"2026-04-01T10:00:00Z"}]

Compte

Préférences et cycle de vie du compte authentifié : langue, e-mails « Nouveautés », confirmation de l'adresse, suppression. Ces routes agissent sur le compte qui porte le token — pour une API key, celui de son créateur.

PATCH /v1/auth/me/locale

Changer la langue du compte — `fr` ou `en`. Toute autre valeur est refusée.

Requête

curl -X PATCH -H "Authorization: Bearer $TOKEN"   -H "Content-Type: application/json"   -d '{"locale":"en"}' https://api.lampion.cloud/v1/auth/me/locale

Réponse

{"id":"usr_a1b2c3","locale":"en"}

GET /v1/auth/me/email-preferences

Lire l'abonnement aux e-mails « Nouveautés » (`marketing_emails`). Les e-mails de service (maintenance, évolution des CGV/CGU) ne dépendent pas de cette préférence. 404 si le compte est introuvable.

Requête

curl -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/auth/me/email-preferences

Réponse

{"marketing_emails":true}

PATCH /v1/auth/me/email-preferences

S'abonner aux e-mails « Nouveautés » ou s'en désabonner. Corps : `marketing_emails` (booléen, obligatoire, sinon 422). Chaque changement est consigné, pour garder la preuve de votre choix. Le lien de désinscription en pied de ces e-mails a le même effet, sans connexion. 404 si le compte est introuvable.

Requête

curl -X PATCH -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"marketing_emails":false}' https://api.lampion.cloud/v1/auth/me/email-preferences

Réponse

{"marketing_emails":false}

POST /v1/auth/me/resend-verification

Renvoyer le lien de confirmation de l'adresse e-mail du compte. Reste accessible tant que l'adresse n'est pas confirmée : c'est la sortie du blocage. `alreadyVerified: true` si l'adresse est déjà confirmée (rien n'est envoyé). 3 demandes par heure au plus (429 au-delà, avec l'en-tête `Retry-After`), 502 si l'e-mail n'a pas pu partir : l'échec est signalé, jamais masqué.

Requête

curl -X POST -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/auth/me/resend-verification

Réponse

{"ok":true,"alreadyVerified":false}

DELETE /v1/auth/me

Supprimer définitivement votre compte (article 17 du RGPD, droit à l'effacement). Vos API keys, vos appartenances aux organisations, les invitations reçues et vos demandes d'accès à la beta sont supprimées ; votre identité est retirée du journal d'audit et des invitations envoyées, qui restent sous forme anonymisée. `purged` compte les lignes touchées par table. Vos organisations ne sont pas supprimées (voir `DELETE /v1/orgs`). 400 si vous êtes le seul `owner` d'une organisation qui a encore des projets : supprimez-les ou transférez la propriété d'abord. Irréversible.

Requête

curl -X DELETE -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/auth/me

Réponse

{"ok":true,"purged":{"api_keys":1,"org_memberships":1,
 "audit_log_anonymized":12,"console_users":1}}

§ 07 — Infrastructure

Résidence des données

Preuve de l'emplacement physique de vos données. Région, datacenter, provider, certifications de l'hébergeur (distinctes de celles de Lampion), chiffrement par couche tel qu'il est réellement configuré. Exportable en PDF horodaté, portant une empreinte SHA-256 du contenu (format versionné) et une signature Ed25519 de cette empreinte, qui permettent de vérifier que le document n'a pas été modifié et qu'il a bien été émis par Lampion (clés publiques : `GET /v1/compliance/signing-keys`).

GET /v1/projects/{id}/residency

Récupérer le rapport complet de résidence des données d'un projet. Chaque couche de `data_layers` porte un champ `label` (nom lisible). Paramètre locale (`fr` ou `en`, défaut `en`) : traduit `label`, `description` et les valeurs de chiffrement des couches.

Requête

curl -H "Authorization: Bearer $TOKEN" "https://api.lampion.cloud/v1/projects/{id}/residency?locale=fr"

Réponse

{"region_id":"fr-par-1","region":{"city":"Paris","provider":"Scaleway","datacenter":"DC2","certifications":["ISO 27001","HDS"]},"data_layers":[...],"compliance":{"data_in_country":"France"}}

GET /v1/projects/{id}/residency.pdf

Rapport de résidence du projet en PDF horodaté. L'empreinte SHA-256 imprimée en pied de page est aussi renvoyée dans l'en-tête `X-Lampion-Report-Digest`, et sa signature Ed25519 dans l'en-tête `X-Lampion-Report-Signature`. Paramètre locale (`fr` ou `en`). 404 si le projet n'appartient pas à votre organisation, 503 si l'export PDF est indisponible sur le serveur.

Requête

curl -H "Authorization: Bearer $TOKEN" -o residency.pdf "https://api.lampion.cloud/v1/projects/{id}/residency.pdf?locale=fr"

Réponse

HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="lampion-residency-{id}-2026-10-14.pdf"
X-Lampion-Report-Digest: sha256:3f9a…
X-Lampion-Report-Signature: alg=Ed25519;key_id=9b1c4e0a7d2f6835;value=…

Conformité

De quoi répondre à un questionnaire sécurité ou à votre DPO sans nous écrire. Lisible par tout membre de l'organisation : rien n'y est secret. La liste des sous-traitants ultérieurs indique ceux qui voient effectivement vos données (`in_use`, selon les régions de vos projets). Le questionnaire est une base de connaissances : la sortie `md` est un document unique à donner à votre assistant IA, qui y trouve ses consignes — il doit respecter le statut de chaque réponse (`yes`, `no`, `partial`, `planned`) et ne jamais présenter un `planned` comme acquis. Le DPA (accord de sous-traitance, article 28 du RGPD) s'accepte en ligne au nom de la société : la lecture de son statut et le téléchargement de l'attestation sont ouverts à tout membre, mais l'acceptation est réservée à l'`owner` de l'organisation (un `admin` reçoit 403), car elle engage juridiquement la société. Elle n'est volontairement pas exposée au serveur MCP (Model Context Protocol) : un assistant IA ne doit pas pouvoir signer un contrat à votre place.

GET /v1/orgs/compliance/subprocessors

Lister les sous-traitants ultérieurs (article 28(2) du RGPD) : version du registre, préavis de modification (30 jours), régions utilisées par l'organisation, et pour chacun finalité, localisation, données traitées, transfert hors UE. Paramètre locale (`fr` ou `en`).

Requête

curl -H "Authorization: Bearer $TOKEN" "https://api.lampion.cloud/v1/orgs/compliance/subprocessors?locale=en"

Réponse

{"version":"2026-10-14","notice_period_days":30,"regions_in_use":["fr-par-1"],
 "subprocessors":[{"id":"scaleway","name":"Scaleway","entity":"Scaleway SAS","country_code":"FR",
   "scope":"global","outside_eu":false,"transfer_mechanism":null,"purpose":"Cloud hosting: ...",
   "location":"France (Paris region)","data":"Account data; ...","in_use":true},
  {"id":"resend","name":"Resend","entity":"Plus Five Five, Inc.","country_code":"US","outside_eu":true,
   "transfer_mechanism":"EU-U.S. Data Privacy Framework (self-certification) + Standard Contractual Clauses (...)",
   "source":"https://resend.com/legal/dpa","location":"USA","in_use":true, ...},
  {"id":"ovhcloud","name":"OVH Cloud","scope":"fr-gra-1","in_use":false, ...}, ...]}

GET /v1/orgs/compliance/questionnaire

Questionnaire sécurité de l'organisation, chaque réponse avec son statut et ses sources. Paramètres locale (`fr` ou `en`) et format : `json` (défaut), `md` (document unique avec consignes pour une IA) ou `csv` (colonnes id, category, status, question, answer, evidence).

Requête

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.lampion.cloud/v1/orgs/compliance/questionnaire?locale=en&format=md" -o lampion-security.md

Réponse

{"version":"...","locale":"en","org_id":"org_a1b2c3","usage":"...",
 "entries":[{"id":"dpa","category":"gdpr","category_label":"GDPR and subprocessing","status":"yes",
   "question":"...","answer":"...","evidence":["https://lampion.cloud/dpa"]}, ...]}

GET /v1/orgs/compliance/residency

Rapport de résidence de toute l'organisation : pays, régions, hébergeur, datacenter et certifications de l'hébergeur, couches de données, projets et branches par région, sous-traitants ultérieurs effectivement utilisés, `digest` (empreinte SHA-256 du contenu canonique, identique à celle du PDF) et `signature` (`alg` : `Ed25519`, `key_id` : identifiant de la clé, `value` : signature Ed25519 de la chaîne `digest`, encodée en base64). Paramètre locale (`fr` ou `en`).

Requête

curl -H "Authorization: Bearer $TOKEN" "https://api.lampion.cloud/v1/orgs/compliance/residency?locale=en"

Réponse

{"format_version":"3","scope":"org","locale":"en","generated_at":"2026-10-14T10:00:00+00:00",
 "org":{"id":"org_a1b2c3","name":"Acme"},"countries":["France"],"cross_region_replication":false,
 "lampion_certifications":[],"lampion_certifications_planned":"2027-Q1",
 "regions":[{"id":"fr-par-1","provider":"Scaleway","datacenter":"DC2",
   "provider_certifications":["ISO 27001","HDS"],
   "data_layers":[{"name":"compute","location":"DC2, Paris",
     "encryption_transit":"TLS 1.2 minimum enforced through the proxy",
     "encryption_rest":"Encryption at rest planned for Q1 2027"},
    {"name":"pageserver","location":"DC2, Paris",
     "encryption_transit":"Cluster-internal network (TLS not claimed)",
     "encryption_rest":"Encryption at rest planned for Q1 2027"}, ...],
   "projects":[{"id":"proj_x1","name":"shop","branches":["main","dev"]}]}],
 "subprocessors":[{"id":"scaleway","name":"Scaleway", ...}, ...],
 "digest":"sha256:3f9a…",
 "signature":{"alg":"Ed25519","key_id":"…","value":"…"}}

GET /v1/orgs/compliance/residency.pdf

Le même rapport en PDF horodaté, à transmettre tel quel à votre DPO ou à un acheteur. L'empreinte imprimée en pied de page est aussi renvoyée dans l'en-tête `X-Lampion-Report-Digest`, et sa signature Ed25519 dans l'en-tête `X-Lampion-Report-Signature`. Paramètre locale (`fr` ou `en`). 503 si l'export PDF est indisponible sur le serveur.

Requête

curl -H "Authorization: Bearer $TOKEN" -o residency.pdf "https://api.lampion.cloud/v1/orgs/compliance/residency.pdf?locale=fr"

Réponse

HTTP/1.1 200 OK
Content-Type: application/pdf
X-Lampion-Report-Digest: sha256:3f9a…
X-Lampion-Report-Signature: alg=Ed25519;key_id=9b1c4e0a7d2f6835;value=…

GET /v1/orgs/compliance/dpa

Statut du DPA de l'organisation : version en vigueur (`current_version`), liens vers le texte (`url.fr`, `url.en`), `accepted` et détail de l'acceptation de la version en vigueur (`acceptance`, sinon `null`), `needs_reacceptance` (une version antérieure a été acceptée mais pas celle en vigueur), version du registre des sous-traitants et `subprocessors_changed_since_acceptance`, et historique complet des acceptations (`history`). Ouvert à tout membre.

Requête

curl -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/orgs/compliance/dpa

Réponse

{"current_version":"2026-10-18",
 "url":{"fr":"https://lampion.cloud/dpa","en":"https://lampion.cloud/en/dpa"},
 "accepted":true,
 "acceptance":{"id":"dpa-4f2a9c1e7b30","dpa_version":"2026-10-18","company_name":"Acme SAS",
   "company_registration":"RCS Paris 123 456 789","signer_name":"Jane Doe","signer_title":"CEO",
   "accepted_by_email":"[email protected]","accepted_at":"2026-10-18T10:00:00+00:00"},
 "needs_reacceptance":false,"subprocessors_version":"2026-10-14",
 "subprocessors_changed_since_acceptance":false,
 "history":[{"id":"dpa-4f2a9c1e7b30","dpa_version":"2026-10-18", ...}]}

POST /v1/orgs/compliance/dpa/accept

Accepter la version en vigueur du DPA au nom de la société — réservé à l'`owner` de l'organisation (403 pour tout autre rôle, `admin` compris). Corps : `dpa_version` (la version lue, qui doit être celle en vigueur, sinon 409), `company_name`, `company_registration` (facultatif : SIREN, numéro d'immatriculation), `signer_name`, `signer_title`. 201 à la première acceptation, 200 si cette version est déjà acceptée (idempotent : l'acceptation existante est renvoyée telle quelle), 422 si un champ obligatoire est vide. Consigné dans le journal d'audit (action `dpa.accepted`).

Requête

curl -X POST https://api.lampion.cloud/v1/orgs/compliance/dpa/accept \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"dpa_version":"2026-10-18","company_name":"Acme SAS",
       "company_registration":"RCS Paris 123 456 789",
       "signer_name":"Jane Doe","signer_title":"CEO"}'

Réponse

HTTP/1.1 201 Created
{"id":"dpa-4f2a9c1e7b30","dpa_version":"2026-10-18","company_name":"Acme SAS",
 "company_registration":"RCS Paris 123 456 789","signer_name":"Jane Doe","signer_title":"CEO",
 "accepted_by_email":"[email protected]","accepted_at":"2026-10-18T10:00:00+00:00"}

GET /v1/orgs/compliance/dpa/certificate.pdf

Attestation d'acceptation du DPA en PDF : société, signataire, version, date. Porte une empreinte SHA-256 du contenu, aussi renvoyée dans l'en-tête `X-Lampion-Report-Digest`. Paramètres locale (`fr` ou `en`) et version (défaut : la version en vigueur). 404 si cette version n'a pas été acceptée par l'organisation, 503 si l'export PDF est indisponible sur le serveur. Ouvert à tout membre.

Requête

curl -H "Authorization: Bearer $TOKEN" -o dpa-certificate.pdf \
  "https://api.lampion.cloud/v1/orgs/compliance/dpa/certificate.pdf?locale=fr&version=2026-10-18"

Réponse

HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="lampion-dpa-org_a1b2c3-v2026-10-18.pdf"
X-Lampion-Report-Digest: sha256:8c41…
X-Lampion-Report-Signature: alg=Ed25519;key_id=9b1c4e0a7d2f6835;value=…

GET /v1/compliance/signing-keys

Clés publiques Ed25519 qui signent les rapports de résidence, identifiées par `key_id`. Endpoint public, sans authentification : un tiers (votre DPO, un acheteur) peut vérifier un rapport sans compte Lampion. Vérification : `signature.value`, décodée depuis le base64, est la signature Ed25519 de la chaîne `digest` par la clé désignée par `signature.key_id`.

Requête

# Public endpoint: no token
curl https://api.lampion.cloud/v1/compliance/signing-keys

Réponse

{"keys":[{"key_id":"9b1c4e0a7d2f6835","alg":"Ed25519",
  "public_key":"<base64, 32 raw bytes>",
  "pem":"-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----\n"}]}
// signature.value (base64) = Ed25519 signature of the UTF-8 "digest" string,
// made with the key whose id is signature.key_id.

Plans

Plans tarifaires.

GET /v1/plans

Lister les plans avec leurs limites et tarifs.

Requête

curl -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/plans

Réponse

[{"name":"free","max_projects":3,"pricing":{"cu_hour_eur":0,"storage_gb_month_eur":0}},
 {"name":"startup","max_projects":1000,"pricing":{"cu_hour_eur":0.10,"storage_gb_month_eur":0.40}},
 {"name":"souverain","pricing":{"cu_hour_eur":0.176,"storage_gb_month_eur":0.40}}]

Facturation

Ce que consomme votre organisation et ce qui a été facturé. Chaque relevé clos porte les quantités autant que les montants : de quoi répondre à « pourquoi ce montant » sans nous écrire. Rôle admin minimum — ce que dépense une entreprise n'est pas une information d'exploitation.

GET /v1/billing

Synthèse de la période en cours : abonnement, crédits (accordé, consommé, solde, dépassement) et factures.

Requête

curl -H "Authorization: Bearer $TOKEN" https://api.lampion.cloud/v1/billing

Réponse

{"period":"2026-09","subscription":{"plan":"startup","status":"active"},
 "credits":{"granted_eur":0,"consumed_eur":19.0,"balance_eur":-19.0,"overage_eur":19.0,"pct_used":null},
 "invoices":[],"stripe_mode":"live"}

GET /v1/billing/periods

Historique des relevés clos, du plus récent au plus ancien. Paramètres limit (défaut 24, maximum 120) et offset.

Requête

curl -H "Authorization: Bearer $TOKEN" "https://api.lampion.cloud/v1/billing/periods?limit=2"

Réponse

[{"period":"2026-08","status":"closed","plan_name":"startup",
   "compute_cu_hours":190.0,"storage_gb_month":12.4,"transfer_gb":3.1,
   "floor_eur":29.0,"usage_eur":23.96,"overage_eur":23.96,"total_eur":52.96,
   "closed_at":"2026-09-01T03:17:04+00:00","reported_at":"2026-09-01T03:17:05+00:00"}]