Aller au contenu
Logo Aurabase
aurabase

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/.

Référence7 min de lectureNiveau référenceRévisé le 15 avr. 2026

Cette page a été traduite automatiquement. La version anglaise fait foi.

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.

examplesbash
# 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
Informations

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.

Attention

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ête apikey, X-API-Key ou 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 par POST /v1/auth/login après authentification. En-tête Authorization: Bearer.
headers.shbash
# 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, dans multipart/form-data)
  • Prefer: return=representation — renvoie les lignes créées ou 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 vous appuyer sur une lecture de, 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 la base de données (POST /v1/db/…) écrit : deux POST identiques créent deux lignes. Elle n'est honorée que par POST /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#

pagination.shbash
# 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
Astuce

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.

Attention

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.

erreur émise par un service Aurabasejson
{
  "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"
  }
}
Erreur PostgREST traduite par la passerellejson
{
  "error": {
    "code": "COLUMN_NOT_FOUND",    // jamais le code PGRST brut
    "message": "Column unknown_col not found in table sensors",
    "details": ""
  }
}
Attention

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.

CoderNomDescriptif
400Mauvaise demandeCharge utile ou requête mal formée. error.code est BAD_REQUEST.
401Non autoriséapikey manquant ou révoqué, ou JWT invalide. error.code est UNAUTHORIZED ou REFRESH_TOKEN_REJECTED sur /refresh.
403InterditRLS ou le service d'autorisation refuse l'opération. error.code est FORBIDDEN, QUOTA_EXCEEDED ou INSUFFICIENT_PRIVILEGE (chemin PostgREST).
404IntrouvableLa ressource n'existe pas ou RLS la cache. error.code est NOT_FOUND, RECORD_NOT_FOUND ou TABLE_NOT_FOUND.
406Pas acceptableUne rangée attendue, plusieurs sont revenues. error.code est NOT_SINGULAR.
409ConflitViolation de clé unique ou étrangère. error.code est CONFLICT, DUPLICATE_KEY ou FOREIGN_KEY_VIOLATION. Utilisez on_conflict pour une upsert.
413Charge utile trop importanteRequête supérieure à MAX_BODY_SIZE (50 Mo par défaut sur la passerelle). Utilisez un téléchargement de stockage en plusieurs parties.
429Too Many RequestsLimite 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.
500Erreur de serveur interneErreur de serveur. Donnez error.request_id au support.
503Service UnavailableSERVER_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.
504Gateway TimeoutDé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 429 nomme la portée atteinte, pour savoir s'il faut ralentir ou changer de plan.
  • Passerelle , toutes les routes: par IP, 100 req/s avec un burst de 1000 par défaut (réglable via RATE_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.
Attention

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:

aurabase_rest.pypython
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:

aurabase_rest.dartdart
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'));
}

Pour aller plus loin#