REST API — Overview

There is no domain per project. All traffic goes through a single origin — that of the gateway — and the project is identified by its UUID in the path. The gateway exposes two plans: the data plan (SDK and applications, :8080 locally) and the management plan (Studio and administration, :8090). The given plane surfaces are prefixed /v1/db, /v1/auth, /v1/storage, /v1/realtime, /v1/functions, /v1/notifications, /v1/ai.

# AURA_URL = origin of the gateway, data plan (e.g. http://localhost:8080)
# PROJECT_ID = Project UUID

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 — publishable. Serves as the API key for any request. Header apikey, X-API-Key, or parameter ?apikey= — the latter is only accepted on real-time streams (/ws, /sse, /chat/stream); elsewhere it is explicitly refused.
• service_role_key — secret, RLS bypass. Reserved for the backend.
• user_jwt — issued by POST /v1/auth/{project_id}/login after authentication. Header Authorization: Bearer.

# Anonymous customer (guest)
-H "apikey: <ANON_KEY>"

# Authenticated client (claims user)
-H "apikey: <ANON_KEY>"
-H "Authorization: Bearer <USER_JWT>"

# Backend (RLS bypass)
-H "apikey: <SERVICE_ROLE_KEY>"
-H "Authorization: Bearer <SERVICE_ROLE_KEY>"

• Content-Type: application/json — required on POST/PATCH/PUT (except upload storage, in multipart/form-data)
• Prefer: return=representation — returns the lines created/modified; return=minimal for a response without a body (204). Prefer: count=exact is read on aura-db mutations (headers Content-Range + Preference-Applied); To rely on a reading, use the ?count=exact parameter
• Range: 0-49 — only on a Postgres project served by PostgREST, which interprets it itself. The aura-db path (MongoDB project, or Postgres with PostgREST disabled) ignores this header: it only reads limit and offset. Prefer limit/offset, which work on both engines
• Idempotency-Key — is NOT read on Database (POST /v1/db/…) writes: two identical POSTs create two lines. It is only honored by POST /v1/notifications/{project_id}/send (and /send/batch), and by the creation of the management plan API key (POST /v1/db/{project_id}/api-keys, 24-hour window)

error is always an object, never a string. Two variants, depending on the issuer - the fields code and message are common to both, and it is on code (never on message, free text) that we discriminate.

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

{
  "error": {
    "code": "COLUMN_NOT_FOUND",    // never the raw PGRST code
    "message": "Column unknown_col not found in table sensors",
    "details": ""
  }
}

CodeNameDescription

400Invalid Bad RequestPayload or malformed query. error.code = BAD_REQUEST.

401Unauthorizedapikey missing/revoked or invalid JWT. error.code = UNAUTHORIZED (or REFRESH_TOKEN_REJECTED on /refresh).

403ForbiddenRLS or authorization service refuses the operation. error.code = FORBIDDEN, QUOTA_EXCEEDED, or INSUFFICIENT_PRIVILEGE (PostgREST path).

404Not FoundResource nonexistent or invisible by RLS. error.code = NOT_FOUND, RECORD_NOT_FOUND or TABLE_NOT_FOUND.

406Not Acceptable Single line expected, multiple returned. error.code = NOT_SINGULAR.

409ConflictSingle constraint violation or FK. error.code = CONFLICT, DUPLICATE_KEY, FOREIGN_KEY_VIOLATION. Use on_conflict for upsert.

413Payload Too LargeRequest > MAX_BODY_SIZE (default 50 MB on the gateway side). Use multipart storage upload.

429Too Many RequestsRate limit reached. X-RateLimit-Limit / X-RateLimit-Remaining headers; Retry-After on gateway refusals.

500Internal ErrorServer error. error.request_id to provide to support.

503Service UnavailableCircuit breaker open, instance missing, or hibernated project (Retry-After: 5 in the latter case). Recovery breaker after 30 s.

504Gateway TimeoutTimeout upstream. error.code = TIMEOUT.

• Gateway, all routes: per IP, 100 req/s with a burst of 1000 (adjustable via RATE_LIMIT_RPS / RATE_LIMIT_BURST). There is no separate tier per role.
• Auth sensitive (login, register, forgot-password, magic-link, email-otp/send, sms/send, refresh, mfa/verify-login): 5 req/min per IP, burst 3. In addition, a quota per project: 30 connection attempts/hour per IP by default, adjustable in the project settings.
• Raw SQL (/raw): 30 req/min, burst 10. IA: 10 req/min, burst 5.

Each endpoint has its dedicated page with parameters, response codes, examples in 5 languages and live rail code.

DatabaseAuthStorageRealtimeFunctions