La API de consulta REST está en acceso anticipado y todavía no está abierta para uso externo. Ejecuta procesamiento facturable en el datalake; la apertura llega junto con las protecciones finales de límite de solicitudes y de costo.
No construyas integraciones críticas sobre estas rutas todavía. Para el consumo externo de datos hoy, usa el feed OData (Power BI/Excel), que está disponible.
Esta página documenta el contrato de la API REST por transparencia y planificación. El comportamiento descrito es el del código actual; el contrato puede cambiar con aviso mientras la API esté en acceso anticipado.
Disponibilidad#
- Estado: acceso anticipado. Motivo: son rutas que disparan consultas pagadas en el datalake y la protección de rate limit necesita operar en modo fail-closed comprobado (denegar cuando el limitador no esté disponible) antes de liberarse.
- Alternativa disponible: OData v4 / Power BI / Excel (disponible) cubre la lectura de tablas de los marts publicados.
- Región: Brasil (São Paulo).
Permisos#
- Autenticación por clave de API (consulta Autenticación).
/api/v1/tablesexige la acción de exportación de datos (rol member+ / clave de datos del dueño)./api/v1/query(SQL libre) exige la acción de consulta de datos (admin+); la clave también necesita el alcanceread/read_query.
Endpoints (contrato)#
GET /api/v1/tables
Lista las tablas de los marts publicados (gold + silver) del workspace.
[
{ "dataset": "prd_aurora_gold", "table": "vendas", "layer": "gold",
"columns": [{ "name": "data", "type": "DATE" }, { "name": "total", "type": "NUMERIC" }] }
]GET /api/v1/tables/{dataset}/{table}?limit=&offset=
Filas paginadas de una tabla publicada. dataset debe ser un mart del workspace
(<prefixo>_gold o <prefixo>_silver) — cualquier otro responde 403.
limit: predeterminado 100, máximo 1000.offset: desplazamiento inicial.
{ "table": "vendas", "rows": [ /*... */ ], "rowCount": 100, "nextOffset": 100 }nextOffset es null cuando no hay más páginas.
POST /api/v1/query
SQL de solo lectura (SELECT/WITH … SELECT) con alcance en el workspace.
// cuerpo
{ "sql": "SELECT data, SUM(total) AS total FROM prd_aurora_gold.vendas GROUP BY data", "limit": 500 }// respuesta
{ "rows": [ /*... */ ], "rowCount": 42 }Si el resultado se corta por seguridad, la respuesta incluye
"truncated": true y "totalRows" — para que la suma del otro lado no salga mal.
Defensas aplicadas antes de tocar el datalake (en capas):
- Solo
SELECT— cualquierINSERT/UPDATE/DELETE/DDL/…→403. - Sin cruzar workspaces — una referencia a un dataset de otro cliente o a otro
proyecto →
403. - Sin construcciones peligrosas —
EXTERNAL_QUERY, metadatos del proyecto (INFORMATION_SCHEMA/JOBS_*), etc. →403. - Solo marts publicados — solo
*_gold/*_silver; una referencia abronzeo a cualquier otro dataset →403. - Protección de costo — tope de bytes facturados aplicado al job.
Validación (cuando se libere)#
GET /api/v1/tablesresponde200con la lista de tablas.- Una consulta a un dataset fuera del workspace responde
403con un mensaje explícito. - Mientras esté en acceso anticipado, las integraciones deben tratar las respuestas de indisponibilidad
(
503) como un estado esperado.
Ejemplo#
# 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/prd_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 prd_aurora_gold.vendas LIMIT 10"}' \
https://ingestia.io/api/v1/queryCosto#
- Cobra por los bytes realmente procesados en el datalake —
LIMIT/OFFSETno reducen los bytes leídos. Paginar una tabla grande es la forma más cara de extraer; prefiere unSELECTcon filtro/agregación. - Las consultas idénticas (misma versión del workspace) se sirven desde la caché con costo R$ 0.
- El valor en
x-ingestia-cost-brles una proyección, no un precio facturado garantizado hoy.
Seguridad#
- Solo lectura + alcance por workspace (solo marts publicados).
- Las columnas PII no se exponen por esta API.
- Las consultas y cobros quedan registrados en la auditoría del workspace.
Límites#
limitmáximo por página: 1000.- Clave a nivel de workspace (sin recorte por miembro).
- Rate limit por clave y por workspace (consulta Errores y límites).
- Sin escritura — no hay endpoint de
INSERT/UPDATE/DELETE.
Troubleshooting#
| Síntoma | Causa probable | Qué hacer |
|---|---|---|
503 recurrente | capacidad en acceso anticipado / datalake no aprovisionado | usa el feed OData; haz seguimiento con soporte |
403 Apenas consultas SELECT (solo SELECT) | SQL de escritura/DDL | usa solo SELECT/WITH … SELECT |
403 fora do workspace (fuera del workspace) | referencia a un dataset de otro cliente/proyecto | consulta solo *_gold/*_silver de tu workspace |
403 só marts publicados (solo marts publicados) | referencia a bronze/otro dataset | apunta a gold/silver |
| Factura de costo alta | paginación de una tabla grande | filtra/agrega en el SELECT en lugar de paginar todo |
Próximos pasos: OData v4 / Power BI / Excel (alternativa disponible) · Errores y límites.