API de datos — consultas guardadas

Versión 2026-10-01 · GET · Autenticación Bearer con API key bipk_…

Lee los resultados de tus consultas guardadas desde cualquier aplicación externa (una hoja de cálculo, un script, otra plataforma de BI) por REST. Cada respuesta trae las filas y las columnas de la consulta.

1 · Lo que necesitas

Una API key. En la app, ve a Conectar IA › Conexiones activas › Crear API key. Cada key vale para un solo espacio, actúa con los mismos permisos que tu usuario en ese espacio y vence (30, 90 o 365 días). Se muestra una sola vez: guárdala en un gestor de secretos, nunca en documentos ni en el código.
El id de la consulta. En Consultas, abre cualquier consulta y haz clic en el botón </> para copiar su URL de API.

2 · La petición

Campo	Valor
Método	`GET`
URL	`https://{subdominio}.frepi.ai/api/data/v1/query/{query_id}` (el host de tu espacio, p. ej. `app.frepi.ai`)
Header	`Authorization: Bearer bipk_tu-key-aqui`

La key va solo en el header, nunca en la URL ni como parámetro: las URLs quedan en los logs de proxies.

curl

curl -H "Authorization: Bearer bipk_tu-key-aqui" \
  "https://{subdominio}.frepi.ai/api/data/v1/query/42"

JavaScript

const res = await fetch(
  'https://{subdominio}.frepi.ai/api/data/v1/query/42',
  { headers: { 'Authorization': 'Bearer bipk_tu-key-aqui' } }
);
const { data, columns } = await res.json();

3 · Parámetros opcionales

Parámetro	Por defecto	Descripción
`format`	`json`	`json` o `csv`.
`fresh`	`false`	Fuerza volver a ejecutar la consulta (sin caché).
`limit`	`1000`	Máximo de filas (tope 1000).

4 · Respuesta JSON

{
  "query_id": 42,
  "query_name": "Ventas mensuales",
  "data": [...],
  "columns": [{"name": "fecha", "type": "date"}],
  "row_count": 150,
  "cached": true,
  "executed_at": "2026-04-14T10:30:00Z",
  "cache_ttl_seconds": 300
}

5 · Límites

60 peticiones por minuto por API key (por defecto). Al pasarlo recibes 429 con retry_after_seconds y el header Retry-After.
1.000 filas como máximo por respuesta.
Los resultados se sirven desde caché (5 minutos por defecto) salvo con fresh=true.
Solo consultas del espacio de la key: una consulta de otro espacio responde 404.

Errores

Código	Qué significa
`401`	Key ausente, inválida, revocada o vencida.
`404`	La consulta no existe en el espacio de la key, o no tiene SQL ni resultados guardados.
`429`	Superaste el límite de peticiones; reintenta después de `Retry-After` segundos.

¿Quieres que un asistente de IA (Claude, ChatGPT, Cursor…) use tus datos? No necesitas esta API: conéctalo desde Conectar IA en la app, con tu cuenta Frepi.