Saltar al contenido
Logotipo de Aurabase
aurabase

API REST: descripción general

Aurabase superficie HTTP sin formato. Compatible con todos los idiomas. URL base, autenticación, formato de respuesta, códigos de error y luego detalles por punto final en /docs/api/.

Referencia7 min leerNivel referenciaRevisado el 15 abr 2026

Esta página fue traducida automáticamente. La versión en inglés es autorizada.

Un origen, el proyecto en camino#

La URL es el proyecto. Cada proyecto se sirve en su propio subdominio, https://<slug>.<apex> (localmente http://<slug>.localhost:8080), y la puerta de enlace resuelve el proyecto desde el host: no se escribe ningún identificador de proyecto en las rutas. Studio › Configuración › Conexión muestra esta URL y NEXT_PUBLIC_AURABASE_URL la contiene. La puerta de enlace expone dos planes: el plan de datos (SDK y aplicaciones, :8080 localmente) y el plan de gestión (Estudio y administración, :8090). Las superficies del plan de datos tienen el prefijo /v1/db, /v1/auth, /v1/storage, /v1/realtime, /v1/functions, /v1/notifications, /v1/ai.

examplesbash
# NEXT_PUBLIC_AURABASE_URL = URL del proyecto (por ejemplo, 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
Información

Los formularios que llevan el UUID del proyecto en la ruta (/v1/db/{project_id}/sensors, /v1/auth/{project_id}/login, como en las páginas de referencia del punto final) aún se aceptan en la URL del proyecto y también en el origen de la puerta de enlace simple. Se mantienen por compatibilidad: prefiera las formas anteriores, que no dependen del identificador.

Atención

Las rutas de transmisión /v1/realtime/ws y /v1/realtime/sse se sirven tal como están en el host del proyecto. Una URL que no identifica un proyecto (por ejemplo, el origen de la puerta de enlace simple sin un identificador de proyecto) se rechaza como 400.

Dos llaves, una JWT#

  • anon_key — publicable. Sirve como clave API para cualquier solicitud. Encabezado apikey, X-API-Key o parámetro ?apikey=: este último solo se acepta en transmisiones en tiempo real (/ws, /sse, /chat/stream); en otros lugares se rechaza explícitamente.
  • service_role_key — secreto, RLS omisión. Reservado para el backend.
  • user_jwt: emitido por POST /v1/auth/login después de la autenticación. Encabezado Authorization: Bearer.
headers.shbash
# Cliente anónimo (invitado)
-H "apikey: <NEXT_PUBLIC_AURABASE_ANON_KEY>"

# Cliente autenticado (usuario de reclamos)
-H "apikey: <NEXT_PUBLIC_AURABASE_ANON_KEY>"
-H "Authorization: Bearer <USER_JWT>"

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

Normas aplicadas#

  • Content-Type: application/json: requerido en POST/PATCH/PUT (excepto almacenamiento de carga, en multipart/form-data)
  • Prefer: return=representation — devuelve las filas creadas o modificadas; return=minimal para una respuesta sin cuerpo (204). Prefer: count=exact se lee en mutaciones aura-db (encabezados Content-Range + Preference-Applied); Para confiar en que un lea, use el parámetro ?count=exact
  • Range: 0-49 — solo en un proyecto Postgres servido por PostgREST, que lo interpreta él mismo. La ruta aura-db (proyecto MongoDB o Postgres con PostgREST deshabilitado) ignora este encabezado: solo lee limit y offset. Prefiera limit/offset, que funcionan en ambos motores
  • Idempotency-Key — NO se lee en la base de datos (POST /v1/db/…) escribe: dos POST idénticos crean dos filas. Solo se respeta mediante POST /v1/notifications/{project_id}/send (y /send/batch) y mediante la creación de la clave API del plan de gestión (POST /v1/db/{project_id}/api-keys, ventana de 24 horas).

Límite + compensación#

pagination.shbash
# Sólo forma portátil: funciona en ambos motores
GET $NEXT_PUBLIC_AURABASE_URL/v1/db/sensors?order=id.asc&limit=50&offset=100

# Conjunto de claves “a mano”: filtrar por la última clave leída
GET $NEXT_PUBLIC_AURABASE_URL/v1/db/sensors?id=gt.{last_id}&order=id.asc&limit=50

# ?cursor=: aura-db SOLAMENTE (MongoDB o Postgres sin PostgREST).
# El PostgREST se rechaza la solicitud en 400.
GET $NEXT_PUBLIC_AURABASE_URL/v1/db/sensors?cursor={meta.next_cursor}&limit=50
Consejo

Sin limit, una lectura devuelve como máximo 1000 filas; este es el límite máximo predeterminado y estricto. Cuando una consulta en realidad tiene más filas coincidentes más allá del segmento devuelto, meta.has_more es true (y false cuando no existen filas adicionales o se ha alcanzado el segmento final); Solicite count=exact para obtener también meta.total.

Atención

El total no se lee en el mismo lugar dependiendo del motor: en la ruta aura-db, la respuesta lleva el encabezado Content-Range: items 100-149/1247 (el total vale * si no se solicitó ningún recuento); en la ruta PostgREST, la puerta de enlace no transmite este encabezado y coloca el total en meta.total del sobre JSON. El conteo nunca se realiza de forma predeterminada: solicítelo con el parámetro ?count=exact (formulario portátil, traducido a Prefer por la puerta de enlace en la ruta PostgREST), ?count=planned o ?count=estimated.

La descripción OpenAPI de su proyecto se proporciona en GET /v1/db/{project_id}/openapi.json (con su apikey); se genera a partir del esquema en vivo, por lo que aparece en él una tabla que acaba de crear.

Formato uniforme#

error es siempre un objeto, nunca una cadena. Dos variantes, dependiendo del emisor: los campos code y message son comunes a ambos, y es en code (nunca en message, texto libre) que discriminamos.

error emitido por un servicio Aurabasejson
{
  "error": {
    "type": "auth_unauthorized",      // tipo de máquina, con el prefijo de dominio
    "code": "UNAUTHORIZED",         // código estable
    "message": "Unauthorized: Invalid or revoked API key",
    "request_id": "dc20e246-d8e0-412c-b9d7-ce675af6edd5"
  }
}
Error PostgREST traducido por la puerta de enlacejson
{
  "error": {
    "code": "COLUMN_NOT_FOUND",    // nunca el código PGRST sin formato
    "message": "Column unknown_col not found in table sensors",
    "details": ""
  }
}
Atención

Los códigos PostgREST/PostgreSQL (PGRST116, 23505…) nunca devueltos tal como están por la API REST: la puerta de enlace los traduce en códigos 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, en caso contrario POSTGREST_ERROR). Esta variante no lleva type; los errores que puede corregir la persona que llama agrega un hint (una columna o función faltante sugiere el nombre más cercano, una negativa RLS da el create policy para agregar). El SDK de JavaScript mantiene PGRST116 para .single() / .maybeSingle() a propósito, por compatibilidad con supabase-js: en HTTP sin formato, la misma situación es NOT_SINGULAR.

CódigoNombreDescripción
400Solicitud incorrectaCarga útil o consulta con formato incorrecto. error.code es BAD_REQUEST.
401No autorizadoapikey faltante o revocado, o JWT no válido. error.code es UNAUTHORIZED o REFRESH_TOKEN_REJECTED en /refresh.
403prohibidoRLS o el servicio de autorización rechaza la operación. error.code es FORBIDDEN, QUOTA_EXCEEDED o INSUFFICIENT_PRIVILEGE (ruta PostgREST).
404No encontradoEl recurso no existe o RLS lo oculta. error.code es NOT_FOUND, RECORD_NOT_FOUND o TABLE_NOT_FOUND.
406No aceptableSe esperaba una fila, varias regresaron. error.code es NOT_SINGULAR.
409ConflictoViolación de clave única o externa. error.code es CONFLICT, DUPLICATE_KEY o FOREIGN_KEY_VIOLATION. Utilice on_conflict para una inserción.
413Carga útil demasiado grandeSolicitud mayor que MAX_BODY_SIZE (50 MB de forma predeterminada en la puerta de enlace). Utilice una carga de almacenamiento de varias partes.
429Demasiadas solicitudesLímite de tarifa alcanzado. error.code es RATE_LIMITED; message nombra el límite alcanzado (IP, proyecto o clave API) y hint dice cuándo volver a intentarlo. Se establecen los encabezados X-RateLimit-Limit y X-RateLimit-Remaining, y Retry-After en los rechazos de la puerta de enlace.
500Error interno del servidorError del servidor. Dale error.request_id al soporte.
503Servicio no disponibleSERVER_BUSY cuando la puerta de enlace está perdiendo carga (demasiadas solicitudes en curso, Retry-After: 1), DB_POOL_TIMEOUT cuando el grupo de conexiones del proyecto permaneció saturado, el disyuntor abierto, falta una instancia o el proyecto está hibernado (Retry-After: 5 en ese caso). El interruptor vuelve a intentarlo después de 30 segundos.
504Tiempo de espera de puerta de enlaceTiempo de espera ascendente. error.code es TIMEOUT o STATEMENT_TIMEOUT cuando una instrucción SQL se ejecutó por más tiempo que el tiempo de espera de 10 segundos de la instrucción del proyecto.

Por IP en el gateway, más límites por ruta#

  • Por proyecto y clave API: el límite del plan del proyecto (Estudio › Configuración › Uso). Un 429 nombra el alcance afectado, para que sepa si reducir la velocidad o actualizar.
  • Gateway, todas las rutas: por IP, 100 requiere/s con una ráfaga de 1000 de forma predeterminada (ajustable mediante RATE_LIMIT_RPS / RATE_LIMIT_BURST). No hay un nivel separado por función.
  • Sensible a autenticación (login, register, forgot-password, magic-link, email-otp/send, sms/send, refresh, mfa/verify-login): 5 solicitudes/min por IP, ráfaga 3. Además, una cuota por proyecto: 30 conexiones intentos/hora por IP por defecto, ajustable en la configuración del proyecto. En desarrollo (AURA_ENV=development, la pila local), el límite del enrutador se relaja (ráfaga 100) para que pueda iterar; las cuotas del proyecto que se muestran en Studio › Autenticación › Configuración › Limitación de velocidad siempre se aplican.
  • SQL sin formato (/raw): 30 solicitudes/min, ráfaga 10. IA: 10 solicitudes/min, ráfaga 5.
Atención

Desbordamiento → 429 Too Many Requests con los encabezados X-RateLimit-Limit y X-RateLimit-Remaining (presentes en cualquier respuesta de la puerta de enlace), más X-RateLimit-Reset y Retry-After en el rechazo.

Árbol completo por servicio#

Cada punto final tiene su página dedicada con parámetros, códigos de respuesta, ejemplos en 5 idiomas y código ferroviario en vivo.

Base de datosAutenticaciónAlmacenamientoTiempo realFunciones

Aún no hay SDK para tu idioma#

Aún no hay ningún paquete Python o Dart publicado (el estudio también lo dice). La API REST anterior está completa, por lo que un cliente tiene unas pocas líneas. La versión de Python utiliza sólo la biblioteca estándar; lee las mismas variables que los otros ejemplos y convierte un error de API en una excepción que lleva el code estable y el 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"]  # o AURABASE_SERVICE_ROLE_KEY en un servidor


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 versión Dart (Flutter o server) tampoco necesita paquete; ejecútelo con 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'));
}

para ir más lejos#