API de consulta (REST) — `/api/v1/query` e `/api/v1/tables`

Selo de estado: FORA DE GA — indisponível para uso externo hoje. A API de consulta REST executa processamento cobrável no datalake; ela só será liberada quando as proteções de limite de requisições e de custo estiverem endurecidas e comprovadas. Atualizado em 2026-09-06.

Não construa integrações críticas sobre estas rotas ainda. Para consumo externo de dados hoje, use o feed OData (Power BI/Excel), que está em Preview.

Esta página documenta o contrato da API REST para transparência e planejamento. O comportamento descrito é o do código atual, mas a capacidade não está em disponibilidade geral.

Disponibilidade#

• Estado operacional: fora de GA. Motivo: são rotas que disparam consultas pagas no datalake e a guarda de rate limit precisa operar em modo fail-closed comprovado (negar quando o limitador estiver indisponível) antes de liberar.
• Alternativa disponível: OData v4 / Power BI / Excel (Preview) cobre a leitura de tabelas dos marts publicados.
• Região: Brasil (São Paulo).

Permissões#

• Autenticação por chave de API (ver Autenticação).
• /api/v1/tables exige a ação de exportação de dados (papel member+ / chave de dados do dono).
• /api/v1/query (SQL livre) exige a ação de consulta de dados (admin+); a chave também precisa do escopo read/read_query.

Endpoints (contrato)#

GET /api/v1/tables

Lista as tabelas dos marts publicados (gold + silver) do workspace.

[
  { "dataset": "aurora_gold", "table": "vendas", "layer": "gold",
    "columns": [{ "name": "data", "type": "DATE" }, { "name": "total", "type": "NUMERIC" }] }
]

GET /api/v1/tables/{dataset}/{table}?limit=&offset=

Linhas paginadas de uma tabela publicada. dataset precisa ser um mart do workspace (<prefixo>_gold ou <prefixo>_silver) — qualquer outro responde 403.

• limit: padrão 100, máximo 1000.
• offset: deslocamento inicial.

{ "table": "vendas", "rows": [ /*... */ ], "rowCount": 100, "nextOffset": 100 }

nextOffset é null quando não há mais páginas.

POST /api/v1/query

SQL somente leitura (SELECT/WITH … SELECT) escopado ao workspace.

// corpo
{ "sql": "SELECT data, SUM(total) AS total FROM aurora_gold.vendas GROUP BY data", "limit": 500 }

// resposta
{ "rows": [ /*... */ ], "rowCount": 42 }

Se o resultado for cortado por segurança, a resposta inclui "truncated": true e "totalRows" — para a soma do outro lado não sair errada.

Defesas aplicadas antes de tocar o datalake (em camadas):

1. Só SELECT — qualquer INSERT/UPDATE/DELETE/DDL/… → 403.
2. Sem cruzar workspace — referência a dataset de outro cliente ou a outro projeto → 403.
3. Sem construções perigosas — EXTERNAL_QUERY, metadados de projeto (INFORMATION_SCHEMA/JOBS_*), etc. → 403.
4. Só marts publicados — apenas *_gold/*_silver; referência a bronze ou a qualquer outro dataset → 403.
5. Guarda de custo — teto de bytes faturados aplicado ao job.

Validação (quando estiver liberada)#

• GET /api/v1/tables responde 200 com a lista de tabelas.
• Uma consulta a dataset fora do workspace responde 403 com mensagem explícita.
• Enquanto fora de GA, integrações devem tratar respostas de indisponibilidade (503) como estado esperado.

Exemplo#

# Listar tabelas
curl -H "Authorization: Bearer ing_live_..." https://ingestia.io/api/v1/tables

# Puxar 100 linhas
curl -H "Authorization: Bearer ing_live_..." \
  "https://ingestia.io/api/v1/tables/aurora_gold/vendas?limit=100&offset=0"

# SQL livre (read-only)
curl -X POST -H "Authorization: Bearer ing_live_..." -H "Content-Type: application/json" \
  -d '{"sql":"SELECT * FROM aurora_gold.vendas LIMIT 10"}' \
  https://ingestia.io/api/v1/query

Custo#

• Cobra por bytes realmente processados no datalake — LIMIT/OFFSET não reduzem os bytes lidos. Paginar tabela grande é a forma mais cara de extrair; prefira SELECT com filtro/agregação.
• Consultas idênticas (mesma versão do workspace) servem do cache com custo R$ 0.
• O valor em x-ingestia-cost-brl é uma projeção, não um preço faturado garantido hoje.

Segurança#

• Somente leitura + escopo por workspace (marts publicados apenas).
• Colunas PII não são expostas por esta API.
• Consultas e cobranças ficam registradas na auditoria do workspace.

Limites#

• limit máximo por página: 1000.
• Chave de nível workspace (sem recorte por membro).
• Rate limit por chave e por workspace (ver Erros e limites).
• Sem escrita — não há endpoint de INSERT/UPDATE/DELETE.

Troubleshooting#

Próximos passos: OData v4 / Power BI / Excel (alternativa disponível) · Erros e limites.

Estado & evidência: capacidade /api/v1 REST = fora de GA (rate-limit/ custo em endurecimento) — não anunciar como disponível. Fonte: matriz de estados do produto.