Référence API

Sovrium expose une API REST complète pour gérer les tables, les enregistrements, les vues, les journaux d'activité, l'analytique, l'authentification et la gestion de schéma par les administrateurs. Tous les endpoints acceptent et retournent du JSON, appliquent le RBAC avec des permissions au niveau des champs et émettent une enveloppe d'erreur canonique unique.

URL de base

Tous les endpoints sont relatifs à l'URL de base de votre instance Sovrium.

http://localhost:3000/api

Authentification et contrôle d'accès

L'API utilise une authentification basée sur les sessions (Better Auth). Les requêtes qui touchent à des ressources protégées doivent porter un cookie de session valide ou un en-tête Authorization: Bearer <token>. L'accès est régi par le RBAC (admin, member, viewer) avec des permissions au niveau des champs superposées par-dessus.

Conformément à la politique anti-énumération, une requête authentifiée qui ne dispose pas d'un accès en lecture à une ressource retourne 404 (et non 403), de sorte que l'appelant ne peut pas distinguer « introuvable » de « pas d'accès ». Un véritable 403 est réservé aux surfaces où la ressource est connue pour exister mais où l'action est refusée (par exemple, un non-administrateur appelant GET /api/admin/schema/versions).

Contrat de réponse d'erreur

Toutes les réponses 4xx/5xx utilisent une enveloppe JSON canonique unique, de sorte qu'un seul décodeur couvre toutes les erreurs.

Enveloppe 4xx/5xx générique :

{
  "success": false,
  "message": "Authentication required",
  "code": "UNAUTHORIZED"
}

Le code est tiré d'une énumération stable : UNAUTHORIZED, FORBIDDEN, NOT_FOUND, VALIDATION_ERROR, CONFLICT, RATE_LIMITED, INTERNAL_ERROR, SERVICE_UNAVAILABLE. Les champs optionnels error (identifiant de type hérité) et details peuvent également être présents.

Enveloppe de validation 400 — lorsque l'échec se situe au niveau des champs, un tableau errors[] nomme chaque champ fautif :

{
  "success": false,
  "message": "One or more fields failed validation",
  "code": "VALIDATION_ERROR",
  "errors": [{ "field": "id", "message": "Cannot write to readonly field 'id'" }]
}

Statut	code	Signification
400	VALIDATION_ERROR	Échec de validation au niveau des champs (porte errors[])
401	UNAUTHORIZED	Session absente / expirée
403	FORBIDDEN	Authentifié, action refusée (ressource connue)
404	NOT_FOUND	Introuvable, ou refus d'accès anti-énumération
413	PAYLOAD_TOO_LARGE	La charge utile du lot dépasse la limite
429	RATE_LIMITED	Limite de débit dépassée
500	INTERNAL_ERROR	Erreur serveur inattendue (détails masqués)

Santé

Endpoint de vérification de l'état du serveur (non authentifié).

Méthode	Chemin	Description
GET	/api/health	Vérifier l'état du serveur

Tables

Lecture des définitions de tables, y compris les schémas de champs et les règles de permissions.

Méthode	Chemin	Description
GET	/api/tables	Lister toutes les tables
GET	/api/tables/{tableId}	Obtenir une table par ID
GET	/api/tables/{tableId}/permissions	Obtenir les permissions d'une table

Enregistrements

CRUD complet, opérations par lot, cycle de vie de suppression douce, historique des révisions et commentaires d'enregistrements. Consultez Aperçu des enregistrements pour le modèle de données.

CRUD

Méthode	Chemin	Description
GET	/api/tables/{tableId}/records	Lister les enregistrements
POST	/api/tables/{tableId}/records	Créer un enregistrement
GET	/api/tables/{tableId}/records/{recordId}	Obtenir un enregistrement par ID
PATCH	/api/tables/{tableId}/records/{recordId}	Modifier un enregistrement
DELETE	/api/tables/{tableId}/records/{recordId}	Supprimer un enregistrement (soft)

Opérations par lot

Méthode	Chemin	Description
POST	/api/tables/{tableId}/records/batch	Créer plusieurs enregistrements
PATCH	/api/tables/{tableId}/records/batch	Modifier plusieurs enregistrements
DELETE	/api/tables/{tableId}/records/batch	Supprimer plusieurs enregistrements (soft)
POST	/api/tables/{tableId}/records/upsert	Créer ou modifier un enregistrement

Corbeille et historique

Méthode	Chemin	Description
GET	/api/tables/{tableId}/trash	Lister les enregistrements supprimés
POST	/api/tables/{tableId}/records/{recordId}/restore	Restaurer un enregistrement supprimé
POST	/api/tables/{tableId}/records/batch/restore	Restaurer plusieurs enregistrements
GET	/api/tables/{tableId}/records/{recordId}/history	Obtenir l'historique des révisions

Commentaires

Méthode	Chemin	Description
GET	/api/tables/{tableId}/records/{recordId}/comments	Lister les commentaires d'un enregistrement
POST	/api/tables/{tableId}/records/{recordId}/comments	Ajouter un commentaire
GET	.../{recordId}/comments/{commentId}	Obtenir un commentaire par ID
PATCH	.../{recordId}/comments/{commentId}	Modifier un commentaire
DELETE	.../{recordId}/comments/{commentId}	Supprimer un commentaire

Vues

Vues préconfigurées qui filtrent, trient et regroupent les enregistrements d'une table.

Méthode	Chemin	Description
GET	/api/tables/{tableId}/views	Lister les vues d'une table
GET	/api/tables/{tableId}/views/{viewId}	Obtenir une vue par ID
GET	/api/tables/{tableId}/views/{viewId}/records	Obtenir les enregistrements via une vue

Activité

Journal d'audit des modifications de données sur toutes les tables.

Méthode	Chemin	Description
GET	/api/activity	Lister les entrées d'activité
GET	/api/activity/{activityId}	Obtenir le détail d'une activité

Analytique

Analytique d'utilisation respectueuse de la vie privée, sans cookies.

Méthode	Chemin	Description
POST	/api/analytics/collect	Enregistrer un événement de page vue
GET	/api/analytics/overview	Obtenir l'aperçu analytique
GET	/api/analytics/pages	Obtenir les pages les plus vues
GET	/api/analytics/referrers	Obtenir les principaux référents
GET	/api/analytics/devices	Obtenir la répartition par appareil
GET	/api/analytics/campaigns	Obtenir les statistiques de campagnes

Admin : gestion de schéma

Édition de schéma en direct (brouillon → validation → publication) pour les utilisateurs administrateurs. Enregistrée uniquement lorsque app.auth est configuré et que SCHEMA_EDIT_API_ENABLED=true ; sinon, chaque chemin /api/admin/schema/* retourne 404. Toutes les routes nécessitent le rôle admin.

Méthode	Chemin	Description
GET	/api/admin/schema/status	Statut de dérive / brouillon
GET	/api/admin/schema/diff	Aperçu de la dérive en direct vs fichier
GET	/api/admin/schema/export	Sérialiser la version en direct en YAML
GET	/api/admin/schema/draft	Obtenir le brouillon de travail
PUT	/api/admin/schema/draft	Remplacer le brouillon de travail
POST	/api/admin/schema/draft/discard	Abandonner le brouillon
POST	/api/admin/schema/draft/validate	Valider le brouillon
POST	/api/admin/schema/draft/publish	Publier le brouillon (nouvelle version)
POST	/api/admin/schema/draft/rebase	Rebaser un brouillon obsolète sur l'actif
GET	/api/admin/schema/versions	Lister les versions publiées
GET	/api/admin/schema/versions/{version}	Obtenir une version
POST	.../versions/{version}/restore	Restaurer une version

Les mutations de brouillon par ressource (/api/admin/schema/draft/tables, /pages, /auth/strategies, /forms, /automations, /connections, /preview) et l'opération /api/admin/schema/prune complètent la surface. Chaque endpoint REST est reflété en tant qu'outil MCP ({appName}_schema_*) pour les agents IA.

Endpoints d'authentification

L'authentification est gérée par Better Auth et montée sur /api/auth/*. Elle inclut la connexion et l'inscription par email/mot de passe, les fournisseurs OAuth sociaux, la gestion des sessions, la réinitialisation de mot de passe, la vérification d'email, l'authentification à deux facteurs, les liens magiques, l'OTP par email, les organisations et la gestion des utilisateurs par les administrateurs. Consultez la documentation de configuration de l'authentification pour la mise en place, ou explorez chaque endpoint d'authentification dans la documentation interactive de l'API.

Les administrateurs peuvent parcourir la surface complète lisible par les machines sur /api/scalar et récupérer les documents OpenAPI bruts — consultez OpenAPI.

Fonctionnalités transversales

Capacités qui s'appliquent à tous les endpoints de l'API.

• Pagination — les endpoints de liste paginent leurs résultats
• Suppressions douces — DELETE met à la corbeille (récupérable) ; une purge distincte supprime définitivement
• RBAC — les rôles admin / member / viewer protègent chaque route protégée
• Permissions au niveau des champs — contrôle granulaire en lecture/écriture par champ et par rôle
• Limitation de débit — les endpoints d'authentification et d'administration sont limités en débit
• Enveloppe d'erreur canonique — chaque réponse 4xx/5xx partage une forme unique (voir ci-dessus)