API REST — Vue d'ensemble

Il n'y a pas de domaine par projet. Tout le trafic passe par une seule origine — celle du gateway — et le projet est identifié par son UUID dans le chemin. Le gateway expose deux plans : le plan données (SDK et applications, :8080 en local) et le plan management (Studio et administration, :8090). Les surfaces du plan données sont préfixées /v1/db, /v1/auth, /v1/storage, /v1/realtime, /v1/functions, /v1/notifications, /v1/ai.

# AURA_URL = origine du gateway, plan données (ex. http://localhost:8080)
# PROJECT_ID = UUID du projet
GET   $AURA_URL/v1/db/$PROJECT_ID/sensors
POST  $AURA_URL/v1/auth/$PROJECT_ID/login
GET   $AURA_URL/v1/storage/$PROJECT_ID/avatars/u_xx/file.png
POST  $AURA_URL/v1/functions/$PROJECT_ID/ocr/invoke

• anon_key — publiable. Sert d'API key pour toute requête. Header apikey, X-API-Key, ou paramètre ?apikey= — ce dernier n'est accepté que sur les flux temps réel (/ws, /sse, /chat/stream) ; ailleurs il est refusé explicitement.
• service_role_key — secrète, bypass RLS. Réservée au backend.
• user_jwt — émis par POST /v1/auth/{project_id}/login après authentification. Header Authorization: Bearer.

# Client anonyme (guest)
-H "apikey: <ANON_KEY>"
# Client authentifié (claims user)
-H "apikey: <ANON_KEY>"
-H "Authorization: Bearer <USER_JWT>"
# Backend (bypass RLS)
-H "apikey: <SERVICE_ROLE_KEY>"
-H "Authorization: Bearer <SERVICE_ROLE_KEY>"

• Content-Type: application/json — requis sur POST/PATCH/PUT (sauf upload storage, en multipart/form-data)
• Prefer: return=representation — retourne les lignes créées/modifiées ; return=minimal pour une réponse sans corps (204). Prefer: count=exact est lu sur les mutations aura-db (en-têtes Content-Range + Preference-Applied) ; pour compter sur une lecture, utilisez le paramètre ?count=exact
• Range: 0-49 — uniquement sur un projet Postgres servi par PostgREST, qui l'interprète lui-même. Le chemin aura-db (projet MongoDB, ou Postgres avec PostgREST désactivé) ignore cet en-tête : il ne lit que limit et offset. Préférez limit/offset, qui fonctionnent sur les deux moteurs
• Idempotency-Key — n'est PAS lu sur les écritures Database (POST /v1/db/…) : deux POST identiques créent deux lignes. Il n'est honoré que par POST /v1/notifications/{project_id}/send (et /send/batch), et par la création de clé API du plan management (POST /v1/db/{project_id}/api-keys, fenêtre de 24 h)

error est toujours un objet, jamais une chaîne. Deux variantes, selon l'émetteur — les champs code et message sont communs aux deux, et c'est sur code (jamais sur message, texte libre) que l'on discrimine.

{
  "error": {
    "type": "auth_unauthorized",      // type machine, préfixé par domaine
    "code": "UNAUTHORIZED",         // code stable
    "message": "Non autorisé : Clé API invalide ou révoquée",
    "request_id": "dc20e246-d8e0-412c-b9d7-ce675af6edd5"
  }
}

{
  "error": {
    "code": "COLUMN_NOT_FOUND",    // jamais le code PGRST brut
    "message": "Column unknown_col not found in table sensors",
    "details": ""
  }
}

• Gateway, toutes routes : par IP, 100 req/s avec un burst de 1000 (réglable via RATE_LIMIT_RPS / RATE_LIMIT_BURST). Il n'y a pas de palier distinct par rôle.
• Auth sensible (login, register, forgot-password, magic-link, email-otp/send, sms/send, refresh, mfa/verify-login) : 5 req/min par IP, burst 3. En plus, un quota par projet : 30 tentatives de connexion/heure par IP par défaut, réglable dans les paramètres du projet.
• SQL brut (/raw) : 30 req/min, burst 10. IA : 10 req/min, burst 5.

Chaque endpoint a sa page dédiée avec paramètres, response codes, exemples dans 5 langages et code rail live.