v1 — establePlan Professional

Intelrift
API pública

Una API REST pequeña, opinada y de solo lectura que te da acceso programático a la misma señal geopolítica que alimenta el dashboard de Intelrift: clusters diarios de eventos, briefings editoriales y los artículos que los sustentan. Úsala desde tu data warehouse, notebooks de investigación, dashboards internos o sistemas de trading.

Auth BearerClaves seguras por usuario

Sin créditosLlamadas gratuitas

30/min · 500/díaLímites en base de datos

Solo lecturaSegura por diseño

Inicio rápido

1.Asegúrate de que tu suscripción está en el plan Professional. El acceso a la API está incluido a partir de ese nivel.
2.Ve a Ajustes → API, pulsa Nueva clave, dale un nombre reconocible y copia el secreto. El valor en texto plano solo se muestra una vez.
3.Envía tu primera petición — sin SDK ni setup adicional:

curl

curl https://intelrift.com/api/v1/health \
  -H "Authorization: Bearer $INTELRIFT_API_KEY"

Cada petición debe llevar tu clave en la cabecera Authorization. No hace falta nada más.

Autenticación

Todos los endpoints están autenticados. Envía tu API key usando una de estas cabeceras:

Authorization: Bearer <key> (recomendado)

X-API-Key: <key>

Las claves siguen el formato irf_live_<40 caracteres hexadecimales>. Los primeros dieciséis caracteres forman un prefijo no secreto que se muestra en el panel para que puedas identificar la clave. El valor completo no vuelve a mostrarse después de crearla.

Cada usuario puede mantener hasta diez claves activas a la vez. Revocar una clave desde Ajustes → API la invalida al instante — cualquier petición hecha con una clave revocada responde 401 invalid_api_key. Las claves heredan el plan del propietario: si la suscripción baja por debajo de Professional, todas las claves dejan de funcionar hasta restaurar el plan.

Mantén las claves en secreto

Trata las API keys como contraseñas. Nunca las commitees al repositorio, nunca las embedas en JavaScript del navegador, y nunca las compartas con terceros. Si sospechas que una clave ha filtrado, revócala al instante desde Ajustes → API y crea una nueva.

URL base y versionado

La API se sirve por HTTPS desde una única URL base:

https://intelrift.com/api/v1

El segmento /v1 es la versión. Dentro de una versión mayor solo hacemos cambios aditivos y compatibles hacia atrás: campos nuevos, parámetros opcionales nuevos, endpoints nuevos. Los cambios disruptivos se publican bajo una nueva ruta de versión (por ejemplo /v2) y la anterior se mantiene soportada al menos doce meses después de que la sucesora llegue a estable.

Los clientes deben ser permisivos al leer: ignora campos desconocidos en las respuestas y no dependas del orden de las claves en los objetos JSON.

Formato de petición

Todos los endpoints de v1 solo aceptan peticiones GET. Los parámetros se pasan en la query string. No hay cuerpos de petición ni negociación de content-type — las respuestas son siempre application/json; charset=utf-8.

Convenciones generales

Los parámetros booleanos aceptan true / false (insensible a mayúsculas).
Las listas separadas por comas se usan para filtros de múltiples valores (p. ej. country=us,de,fr).
Los parámetros desconocidos se ignoran en silencio — nunca son fatales.
Todas las marcas de tiempo en respuestas son ISO-8601 UTC (por ejemplo 2026-04-05T18:44:10.000Z).

Formato de respuesta

Las respuestas correctas devuelven un envoltorio que siempre contiene un campo data con el payload, más metadatos ligeros. Los nombres de campo usan snake_case.

Campos comunes del envoltorio

`data`	object \| array	El payload real: un recurso único o un array de recursos.
`count`	number	Para endpoints de lista — número de elementos en la página actual.
`limit`	number	El tamaño de página efectivo (tras aplicar el límite).
`offset`	number	El offset de paginación efectivo.
`date`	string	Día de calendario representado en la respuesta (en endpoints con scope diario).
`tz`	string	Zona horaria usada para calcular el día (IANA).
`range`	object	Timestamps UTC `start` / `end` del intervalo de 24 horas.

Las respuestas de error nunca contienen un campo data — ver sección 09.

Scope del día y zonas horarias

Varios endpoints de lista (en particular GET /v1/clusters) devuelven los elementos de un único día de calendario. La frontera del día se interpreta en la zona horaria que tú elijas, para que "hoy" coincida con el que ven tus usuarios.

El scope se controla con dos parámetros de query:

date — un día de calendario ISO en formato YYYY-MM-DD. Por defecto, hoy en la zona horaria indicada.
tz — un nombre de zona horaria IANA, como Europe/Madrid, America/New_York, Asia/Tokyo. Por defecto UTC. Los nombres inválidos se ignoran y se cae a UTC.

El servidor resuelve el par (date, tz) a un intervalo UTC semiabierto [start, end) de exactamente 24 horas y devuelve todos los elementos actualizados dentro de ese intervalo. La respuesta devuelve de vuelta date, tz y el range UTC resuelto, para que el cliente no tenga que re-implementar la conversión.

Paginación

Los endpoints de lista usan paginación por offset con dos parámetros:

limit — número de elementos por página. Rango válido: 1 a 100. Valor por defecto: 50 (30 para briefings).
offset — cuántos elementos saltar. Máximo: 10 000.

Itera hasta que el count devuelto sea menor que tu limit. El servidor nunca devuelve más elementos de los solicitados.

Límites de uso

Los límites se aplican por API key y se persisten en base de datos, así que sobreviven a reinicios del servidor y no se pueden saltar distribuyendo llamadas entre instancias.

Por minuto

peticiones / minuto / clave

Por día

500

peticiones / día / clave

Cabeceras de respuesta

Cada respuesta (incluyendo 429) incluye las siguientes cabeceras para que los clientes puedan controlar su presupuesto:

http

X-RateLimit-Limit-Minute: 30
X-RateLimit-Remaining-Minute: 27
X-RateLimit-Reset-Minute:  1743864120
X-RateLimit-Limit-Day:     500
X-RateLimit-Remaining-Day: 463
X-RateLimit-Reset-Day:     1743897600

Los valores de X-RateLimit-Reset-* son timestamps Unix (en segundos) que indican cuándo se reinicia cada ventana. En 429 Too Many Requests también se añade una cabecera Retry-After (en segundos) — espera al menos ese tiempo antes de reintentar.

No consume créditos

Las peticiones a la API no descuentan créditos de tu asignación mensual. Los créditos siguen reservados para acciones con IA dentro de la aplicación (Spectre, generación de briefings, generación de estrategias). La API es un acceso plano de solo lectura.

Errores

Los errores usan un único envoltorio estable. code es legible por máquina y forma parte del contrato; message es legible por humanos y puede cambiar.

json

{
  "error": {
    "code": "rate_limit_minute",
    "message": "Per-minute rate limit of 30 requests exceeded."
  }
}

Referencia de códigos de error posibles:

Status	Código	Cuándo
401	missing_api_key	No se proporcionó ninguna API key en la cabecera Authorization o X-API-Key.
401	invalid_api_key	La clave es desconocida, está revocada o ha expirado.
403	insufficient_scope	La clave no tiene el scope requerido por el endpoint.
403	api_feature_disabled	El propietario de la clave ya no está en el plan Professional.
404	not_found	El recurso solicitado no existe.
429	rate_limit_minute	Se superó el límite por minuto. Revisa Retry-After.
429	rate_limit_daily	Se superó el límite diario. Reintenta mañana.
500	internal_error	Error inesperado en el servidor. Reintenta con backoff exponencial.

Endpoints

URL base:https://intelrift.com/api/v1

GET/api/v1/health

Health check

Comprobación de sanidad. Devuelve la versión de la API, el id de tu clave, los scopes concedidos y el estado actual del rate limit. Útil para verificar que una clave está activa y ver cuánto presupuesto te queda.

Ejemplo de petición

curl

curl https://intelrift.com/api/v1/health \
  -H "Authorization: Bearer $INTELRIFT_API_KEY"

GET/api/v1/clusters

Listar clusters de un día

Devuelve los clusters de eventos actualizados dentro de un día de calendario. El día se interpreta en la zona horaria indicada — por defecto UTC. Los resultados se ordenan por severidad (descendente) y después por fecha de actualización.

Parámetros de query

date

YYYY-MM-DD

Día de calendario a devolver. Por defecto, hoy en la zona horaria indicada.

tz

IANA

Zona horaria para interpretar date. Por defecto UTC.

country

csv

Códigos de país separados por comas. Filtra clusters cuya lista de países se solape con el filtro.

limit

1..100

Tamaño de página. Por defecto 50.

offset

int

Offset de paginación. Máximo 10 000.

Ejemplo de petición

curl

curl "https://intelrift.com/api/v1/clusters?date=2026-04-05&tz=Europe/Madrid&limit=50" \
  -H "Authorization: Bearer $INTELRIFT_API_KEY"

Ejemplo de respuesta

json

{
  "date": "2026-04-05",
  "tz": "Europe/Madrid",
  "range": {
    "start": "2026-04-04T22:00:00.000Z",
    "end":   "2026-04-05T22:00:00.000Z"
  },
  "count": 12,
  "limit": 50,
  "offset": 0,
  "data": [
    {
      "id": "7a3f0e1b-2c84-4a6d-b99f-8d1f2e3a4b5c",
      "title": "NATO summit concludes with new eastern-flank commitments",
      "summary": "Allies agreed to ...",
      "category": "diplomacy",
      "severity": 78,
      "confidence": 85,
      "article_count": 14,
      "source_count": 9,
      "countries": ["us", "pl", "de", "fr"],
      "primary_country": "pl",
      "region": "europe",
      "event_type": "diplomatic",
      "threat_level": "medium",
      "trend": "rising",
      "urgency": "high",
      "topics": ["diplomacy", "defense"],
      "keywords": ["nato", "summit"],
      "tags": [],
      "entities": { "people": [], "organizations": [] },
      "window_start": "2026-04-05T06:00:00.000Z",
      "window_end":   "2026-04-05T18:00:00.000Z",
      "created_at":   "2026-04-05T06:12:44.000Z",
      "updated_at":   "2026-04-05T18:44:10.000Z"
    }
  ]
}

GET/api/v1/clusters/{id}

Obtener un cluster

Recupera el detalle completo de un cluster por su UUID — summary, entidades, severidad, threat level, lista de países, topics y metadatos.

Ejemplo de petición

curl

curl https://intelrift.com/api/v1/clusters/7a3f0e1b-2c84-4a6d-b99f-8d1f2e3a4b5c \
  -H "Authorization: Bearer $INTELRIFT_API_KEY"

GET/api/v1/clusters/{id}/articles

Listar artículos de un cluster

Devuelve los artículos subyacentes que alimentan un cluster. Útil para auditar fuentes o construir tus propias agregaciones sobre el clustering de Intelrift.

Parámetros de query

limit

1..100

Tamaño de página. Por defecto 50.

offset

int

Offset de paginación. Máximo 10 000.

Ejemplo de petición

curl

curl "https://intelrift.com/api/v1/clusters/7a3f0e1b-.../articles?limit=20" \
  -H "Authorization: Bearer $INTELRIFT_API_KEY"

GET/api/v1/briefings

Listar briefings recientes

Devuelve los briefings públicos más recientes, ordenados por fecha descendente.

Parámetros de query

limit

1..100

Número máximo de briefings a devolver. Por defecto 30.

Ejemplo de petición

curl

curl "https://intelrift.com/api/v1/briefings?limit=7" \
  -H "Authorization: Bearer $INTELRIFT_API_KEY"

GET/api/v1/briefings/{id}

Obtener un briefing

Recupera un briefing único. El segmento {id} acepta tres formas:

Un UUID — búsqueda directa por id del briefing.
La cadena literal latest — devuelve el briefing público más reciente.
Una fecha de calendario en formato YYYY-MM-DD — devuelve el briefing de ese día. Respeta el parámetro tz.

Parámetros de query

tz

IANA

Zona horaria para la búsqueda por fecha. Ignorado cuando {id} es un UUID o latest.

Ejemplo de petición

curl

curl https://intelrift.com/api/v1/briefings/latest \
  -H "Authorization: Bearer $INTELRIFT_API_KEY"

Esquemas de objetos

Los tres tipos principales de recurso expuestos por la API. Todos los campos están documentados; los clientes deben ignorar los desconocidos para mantenerse compatibles hacia adelante.

Cluster

Un grupo de artículos que describen el mismo evento del mundo real, con metadatos editoriales añadidos por el pipeline de Intelrift.

Campo	Tipo	Descripción
`id`	uuid	Identificador único del cluster.
`title`	string	Título canónico elegido por el editor.
`summary`	string \| null	Resumen narrativo del evento.
`category`	string \| null	Categoría principal (diplomacy, conflict, economy…).
`severity`	integer (0–100)	Puntuación de severidad del evento.
`confidence`	integer (0–100)	Confianza editorial en el cluster.
`article_count`	integer	Número de artículos subyacentes.
`source_count`	integer	Número de fuentes distintas.
`countries`	string[]	Códigos ISO-3166-1 alpha-2 en minúsculas.
`primary_country`	string \| null	País principal del evento.
`region`	string \| null	Región geográfica.
`event_type`	string \| null	Tipo de evento normalizado.
`threat_level`	string \| null	low / medium / high / critical
`trend`	string \| null	rising / stable / falling
`urgency`	string \| null	low / medium / high / critical
`topics`	string[]	Topics derivados automáticamente.
`keywords`	string[]	Palabras clave extraídas.
`tags`	string[]	Tags editoriales.
`entities`	object	Entidades nombradas (personas, organizaciones, localizaciones).
`window_start`	ISO-8601	Inicio de la ventana temporal cubierta.
`window_end`	ISO-8601	Final de la ventana temporal cubierta.
`created_at`	ISO-8601	Fecha de creación del cluster.
`updated_at`	ISO-8601	Última actualización del cluster.

Briefing

Un resumen editorial de los principales clusters de un día específico.

Campo	Tipo	Descripción
`id`	uuid	Identificador del briefing.
`date`	YYYY-MM-DD	Día de calendario del briefing.
`items`	object[]	Elementos del briefing (referencias a clusters con comentario editorial).
`generated_at`	ISO-8601	Cuándo se generó el briefing.
`created_at`	ISO-8601	Cuándo se persistió el briefing.

Article

Un artículo individual ingerido desde una fuente y, opcionalmente, asociado a un cluster.

Campo	Tipo	Descripción
`id`	uuid	Identificador del artículo.
`title`	string	Título del artículo tal como lo publicó la fuente.
`url`	string	URL original.
`canonical_url`	string	URL canónica tras normalización.
`domain`	string	Dominio de la fuente.
`language`	string	ISO-639-1 (en, es, fr, …)
`countries`	string[]	Códigos de país asociados.
`topics`	string[]	Topics del artículo.
`snippet`	string \| null	Extracto corto del contenido.
`computed_score`	integer \| null	Puntuación computada del artículo.
`published_at`	ISO-8601 \| null	Fecha de publicación original.
`fetched_at`	ISO-8601	Cuándo Intelrift lo ingirió.

Ejemplos de código

Snippets canónicos en los lenguajes que más usan los clientes de Intelrift. Sustituye $INTELRIFT_API_KEY por tu propia clave — nunca la hardcodees.

curl

curl "https://intelrift.com/api/v1/clusters?date=2026-04-05&tz=Europe/Madrid&limit=50" \
  -H "Authorization: Bearer $INTELRIFT_API_KEY"

# Follow up with a single cluster
curl https://intelrift.com/api/v1/clusters/7a3f0e1b-2c84-4a6d-b99f-8d1f2e3a4b5c \
  -H "Authorization: Bearer $INTELRIFT_API_KEY"

Buenas prácticas de seguridad

Guarda las API keys en variables de entorno o en un gestor de secretos — nunca en archivos fuente.

Usa una clave distinta por entorno (producción, staging, notebook) para poder rotarlas o revocarlas de forma independiente.

Rota las claves con regularidad, e inmediatamente cuando un miembro del equipo con acceso se va.

Nunca llames a la API directamente desde un navegador o cliente móvil — siempre pasa por tu backend para que la clave no llegue al user agent.

Vigila la columna last_used_at en Ajustes → API y revoca cualquier clave que parezca inactiva o sospechosa.

Considera una clave revocada como irrecuperable. Crea una nueva y actualiza tus despliegues.

Changelog

v1.02026-04

Lanzamiento público inicial de la API de Intelrift.
Endpoints: /health, /clusters, /clusters/{id}, /clusters/{id}/articles, /briefings, /briefings/{id}.
Límites: 30 peticiones por minuto y 500 por día por clave.
Autenticación Bearer / X-API-Key con gestión de claves por usuario en Ajustes → API.

Soporte

¿Encontraste un bug, necesitas un límite más alto, o quieres una feature que todavía no exponemos? La forma más rápida de contactar es usando el botón de ayuda dentro de la app, o respondiendo al email de bienvenida que recibiste al suscribirte. Incluye el prefijo de tu clave (nunca el secreto) para que podamos correlacionar la petición con tu cuenta.

¿Listo para construir?

Genera tu primera API key e integra la señal geopolítica de Intelrift en tu stack en minutos.

IntelriftAPI pública

Inicio rápido

Autenticación

URL base y versionado

Formato de petición

Formato de respuesta

Scope del día y zonas horarias

Paginación

Límites de uso

Errores

Endpoints

Health check

Listar clusters de un día

Obtener un cluster

Listar artículos de un cluster

Listar briefings recientes

Obtener un briefing

Esquemas de objetos

Ejemplos de código

Buenas prácticas de seguridad

Changelog

Soporte

¿Listo para construir?

Intelrift
API pública