API REST — Présentation
Surface HTTP brute Aurabase. Compatible avec toutes les langues. URL de base, authentification, format de réponse, codes d'erreur, puis détails par point de terminaison dans /docs/api/.
Une origine, le projet en route#
L'URL est le projet. Chaque projet est servi sur son propre sous-domaine, https://<slug>.<apex> (localement http://<slug>.localhost:8080), et la passerelle résout le projet depuis l'hôte : aucun identifiant de projet n'est écrit dans les chemins. Studio > Paramètres > Connexion affiche cette URL et NEXT_PUBLIC_AURABASE_URL la contient. La passerelle expose deux plans : le plan de données (SDK et applications, :8080 localement) et le plan de gestion (Studio et administration, :8090). Les surfaces du plan de données portent le préfixe /v1/db, /v1/auth, /v1/storage, /v1/realtime, /v1/functions, /v1/notifications, /v1/ai.
# NEXT_PUBLIC_AURABASE_URL = URL du projet (par exemple http://my-app-x1y2z3.localhost:8080)
GET $NEXT_PUBLIC_AURABASE_URL/v1/db/sensors
POST $NEXT_PUBLIC_AURABASE_URL/v1/auth/login
GET $NEXT_PUBLIC_AURABASE_URL/v1/storage/avatars/u_xx/file.png
POST $NEXT_PUBLIC_AURABASE_URL/v1/functions/ocr/invoke
Les formulaires qui portent l'UUID du projet dans le chemin (/v1/db/{project_id}/sensors, /v1/auth/{project_id}/login, comme dans les pages de référence du point de terminaison) sont toujours acceptés sur l'URL du projet, ainsi que sur l'origine de la passerelle nue. Ils sont conservés par compatibilité : préférez les formulaires ci-dessus, qui ne dépendent pas de l'identifiant.
Les routes de streaming /v1/realtime/ws et /v1/realtime/sse sont diffusées telles quelles sur l'hôte du projet. Une URL qui n'identifie pas de projet (par exemple l'origine de la passerelle nue sans identifiant de projet) est rejetée en tant que 400.
Deux clés, une JWT#
anon_key— publiable. Sert de clé API pour toute demande. En-têteapikey,X-API-Keyou paramètre?apikey=— ce dernier n'est accepté que sur les flux en temps réel (/ws,/sse,/chat/stream) ; ailleurs, il est explicitement refusé.service_role_key— secret, contournement RLS. Réservé au backend.user_jwt— émis parPOST /v1/auth/loginaprès authentification. En-têteAuthorization: Bearer.
# Client anonyme (invité)
-H "apikey: <NEXT_PUBLIC_AURABASE_ANON_KEY>"
# Client authentifié (utilisateur revendique)
-H "apikey: <NEXT_PUBLIC_AURABASE_ANON_KEY>"
-H "Authorization: Bearer <USER_JWT>"
# Back-end (contournement RLS)
-H "apikey: <AURABASE_SERVICE_ROLE_KEY>"
-H "Authorization: Bearer <AURABASE_SERVICE_ROLE_KEY>"
Normes appliquées#
Content-Type: application/json— requis sur POST/PATCH/PUT (sauf stockage de téléchargement, dansmultipart/form-data)Prefer: return=representation— renvoie les lignes créées ou modifiées ;return=minimalpour une réponse sans corps (204).Prefer: count=exactest lu sur les mutations aura-db (en-têtesContent-Range+Preference-Applied) ; Pour vous appuyer sur une lecture de, utilisez le paramètre?count=exactRange: 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 quelimitetoffset. Préférezlimit/offset, qui fonctionnent sur les deux moteursIdempotency-Key— n'est PAS lu sur la base de données (POST /v1/db/…) écrit : deux POST identiques créent deux lignes. Elle n'est honorée que parPOST /v1/notifications/{project_id}/send(et/send/batch), et par la création de la clé API du plan de gestion (POST /v1/db/{project_id}/api-keys, fenêtre de 24 heures)
Limite + décalage#
# Uniquement sous forme portable – fonctionne sur les deux moteurs
GET $NEXT_PUBLIC_AURABASE_URL/v1/db/sensors?order=id.asc&limit=50&offset=100
# Keyset « à la main » : filtrer sur la dernière clé lue
GET $NEXT_PUBLIC_AURABASE_URL/v1/db/sensors?id=gt.{last_id}&order=id.asc&limit=50
# ?cursor= : aura-db UNIQUEMENT (MongoDB, ou Postgres sans PostgREST).
# Le PostgREST la demande est refusée en 400.
GET $NEXT_PUBLIC_AURABASE_URL/v1/db/sensors?cursor={meta.next_cursor}&limit=50
Sans limit, une lecture renvoie au maximum 1 000 lignes — il s'agit à la fois de la valeur par défaut et du plafond strict. Lorsqu'une requête comporte en fait plus de lignes correspondantes au-delà de la tranche renvoyée, meta.has_more est true (et false lorsqu'aucune ligne supplémentaire n'existe ou que la tranche finale a été atteinte) ; demandez count=exact pour obtenir également meta.total.
Le total n'est pas lu au même endroit selon les moteurs : sur le chemin aura-db, la réponse porte l'entête Content-Range: items 100-149/1247 (le total vaut * si aucun comptage n'a été demandé) ; sur le chemin PostgREST, la passerelle ne relaie pas cet entête et place le total dans meta.total de l'enveloppe JSON. Le comptage n'est jamais fait par défaut : demandez-le avec le paramètre ?count=exact (forme portable, traduit en Prefer par la passerelle sur le chemin PostgREST), ?count=planned, ou ?count=estimated.
La description OpenAPI de votre projet est servie à GET /v1/db/{project_id}/openapi.json (avec votre apikey) ; elle est générée à partir du schéma réel, donc une table que vous venez de créer y figure.
Format uniforme#
error est toujours un objet, jamais une chaîne. Deux variantes, selon les émetteurs - 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 de machine, préfixé par domaine
"code": "UNAUTHORIZED", // code stable
"message": "Unauthorized: Invalid or revoked API key",
"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": ""
}
}
Les codes PostgREST/PostgreSQL (PGRST116, 23505…) ne sont jamais renvoyés tels quels par l'API REST : la passerelle les traduit en codes Aurabase (RECORD_NOT_FOUND, NOT_SINGULAR, COLUMN_NOT_FOUND, NO_RELATIONSHIP, SCHEMA_NOT_FOUND, DUPLICATE_KEY, FOREIGN_KEY_VIOLATION, CHECK_VIOLATION, INVALID_INPUT, NUMERIC_OUT_OF_RANGE, INVALID_BODY, TABLE_NOT_FOUND, FUNCTION_NOT_FOUND, INSUFFICIENT_PRIVILEGE, STATEMENT_TIMEOUT, DB_POOL_TIMEOUT, sinon POSTGREST_ERROR). Cette variante ne porte pas de type ; les erreurs que l'appelant peut corriger ajoutent un hint (une colonne ou une fonction manquante suggère le nom le plus proche, un refus RLS donne le create policy à ajouter). Le SDK JavaScript conserve volontairement PGRST116 pour .single() / .maybeSingle(), par compatibilité avec supabase-js : en HTTP brut, la même situation est NOT_SINGULAR.
| Coder | Nom | Descriptif |
|---|---|---|
400 | Mauvaise demande | Charge utile ou requête mal formée. error.code est BAD_REQUEST. |
401 | Non autorisé | apikey manquant ou révoqué, ou JWT invalide. error.code est UNAUTHORIZED ou REFRESH_TOKEN_REJECTED sur /refresh. |
403 | Interdit | RLS ou le service d'autorisation refuse l'opération. error.code est FORBIDDEN, QUOTA_EXCEEDED ou INSUFFICIENT_PRIVILEGE (chemin PostgREST). |
404 | Introuvable | La ressource n'existe pas ou RLS la cache. error.code est NOT_FOUND, RECORD_NOT_FOUND ou TABLE_NOT_FOUND. |
406 | Pas acceptable | Une rangée attendue, plusieurs sont revenues. error.code est NOT_SINGULAR. |
409 | Conflit | Violation de clé unique ou étrangère. error.code est CONFLICT, DUPLICATE_KEY ou FOREIGN_KEY_VIOLATION. Utilisez on_conflict pour une upsert. |
413 | Charge utile trop importante | Requête supérieure à MAX_BODY_SIZE (50 Mo par défaut sur la passerelle). Utilisez un téléchargement de stockage en plusieurs parties. |
429 | Too Many Requests | Limite de débit atteinte. error.code vaut RATE_LIMITED ; message nomme la limite atteinte (IP, projet ou clé d'API) et hint indique quand réessayer. Les en-têtes X-RateLimit-Limit et X-RateLimit-Remaining sont posés, et Retry-After sur les refus de la passerelle. |
500 | Erreur de serveur interne | Erreur de serveur. Donnez error.request_id au support. |
503 | Service Unavailable | SERVER_BUSY quand la passerelle délestage la charge (trop de requêtes en vol, Retry-After: 1), DB_POOL_TIMEOUT quand le pool de connexions du projet reste saturé, disjoncteur ouvert, instance absente ou projet hiberné (Retry-After: 5 dans ce cas). Le disjoncteur réessaie après 30 secondes. |
504 | Gateway Timeout | Délai d'attente dépassé en amont. error.code vaut TIMEOUT, ou STATEMENT_TIMEOUT quand une instruction SQL a dépassé le délai de 10 secondes du projet. |
Par IP à la passerelle, plus limites par route#
- Par projet et par clé d'API : la limite du plan du projet (Studio › Settings › Usage). Un
429nomme la portée atteinte, pour savoir s'il faut ralentir ou changer de plan. - Passerelle , toutes les routes: par IP,
100req/s avec un burst de1000par défaut (réglable viaRATE_LIMIT_RPS/RATE_LIMIT_BURST). Il n’y a pas de niveau 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. De plus, un quota par projet : 30 connexions tentatives/heure par IP par défaut, réglable dans les paramètres du projet. En développement (AURA_ENV=development, la pile locale), la limite du routeur est assouplie (rafale 100) afin que vous puissiez itérer ; les quotas de projet affichés dans Studio > Authentification > Configuration > Limitation de débit s'appliquent toujours. - SQL brut (
/raw) : 30 req/min, rafale 10. IA: 10 req/min, rafale 5.
Débordement → 429 Too Many Requests avec les entêtes X-RateLimit-Limit et X-RateLimit-Remaining (présents sur toute réponse de la passerelle), plus X-RateLimit-Reset et Retry-After sur le refus.
Arbre complet par service#
Chaque point de terminaison a sa page dédiée avec des paramètres, des codes de réponse, des exemples en 5 langues et du code ferroviaire en direct.
Base de donnéesAuthStockageTemps réelFonctions
Pas encore de SDK pour votre langue#
Il n'y a pas encore de package Python ou Dart publié (le Studio le dit aussi). L'API REST ci-dessus est complète, donc un client représente quelques lignes. La version Python utilise uniquement la bibliothèque standard ; il lit les mêmes variables que les autres exemples et transforme une erreur API en une exception qui porte le code stable et le request_id:
import json, os, urllib.error, urllib.request
URL = os.environ["NEXT_PUBLIC_AURABASE_URL"]
KEY = os.environ["NEXT_PUBLIC_AURABASE_ANON_KEY"] # ou AURABASE_SERVICE_ROLE_KEY sur un serveur
def get(path):
request = urllib.request.Request(URL + path, headers={"apikey": KEY})
try:
with urllib.request.urlopen(request, timeout=15) as response:
return json.load(response)
except urllib.error.HTTPError as e:
error = json.load(e)["error"]
raise RuntimeError(f'{error["code"]}: {error["message"]} (request_id {error.get("request_id")})')
print(get("/v1/db/todos?limit=2"))
La version Dart (Flutter ou serveur) n'a pas non plus besoin de package ; exécutez-le avec dart run aurabase_rest.dart:
import 'dart:convert';
import 'dart:io';
final url = Platform.environment['NEXT_PUBLIC_AURABASE_URL']!;
final key = Platform.environment['NEXT_PUBLIC_AURABASE_ANON_KEY']!; // or AURABASE_SERVICE_ROLE_KEY on a server
Future<dynamic> get(String path) async {
final client = HttpClient();
try {
final request = await client.getUrl(Uri.parse(url + path));
request.headers.set('apikey', key);
final response = await request.close();
final body = jsonDecode(await response.transform(utf8.decoder).join());
if (response.statusCode >= 400) {
final error = body['error'];
throw Exception('${error['code']}: ${error['message']} (request_id ${error['request_id']})');
}
return body;
} finally {
client.close();
}
}
Future<void> main() async {
print(await get('/v1/db/todos?limit=2'));
}