API REST – Visão geral
Aurabase superfície HTTP bruta. Compatível com todos os idiomas. URL base, autenticação, formato de resposta, códigos de erro — depois detalhes por endpoint em /docs/api/.
Uma origem, o projeto a caminho#
A URL é do projeto. Cada projeto é servido em seu próprio subdomínio, https://<slug>.<apex> (localmente http://<slug>.localhost:8080), e o gateway resolve o projeto a partir do host: nenhum identificador de projeto é escrito nos caminhos. Studio › Configurações › Connection mostra este URL e NEXT_PUBLIC_AURABASE_URL o mantém. O gateway expõe dois planos: o plano de dados (SDK e aplicativos, :8080 localmente) e o plano de gerenciamento (Estúdio e administração, :8090). As superfícies do plano de dados são prefixadas /v1/db, /v1/auth, /v1/storage, /v1/realtime, /v1/functions, /v1/notifications, /v1/ai.
# NEXT_PUBLIC_AURABASE_URL = URL do projeto (por exemplo, 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
Os formulários que carregam o UUID do projeto no caminho (/v1/db/{project_id}/sensors, /v1/auth/{project_id}/login, como nas páginas de referência do endpoint) ainda são aceitos na URL do projeto e também na origem do gateway simples. São mantidos para compatibilidade: prefira os formulários acima, que independem do identificador.
As rotas de streaming /v1/realtime/ws e /v1/realtime/sse são servidas como estão no host do projeto. Uma URL que não identifica um projeto (por exemplo, a origem do gateway simples sem um identificador de projeto) é rejeitada como 400.
Duas chaves, uma JWT#
anon_key— publicável. Serve como chave de API para qualquer solicitação. Cabeçalhoapikey,X-API-Keyou parâmetro?apikey=— este último só é aceito em streams em tempo real (/ws,/sse,/chat/stream); em outros lugares, é explicitamente recusado.service_role_key— segredo, desvio de RLS. Reservado para o back-end.user_jwt— emitido porPOST /v1/auth/loginapós autenticação. CabeçalhoAuthorization: Bearer.
# Cliente anônimo (convidado)
-H "apikey: <NEXT_PUBLIC_AURABASE_ANON_KEY>"
# Cliente autenticado (usuário de declarações)
-H "apikey: <NEXT_PUBLIC_AURABASE_ANON_KEY>"
-H "Authorization: Bearer <USER_JWT>"
# Back-end (ignorar RLS)
-H "apikey: <AURABASE_SERVICE_ROLE_KEY>"
-H "Authorization: Bearer <AURABASE_SERVICE_ROLE_KEY>"
Padrões aplicados#
Content-Type: application/json— necessário em POST/PATCH/PUT (exceto armazenamento de upload, emmultipart/form-data)Prefer: return=representation— retorna as linhas criadas ou modificadas;return=minimalpara uma resposta sem corpo (204).Prefer: count=exacté lido em mutações aura-db (cabeçalhosContent-Range+Preference-Applied); Para contar com uma leitura de , use o parâmetro?count=exactRange: 0-49— apenas em um projeto Postgres servido por PostgREST, que o interpreta por si só. O caminho aura-db (projeto MongoDB ou Postgres com PostgREST desabilitado) ignora este cabeçalho: ele lê apenaslimiteoffset. Prefiralimit/offset, que funcionam em ambos os motoresIdempotency-Key— NÃO é lido no banco de dados (POST /v1/db/…) grava: dois POSTs idênticos criam duas linhas. É honrado apenas porPOST /v1/notifications/{project_id}/send(e/send/batch) e pela criação da chave API do plano de gerenciamento (POST /v1/db/{project_id}/api-keys, janela de 24 horas)
Limite + deslocamento#
# Apenas formato portátil – funciona em ambos os motores
GET $NEXT_PUBLIC_AURABASE_URL/v1/db/sensors?order=id.asc&limit=50&offset=100
# Conjunto de chaves “manualmente”: filtro na última chave lida
GET $NEXT_PUBLIC_AURABASE_URL/v1/db/sensors?id=gt.{last_id}&order=id.asc&limit=50
# ?cursor=: SOMENTE aura-db (MongoDB ou Postgres sem PostgREST).
# Em PostgREST a solicitação é recusada em 400.
GET $NEXT_PUBLIC_AURABASE_URL/v1/db/sensors?cursor={meta.next_cursor}&limit=50
Sem limit, uma leitura retorna no máximo 1000 linhas — este é o padrão e o limite máximo. Quando uma consulta realmente tem mais linhas correspondentes além da fatia retornada, meta.has_more é true (e false quando não existem linhas adicionais ou a fatia final foi alcançada); peça count=exact para obter também meta.total.
O total não é lido no mesmo local dependendo do motor: no caminho aura-db, a resposta carrega o cabeçalho Content-Range: items 100-149/1247 (o total vale * se nenhuma contagem foi solicitada); no caminho PostgREST, o gateway não retransmite esse cabeçalho e coloca o total em meta.total do envelope JSON. A contagem nunca é feita por padrão: solicite-a com o parâmetro ?count=exact (formato portátil, traduzido para Prefer pelo gateway no caminho PostgREST), ?count=planned, ou ?count=estimated.
A descrição OpenAPI do seu projeto é veiculada em GET /v1/db/{project_id}/openapi.json (com seu apikey); ele é gerado a partir do esquema ativo, portanto, uma tabela que você acabou de criar aparece nele.
Formato uniforme#
error é sempre um objeto, nunca uma string. Duas variantes, dependendo do emissor - os campos code e message são comuns a ambos, e é em code (nunca em message, texto livre) que discriminamos.
{
"error": {
"type": "auth_unauthorized", // tipo de máquina, prefixado por domínio
"code": "UNAUTHORIZED", // código estável
"message": "Unauthorized: Invalid or revoked API key",
"request_id": "dc20e246-d8e0-412c-b9d7-ce675af6edd5"
}
}
{
"error": {
"code": "COLUMN_NOT_FOUND", // nunca o código PGRST bruto
"message": "Column unknown_col not found in table sensors",
"details": ""
}
}
Os códigos PostgREST/PostgreSQL (PGRST116, 23505…) são nunca retornados como estão pela API REST: o gateway os traduz em 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, caso contrário POSTGREST_ERROR). Esta variante não contém type; erros que podem ser corrigidos pelo chamador adicionam um hint (uma coluna ou função ausente sugere o nome mais próximo, uma recusa de RLS fornece o create policy para adicionar). O JavaScript SDK mantém PGRST116 para .single() / .maybeSingle() propositalmente, para compatibilidade com supabase-js: em HTTP bruto a mesma situação é NOT_SINGULAR.
| Código | Nome | Descrição |
|---|---|---|
400 | Solicitação incorreta | Carga útil ou consulta malformada. error.code é BAD_REQUEST. |
401 | Não autorizado | apikey ausente ou revogado ou JWT inválido. error.code é UNAUTHORIZED ou REFRESH_TOKEN_REJECTED em /refresh. |
403 | Proibido | RLS ou o serviço de autorização recusa a operação. error.code é FORBIDDEN, QUOTA_EXCEEDED ou INSUFFICIENT_PRIVILEGE (caminho PostgREST). |
404 | Não encontrado | O recurso não existe ou RLS o oculta. error.code é NOT_FOUND, RECORD_NOT_FOUND ou TABLE_NOT_FOUND. |
406 | Não aceitável | Uma linha esperada, várias retornadas. error.code é NOT_SINGULAR. |
409 | Conflito | Violação de chave única ou estrangeira. error.code é CONFLICT, DUPLICATE_KEY ou FOREIGN_KEY_VIOLATION. Use on_conflict para um upsert. |
413 | Carga útil muito grande | Solicitação maior que MAX_BODY_SIZE (50 MB por padrão no gateway). Use um upload de armazenamento multiparte. |
429 | Muitas solicitações | Limite de taxa atingido. error.code é RATE_LIMITED; message nomeia o limite que foi atingido (IP, projeto ou chave API) e hint diz quando tentar novamente. Os cabeçalhos X-RateLimit-Limit e X-RateLimit-Remaining são definidos e Retry-After nas recusas do gateway. |
500 | Erro interno do servidor | Erro no servidor. Dê error.request_id para suporte. |
503 | Serviço indisponível | SERVER_BUSY quando o gateway está liberando carga (muitas solicitações em andamento, Retry-After: 1), DB_POOL_TIMEOUT quando o pool de conexões do projeto permaneceu saturado, disjuntor aberto, instância ausente ou projeto hibernado (Retry-After: 5 nesse caso). O disjuntor tenta novamente após 30 segundos. |
504 | Tempo limite do gateway | Tempo limite de envio. error.code é TIMEOUT ou STATEMENT_TIMEOUT quando uma instrução SQL foi executada por mais tempo do que o tempo limite de instrução de 10 segundos do projeto. |
Por IP no gateway, mais limites por rota#
- Por projeto e chave API: o limite do plano do projeto (Studio › Configurações › Uso). Um
429nomeia o escopo que foi atingido, para que você saiba se deve desacelerar ou atualizar. - Gateway, todas as rotas: por IP,
100req/s com uma explosão de1000por padrão (ajustável viaRATE_LIMIT_RPS/RATE_LIMIT_BURST). Não há um nível separado por função. - Autenticação sensível (
login,register,forgot-password,magic-link,email-otp/send,sms/send,refresh,mfa/verify-login): 5 req/min por IP, burst 3. Além disso, uma cota por projeto: 30 conexões tentativas/hora por IP por padrão, ajustáveis nas configurações do projeto. No desenvolvimento (AURA_ENV=development, a pilha local), o limite do roteador é relaxado (burst 100) para que você possa iterar; as cotas do projeto mostradas em Studio › Autenticação › Configuração › Limitação de taxa sempre se aplicam. - SQL bruto (
/raw): 30 req/min, burst 10. IA: 10 req/min, burst 5.
Overflow → 429 Too Many Requests com os cabeçalhos X-RateLimit-Limit e X-RateLimit-Remaining (presentes em qualquer resposta do gateway), mais X-RateLimit-Reset e Retry-After na recusa.
Árvore completa por serviço#
Cada endpoint possui sua página dedicada com parâmetros, códigos de resposta, exemplos em 5 idiomas e código live rail.
Banco de dadosAutenticaçãoArmazenamentoTempo realFunções
Ainda não há SDK para seu idioma#
Ainda não existe nenhum pacote Python ou Dart publicado (o Studio também diz isso). A API REST acima está completa, então um cliente tem algumas linhas. A versão Python usa apenas a biblioteca padrão; ele lê as mesmas variáveis dos outros exemplos e transforma um erro de API em uma exceção que carrega o code estável e o 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 em um 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"))
A versão Dart (Flutter ou servidor) também não precisa de pacote; execute-o com 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'));
}