Ir para o conteúdo
Aura Logo
aurabase

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

Referência7 min lidoNível referênciaRevisado em 15 de abr. de 2026

Esta página foi traduzida automaticamente. A versão em inglês é oficial.

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.

examplesbash
# 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
Informações

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.

Atenção

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çalho apikey, X-API-Key ou 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 por POST /v1/auth/login após autenticação. Cabeçalho Authorization: Bearer.
headers.shbash
# 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, em multipart/form-data)
  • Prefer: return=representation — retorna as linhas criadas ou modificadas; return=minimal para uma resposta sem corpo (204). Prefer: count=exact é lido em mutações aura-db (cabeçalhos Content-Range + Preference-Applied); Para contar com uma leitura de , use o parâmetro ?count=exact
  • Range: 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ê apenas limit e offset. Prefira limit/offset, que funcionam em ambos os motores
  • Idempotency-Key — NÃO é lido no banco de dados (POST /v1/db/…) grava: dois POSTs idênticos criam duas linhas. É honrado apenas por POST /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#

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

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.

Atenção

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.

erro emitido por um serviço Aurabasejson
{
  "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"
  }
}
Erro PostgREST traduzido pelo gatewayjson
{
  "error": {
    "code": "COLUMN_NOT_FOUND",    // nunca o código PGRST bruto
    "message": "Column unknown_col not found in table sensors",
    "details": ""
  }
}
Atenção

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ódigoNomeDescrição
400Solicitação incorretaCarga útil ou consulta malformada. error.code é BAD_REQUEST.
401Não autorizadoapikey ausente ou revogado ou JWT inválido. error.code é UNAUTHORIZED ou REFRESH_TOKEN_REJECTED em /refresh.
403ProibidoRLS ou o serviço de autorização recusa a operação. error.code é FORBIDDEN, QUOTA_EXCEEDED ou INSUFFICIENT_PRIVILEGE (caminho PostgREST).
404Não encontradoO recurso não existe ou RLS o oculta. error.code é NOT_FOUND, RECORD_NOT_FOUND ou TABLE_NOT_FOUND.
406Não aceitávelUma linha esperada, várias retornadas. error.code é NOT_SINGULAR.
409ConflitoViolação de chave única ou estrangeira. error.code é CONFLICT, DUPLICATE_KEY ou FOREIGN_KEY_VIOLATION. Use on_conflict para um upsert.
413Carga útil muito grandeSolicitação maior que MAX_BODY_SIZE (50 MB por padrão no gateway). Use um upload de armazenamento multiparte.
429Muitas solicitaçõesLimite 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.
500Erro interno do servidorErro no servidor. Dê error.request_id para suporte.
503Serviço indisponívelSERVER_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.
504Tempo limite do gatewayTempo 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 429 nomeia o escopo que foi atingido, para que você saiba se deve desacelerar ou atualizar.
  • Gateway, todas as rotas: por IP, 100 req/s com uma explosão de 1000 por padrão (ajustável via RATE_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.
Atenção

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:

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 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:

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 mais longe#