Desenvolvedores — visão geral da API

Selo de estado: Preview (limite atual do produto). · API de consulta REST (/api/v1/query, /api/v1/tables) = fora de GA (indisponível hoje) · OData v4 / Power BI / Excel = Preview · Embed SDK = Preview · Atualizado em 2026-09-06.

Esta seção documenta como integrar sistemas externos ao seu datalake do ingestia.io: autenticação por chave, os feeds de dados (OData/Power BI/Excel), o SDK de embed de painéis, o formato de erros, paginação, limites e o estado real de cada superfície. Nenhuma superfície de integração é anunciada como GA disponível hoje.

Mapa da seção#

Estados — o que cada selo significa#

• Preview — funciona e é documentado, mas sem SLA e sujeito a ajustes. Use em produção por sua conta e risco; avise o suporte para acompanhar.
• Fora de GA (indisponível hoje) — a capacidade existe no código, mas não está liberada para uso externo enquanto as proteções de custo e de limite de requisições não forem endurecidas e comprovadas. Não construa integrações críticas sobre ela ainda. É o caso da API de consulta REST.
• Roadmap — planejado, ainda não disponível (ex.: assinatura de webhooks).

Convenções gerais#

• Base: https://ingestia.io. Todas as rotas de dados ficam sob /api/v1.
• Escopo por workspace (inviolável): toda credencial é escopada ao workspace que a emitiu. A API nunca cruza datasets/buckets entre clientes e só expõe os marts publicados (*_gold e *_silver) — nunca a camada bronze.
• Somente leitura: não existe API de escrita. Toda rota é GET (ou POST apenas para enviar um SELECT). Por isso, as chamadas são idempotentes por natureza (ver Erros e limites).
• Formato de resposta: JSON (application/json; charset=utf-8); o OData responde JSON e $metadata em XML (EDMX).
• Formato de erro: sempre { "error": "mensagem em português" } com o código HTTP correspondente. O catálogo completo está em Erros e limites.
• CORS: as rotas de dados respondem a OPTIONS (pré-flight) e liberam Authorization e Content-Type.
• Cabeçalho de escopo: toda resposta traz X-Ingestia-Access-Scope: workspace — lembrete de que a credencial lê o workspace inteiro, não um usuário.
• Custo transparente: cada extração paga devolve x-ingestia-cost-brl com o valor da chamada. O valor em BRL é uma projeção, não um preço faturado garantido hoje.
• Compatibilidade N−1: formatos versionados (widgets, filtros, tema, estado de URL, token de embed) preservam a leitura da versão anterior; um campo desconhecido nunca é descartado silenciosamente.

Suporte ao desenvolvedor#

Dúvidas de integração, inclusão do domínio na allowlist de embed ou relato de erro: veja Central de Suporte e Troubleshooting.

Próximos passos: Autenticação → OData/Power BI.

Estado & evidência: limite atual do produto = Preview (nada GA). OData = Preview; Embed SDK = Preview (rotulado conservadoramente); API de consulta REST = fora de GA até endurecimento de rate-limit/custo. Fonte de estado: matriz de estados do produto.