API publique — vue d'ensemble
Auralith expose une API REST sous /api/v1. Toutes les routes mountees ici
ont une OpenAPI auto-generee, accessible via /docs (Swagger UI) ou
/openapi.json.
Namespaces
| Namespace | Description | Exemple |
|---|---|---|
/projects | CRUD projets, membres, permissions | GET /api/v1/projects |
/connections | CRUD connexions DB, test, introspection | POST /api/v1/connections |
/patches | Mass Patch : create, dry-run, execute, rollback | POST /api/v1/patches/{id}/execute |
/seeds | Seed scenarios + execution | POST /api/v1/seed/scenarios/{id}/run |
/anonymize | Configs et runs d'anonymisation | POST /api/v1/anonymize/configs/{id}/run |
/bridge | Copie source -> cible | POST /api/v1/projects/{pid}/bridge/run |
/migrations | DDL compare + apply | POST /api/v1/migrations/{id}/apply |
/approvals | Approval requests + decisions | PATCH /api/v1/approvals/{id} |
/access-requests | JIT access | POST /api/v1/projects/{pid}/access-requests |
/drift | Snapshots + diff reports | POST /api/v1/connections/{cid}/drift/check |
/webhooks | Outbound webhooks config | POST /api/v1/projects/{pid}/webhooks |
/api-keys | CRUD API keys (scope projet) | POST /api/v1/api-keys |
/auth | Login, logout, OAuth, 2FA, profile | POST /api/v1/auth/login |
/billing | Plans, usage, Stripe events | GET /api/v1/billing/usage |
/audit-export | Configuration sinks externes | POST /api/v1/admin/audit-export/sinks |
Liste exhaustive sur /docs Swagger UI.
Conventions
- Versioning :
/api/v1. Une rupture majeure =/api/v2. Les changements retro-compatibles sont ajoutes dans v1. - Format : JSON request / JSON response. UTF-8.
- Erreurs : enveloppe standard FastAPI
{"detail": "..."}ou{"detail": [{"loc": [...], "msg": "...", "type": "..."}]}. - IDs : UUID v4 partout.
- Dates : ISO 8601 UTC (
2026-04-24T10:00:00Z). - Pagination :
?page=1&page_size=50. Reponse contient{"items": [...], "total": N, "page": 1, "page_size": 50}.
Authentification
Deux modes :
- Session cookie : pour l'app web. Login via
/api/v1/auth/login, recoit cookie httpOnly + CSRF token. - API key bearer : pour scripts / CI. Header
Authorization: Bearer <prefix>_<secret>.
Voir Authentication pour le detail.
Exemple curl rapide
# Login
curl -X POST https://app.auralith.io/api/v1/auth/login \
-H "Content-Type: application/json" \
-d '{"email":"alice@example.com","password":"..."}' \
-c cookies.txt
# Lister projets (avec session)
curl https://app.auralith.io/api/v1/projects -b cookies.txt
# Avec API key
curl https://app.auralith.io/api/v1/projects \
-H "Authorization: Bearer ak_abc123_def456..."
OpenAPI / Swagger
- Swagger UI :
https://app.auralith.io/docs - OpenAPI JSON :
https://app.auralith.io/openapi.json
Generation client SDK :
openapi-generator-cli generate -i https://app.auralith.io/openapi.json \
-g typescript-fetch -o ./auralith-sdk