Skip to content
Aurabase Logo
aurabase

REST API — Overview

Aurabase raw HTTP surface. Compatible with all languages. Base URL, authentication, response format, error codes — then details by endpoint in /docs/api/.

Reference7 min readLevel referenceRevised on Apr 15, 2026

An origin, the project on the way#

The URL is the project. Each project is served on its own sub-domain, https://<slug>.<apex> (locally http://<slug>.localhost:8080), and the gateway resolves the project from the host: no project identifier is written in the paths. Studio › Settings › Connection shows this URL, and NEXT_PUBLIC_AURABASE_URL holds it. The gateway exposes two plans: the data plan (SDK and applications, :8080 locally) and the management plan (Studio and administration, :8090). The data plan surfaces are prefixed /v1/db, /v1/auth, /v1/storage, /v1/realtime, /v1/functions, /v1/notifications, /v1/ai.

examplesbash
# NEXT_PUBLIC_AURABASE_URL = project URL (e.g. 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
Info

The forms that carry the project UUID in the path (/v1/db/{project_id}/sensors, /v1/auth/{project_id}/login, as in the endpoint reference pages) are still accepted on the project URL, and also on the bare gateway origin. They are kept for compatibility: prefer the forms above, which do not depend on the identifier.

Attention

The streaming routes /v1/realtime/ws and /v1/realtime/sse are served as they are on the project host. A URL that does not identify a project (for example the bare gateway origin without a project identifier) is rejected as 400.

Two keys, one JWT#

  • 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/login after authentication. Header Authorization: Bearer.
headers.shbash
# Anonymous customer (guest)
-H "apikey: <NEXT_PUBLIC_AURABASE_ANON_KEY>"

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

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

Standards applied#

  • Content-Type: application/json — required on POST/PATCH/PUT (except upload storage, in multipart/form-data)
  • Prefer: return=representation — returns the rows created or 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 rows. 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)

Limit + offset#

pagination.shbash
# Only portable form — works on both engines
GET $NEXT_PUBLIC_AURABASE_URL/v1/db/sensors?order=id.asc&limit=50&offset=100

# Keyset “by hand”: filter on the last key read
GET $NEXT_PUBLIC_AURABASE_URL/v1/db/sensors?id=gt.{last_id}&order=id.asc&limit=50

# ?cursor=: aura-db ONLY (MongoDB, or Postgres without PostgREST).
# On PostgREST the request is refused in 400.
GET $NEXT_PUBLIC_AURABASE_URL/v1/db/sensors?cursor={meta.next_cursor}&limit=50
Tip

Without limit, a read returns at most 1000 rows — this is both the default and the hard ceiling. When a query actually has more matching rows beyond the returned slice, meta.has_more is true (and false when no additional rows exist or the final slice has been reached); ask for count=exact to also get meta.total.

Attention

The total is not read in the same place depending on the engine: on the aura-db path, the response carries the header Content-Range: items 100-149/1247 (the total is worth * if no count was requested); on the PostgREST path, the gateway does not relay this header and places the total in meta.total of the JSON envelope. Counting is never done by default: request it with the parameter ?count=exact (portable form, translated into Prefer by the gateway on the PostgREST path), ?count=planned, or ?count=estimated.

The OpenAPI description of your project is served at GET /v1/db/{project_id}/openapi.json (with your apikey); it is generated from the live schema, so a table you just created appears in it.

Uniform format#

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 emitted by an Aurabase servicejson
{
  "error": {
    "type": "auth_unauthorized",      // machine type, prefixed by domain
    "code": "UNAUTHORIZED",         // stable code
    "message": "Unauthorized: Invalid or revoked API key",
    "request_id": "dc20e246-d8e0-412c-b9d7-ce675af6edd5"
  }
}
PostgREST error translated by the gatewayjson
{
  "error": {
    "code": "COLUMN_NOT_FOUND",    // never the raw PGRST code
    "message": "Column unknown_col not found in table sensors",
    "details": ""
  }
}
Attention

PostgREST/PostgreSQL codes (PGRST116, 23505…) are never returned as is by the REST API: the gateway translates them into Aurabase codes (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, otherwise POSTGREST_ERROR). This variant carries no type; errors that can be fixed by the caller add a hint (a missing column or function suggests the closest name, an RLS refusal gives the create policy to add). The JavaScript SDK keeps PGRST116 for .single() / .maybeSingle() on purpose, for compatibility with supabase-js: on raw HTTP the same situation is NOT_SINGULAR.

CodeNameDescription
400Bad RequestMalformed payload or query. error.code is BAD_REQUEST.
401UnauthorizedMissing or revoked apikey, or invalid JWT. error.code is UNAUTHORIZED, or REFRESH_TOKEN_REJECTED on /refresh.
403ForbiddenRLS or the authorization service refuses the operation. error.code is FORBIDDEN, QUOTA_EXCEEDED or INSUFFICIENT_PRIVILEGE (PostgREST path).
404Not FoundThe resource does not exist or RLS hides it. error.code is NOT_FOUND, RECORD_NOT_FOUND or TABLE_NOT_FOUND.
406Not AcceptableOne row expected, several returned. error.code is NOT_SINGULAR.
409ConflictUnique or foreign key violation. error.code is CONFLICT, DUPLICATE_KEY or FOREIGN_KEY_VIOLATION. Use on_conflict for an upsert.
413Payload Too LargeRequest larger than MAX_BODY_SIZE (50 MB by default on the gateway). Use a multipart storage upload.
429Too Many RequestsRate limit reached. error.code is RATE_LIMITED; message names the limit that was hit (IP, project or API key) and hint says when to retry. X-RateLimit-Limit and X-RateLimit-Remaining headers are set, and Retry-After on gateway refusals.
500Internal Server ErrorServer error. Give error.request_id to support.
503Service UnavailableSERVER_BUSY when the gateway is shedding load (too many requests in flight, Retry-After: 1), DB_POOL_TIMEOUT when the project's connection pool stayed saturated, circuit breaker open, instance missing, or project hibernated (Retry-After: 5 in that case). The breaker retries after 30 seconds.
504Gateway TimeoutUpstream timeout. error.code is TIMEOUT, or STATEMENT_TIMEOUT when a SQL statement ran longer than the project's 10-second statement timeout.

By IP at the gateway, plus limits per route#

  • Per project and API key: the limit of the project's plan (Studio › Settings › Usage). A 429 names the scope that was hit, so you know whether to slow down or upgrade.
  • Gateway, all routes: per IP, 100 req/s with a burst of 1000 by default (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. In development (AURA_ENV=development, the local stack), the router limit is relaxed (burst 100) so you can iterate; the project quotas shown in Studio › Authentication › Configuration › Rate limiting always apply.
  • Raw SQL (/raw): 30 req/min, burst 10. IA: 10 req/min, burst 5.
Attention

Overflow → 429 Too Many Requests with the headers X-RateLimit-Limit and X-RateLimit-Remaining (present on any response from the gateway), plus X-RateLimit-Reset and Retry-After on the refusal.

Complete tree per service#

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

DatabaseAuthStorageRealtimeFunctions

No SDK for your language yet#

There is no published Python or Dart package yet (the Studio says so too). The REST API above is complete, so a client is a few lines. The Python version uses only the standard library; it reads the same variables as the other examples and turns an API error into an exception that carries the stable code and the 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"]  # or AURABASE_SERVICE_ROLE_KEY on a server


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"))

The Dart version (Flutter or server) needs no package either; run it with 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'));
}

To go further#