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/.
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.
# 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
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.
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. Headerapikey,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 byPOST /v1/auth/loginafter authentication. HeaderAuthorization: Bearer.
# 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, inmultipart/form-data)Prefer: return=representation— returns the rows created or modified;return=minimalfor a response without a body (204).Prefer: count=exactis read on aura-db mutations (headersContent-Range+Preference-Applied); To rely on a reading, use the?count=exactparameterRange: 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 readslimitandoffset. Preferlimit/offset, which work on both enginesIdempotency-Key— is NOT read on Database (POST /v1/db/…) writes: two identical POSTs create two rows. It is only honored byPOST /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#
# 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
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.
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": {
"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"
}
}
{
"error": {
"code": "COLUMN_NOT_FOUND", // never the raw PGRST code
"message": "Column unknown_col not found in table sensors",
"details": ""
}
}
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.
| Code | Name | Description |
|---|---|---|
400 | Bad Request | Malformed payload or query. error.code is BAD_REQUEST. |
401 | Unauthorized | Missing or revoked apikey, or invalid JWT. error.code is UNAUTHORIZED, or REFRESH_TOKEN_REJECTED on /refresh. |
403 | Forbidden | RLS or the authorization service refuses the operation. error.code is FORBIDDEN, QUOTA_EXCEEDED or INSUFFICIENT_PRIVILEGE (PostgREST path). |
404 | Not Found | The resource does not exist or RLS hides it. error.code is NOT_FOUND, RECORD_NOT_FOUND or TABLE_NOT_FOUND. |
406 | Not Acceptable | One row expected, several returned. error.code is NOT_SINGULAR. |
409 | Conflict | Unique or foreign key violation. error.code is CONFLICT, DUPLICATE_KEY or FOREIGN_KEY_VIOLATION. Use on_conflict for an upsert. |
413 | Payload Too Large | Request larger than MAX_BODY_SIZE (50 MB by default on the gateway). Use a multipart storage upload. |
429 | Too Many Requests | Rate 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. |
500 | Internal Server Error | Server error. Give error.request_id to support. |
503 | Service Unavailable | SERVER_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. |
504 | Gateway Timeout | Upstream 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
429names the scope that was hit, so you know whether to slow down or upgrade. - Gateway, all routes: per IP,
100req/s with a burst of1000by default (adjustable viaRATE_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.
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:
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:
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'));
}