Referencia de la API REST

Obtener espacio de trabajo, plan, límites y uso

curl "http://localhost:3000/api/v1/workspace" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Listar proyectos

curl "http://localhost:3000/api/v1/projects" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Crear un proyecto

Crea una marca con competidores y prompts e inicia su primera ejecución de recogida (usa `startRun: false` para omitirla). Cuenta para los límites de marcas y prompts del plan.

curl -X POST "http://localhost:3000/api/v1/projects" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Holafly","domain":"holafly.com","country":"US","language":"en","engines":["chatgpt","perplexity","gemini","google_aio","google_ai_mode"],"samples":3,"cadence":"weekly","competitors":[{"name":"Airalo","domain":"airalo.com"}],"prompts":["best eSIM for Japan","Airalo alternatives"],"startRun":true}'

Obtener un proyecto

curl "http://localhost:3000/api/v1/projects/$ID" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Actualizar un proyecto

Cualquiera de name, domain, description, country, language, engines, samples, cadence, aliases.

curl -X PATCH "http://localhost:3000/api/v1/projects/$ID" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cadence":"daily","engines":["chatgpt","perplexity"]}'

Eliminar un proyecto

Elimina la marca y todos sus datos. Irreversible.

curl -X DELETE "http://localhost:3000/api/v1/projects/$ID" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Listar competidores

curl "http://localhost:3000/api/v1/projects/$ID/competitors" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Añadir competidores

Un competidor, o varios con `competitors: [...]`. Las menciones en respuestas ya recogidas se vuelven a detectar al momento.

curl -X POST "http://localhost:3000/api/v1/projects/$ID/competitors" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"competitors":[{"name":"Airalo","domain":"airalo.com","aliases":["Airalo eSIM"]}]}'

Obtener un competidor

curl "http://localhost:3000/api/v1/projects/$ID/competitors/$COMPETITORID" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Actualizar un competidor

curl -X PATCH "http://localhost:3000/api/v1/projects/$ID/competitors/$COMPETITORID" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"airalo.com","aliases":["Airalo"]}'

Quitar un competidor

curl -X DELETE "http://localhost:3000/api/v1/projects/$ID/competitors/$COMPETITORID" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Listar prompts con su visibilidad

curl "http://localhost:3000/api/v1/projects/$ID/prompts" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Añadir prompts

Se omiten los prompts que ya se siguen (mismo texto, sin distinguir mayúsculas). Cuenta para el límite de prompts activos del plan.

curl -X POST "http://localhost:3000/api/v1/projects/$ID/prompts" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompts":["best eSIM for Europe"],"tags":["comparison"]}'

Obtener un prompt

curl "http://localhost:3000/api/v1/projects/$ID/prompts/$PROMPTID" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Actualizar un prompt

Pausar o reanudar (`active`), cambiar etiquetas o editar. Reanudar cuenta para el límite de prompts activos del plan.

curl -X PATCH "http://localhost:3000/api/v1/projects/$ID/prompts/$PROMPTID" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"active":false,"tags":["pricing"]}'

Eliminar un prompt

También elimina sus respuestas.

curl -X DELETE "http://localhost:3000/api/v1/projects/$ID/prompts/$PROMPTID" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Listar etiquetas de prompts con recuentos

curl "http://localhost:3000/api/v1/projects/$ID/tags" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Listar ejecuciones con su progreso

curl "http://localhost:3000/api/v1/projects/$ID/runs" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Obtener una ejecución

Progreso por motor de IA.

curl "http://localhost:3000/api/v1/projects/$ID/runs/$RUNID" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Resumen de visibilidad

Marca y competidores con IC del 95 %, cambio frente al periodo anterior (con valor p) y visibilidad por motor de IA.

curl "http://localhost:3000/api/v1/projects/$ID/metrics" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Visibilidad por ejecución

Un punto por ejecución con la visibilidad de cada marca, más las acciones completadas como anotaciones.

curl "http://localhost:3000/api/v1/projects/$ID/metrics/timeseries" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Visibilidad por motor de IA

Marca y competidores en cada motor de IA, con la significación del cambio.

curl "http://localhost:3000/api/v1/projects/$ID/metrics/engines" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Visibilidad por prompt

Tu visibilidad por prompt, el competidor que lidera y la diferencia.

curl "http://localhost:3000/api/v1/projects/$ID/metrics/prompts" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Listar respuestas

Las más recientes primero, con las marcas mencionadas (en orden) y las fuentes citadas.

curl "http://localhost:3000/api/v1/projects/$ID/answers" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Obtener una respuesta

Texto completo, menciones con fragmentos y sentimiento, citas, query fan-out, productos de shopping, anuncios y resultados locales.

curl "http://localhost:3000/api/v1/projects/$ID/answers/$ANSWERID" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Dominios más citados

curl "http://localhost:3000/api/v1/projects/$ID/citations" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Páginas más citadas

curl "http://localhost:3000/api/v1/projects/$ID/citations/urls" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Fuentes donde no apareces

Dominios de terceros que la IA cita en respuestas que no te mencionan, ordenados por respuestas perdidas.

curl "http://localhost:3000/api/v1/projects/$ID/citations/gaps" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Marcas no seguidas que recomienda la IA

curl "http://localhost:3000/api/v1/projects/$ID/discovered-brands" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Seguir una marca descubierta

La añade como competidor y vuelve a detectar sus menciones en las respuestas recogidas.

curl -X POST "http://localhost:3000/api/v1/projects/$ID/discovered-brands/track" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Saily"}'

Ignorar una marca descubierta

curl -X POST "http://localhost:3000/api/v1/projects/$ID/discovered-brands/ignore" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Google Fi"}'

Listar acciones

curl "http://localhost:3000/api/v1/projects/$ID/actions" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Añadir una acción

Una acción tuya. Vincula prompts con `promptIds` para medir su impacto en ellos.

curl -X POST "http://localhost:3000/api/v1/projects/$ID/actions" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind":"content","title":"Publish Japan eSIM comparison","detail":"Table with price per GB and carriers.","priority":1,"promptIds":[]}'

Regenerar el plan

Crea acciones nuevas a partir de las respuestas de los últimos 30 días. Nunca duplica las existentes.

curl -X POST "http://localhost:3000/api/v1/projects/$ID/actions/generate" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Obtener una acción con su impacto

curl "http://localhost:3000/api/v1/projects/$ID/actions/$ACTIONID" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Actualizar una acción

`status: "done"` registra la fecha de finalización con la que empieza la ventana antes/después.

curl -X PATCH "http://localhost:3000/api/v1/projects/$ID/actions/$ACTIONID" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"done"}'

Eliminar una acción

curl -X DELETE "http://localhost:3000/api/v1/projects/$ID/actions/$ACTIONID" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Impacto medido

Visibilidad antes frente a después de completarse en los prompts objetivo, con una prueba z de dos proporciones.

curl "http://localhost:3000/api/v1/projects/$ID/actions/$ACTIONID/impact" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Auditoría de preparación para IA (la más reciente)

La auditoría más reciente de la web de la marca tal como la ven los rastreadores de IA: acceso por robots.txt y firewall, contenido renderizado sin JavaScript, noindex, canonicals, velocidad, títulos, datos estructurados, actualidad, sitemap y llms.txt, por página, con una puntuación y un borrador de llms.txt. null si aún no hay ninguna.

curl "http://localhost:3000/api/v1/projects/$ID/audit" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Ejecutar una auditoría de preparación para IA

Audita la web ahora (peticiones normales al sitio, sin coste de IA) y actualiza el plan de acción: los problemas nuevos se convierten en acciones y los resueltos se cierran.

curl -X POST "http://localhost:3000/api/v1/projects/$ID/audit" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Último análisis de reputación

Puntuaciones, puntos fuertes, puntos débiles y afirmaciones inexactas con citas textuales, tono por ejecución y las menciones más negativas.

curl "http://localhost:3000/api/v1/projects/$ID/reputation" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Historial de la puntuación de reputación

curl "http://localhost:3000/api/v1/projects/$ID/reputation/history" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Volver a analizar la reputación

Sobre la última ejecución completada. Limitado por marca y día.

curl -X POST "http://localhost:3000/api/v1/projects/$ID/reputation/regenerate" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Convertir un hallazgo en una acción

curl -X POST "http://localhost:3000/api/v1/projects/$ID/reputation/actions" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind":"inaccuracy","index":0}'

Resumen de señales

curl "http://localhost:3000/api/v1/projects/$ID/signals" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Query fan-out

Las búsquedas que hicieron los motores de IA detrás de tus prompts.

curl "http://localhost:3000/api/v1/projects/$ID/signals/fan-out" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Productos y comercios de ChatGPT Shopping

curl "http://localhost:3000/api/v1/projects/$ID/signals/shopping" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Anuncios mostrados en las respuestas

curl "http://localhost:3000/api/v1/projects/$ID/signals/ads" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Entidades de marca reconocidas en las respuestas

curl "http://localhost:3000/api/v1/projects/$ID/signals/entities" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Fuentes de Reddit y YouTube

curl "http://localhost:3000/api/v1/projects/$ID/signals/community" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Negocios locales en las respuestas

curl "http://localhost:3000/api/v1/projects/$ID/signals/local" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Oportunidades de optimización

Prompts ordenados por la diferencia con el competidor que lidera, con la página que optimizar.

curl "http://localhost:3000/api/v1/projects/$ID/geo/opportunities" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Listar borradores

curl "http://localhost:3000/api/v1/projects/$ID/geo/drafts" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Crear un borrador

Analiza las respuestas, las páginas que cita la IA en lugar de la tuya y tu página, y después redacta el contenido. Tarda 1–2 minutos. Limitado por espacio de trabajo y día.

curl -X POST "http://localhost:3000/api/v1/projects/$ID/geo/drafts" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"promptId":"…","targetUrl":"https://holafly.com/esim-japan"}'

Obtener un borrador

curl "http://localhost:3000/api/v1/projects/$ID/geo/drafts/$DRAFTID" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Añadir un borrador al plan de acción

curl -X POST "http://localhost:3000/api/v1/projects/$ID/geo/drafts/$DRAFTID/action" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Resumen del tráfico de referencia desde IA

Sesiones y conversiones por motor de IA de una sola fuente de datos (primero el snippet, después las importaciones de analítica), las fuentes disponibles y el snippet de seguimiento.

curl "http://localhost:3000/api/v1/projects/$ID/traffic" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Sesiones desde IA por día

curl "http://localhost:3000/api/v1/projects/$ID/traffic/daily" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Principales páginas de destino desde IA

curl "http://localhost:3000/api/v1/projects/$ID/traffic/pages" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Importar un CSV de GA4

El cuerpo es una exportación de GA4 con las columnas Date, Session source y Sessions. Se omiten las filas que no son de IA; volver a importar las mismas fechas las sustituye.

curl -X POST "http://localhost:3000/api/v1/projects/$ID/traffic/ga4" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY" \
  -H "Content-Type: text/csv" \
  --data-binary @export.csv

Resumen de rastreadores de IA

curl "http://localhost:3000/api/v1/projects/$ID/bots" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Visitas por rastreador

curl "http://localhost:3000/api/v1/projects/$ID/bots/by-bot" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Páginas más rastreadas

curl "http://localhost:3000/api/v1/projects/$ID/bots/pages" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Listar alertas

curl "http://localhost:3000/api/v1/alerts" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Marcar una alerta como leída

curl -X POST "http://localhost:3000/api/v1/alerts/$ALERTID/read" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Marcar todas las alertas como leídas

curl -X POST "http://localhost:3000/api/v1/alerts/read-all" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Listar integraciones

curl "http://localhost:3000/api/v1/integrations" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Añadir una integración

Email, incoming webhook de Slack o webhook https. Los webhooks devuelven un `secret` de firma una sola vez; cada envío lleva `X-Huginnova-Signature: sha256=<hmac>`.

curl -X POST "http://localhost:3000/api/v1/integrations" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind":"webhook","target":"https://hooks.zapier.com/hooks/catch/…","events":["alert.created","run.completed"]}'

Obtener una integración

curl "http://localhost:3000/api/v1/integrations/$INTEGRATIONID" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Actualizar una integración

curl -X PATCH "http://localhost:3000/api/v1/integrations/$INTEGRATIONID" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled":false}'

Eliminar una integración

curl -X DELETE "http://localhost:3000/api/v1/integrations/$INTEGRATIONID" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Enviar una notificación de prueba

curl -X POST "http://localhost:3000/api/v1/integrations/$INTEGRATIONID/test" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Descargar una exportación CSV

`file` es uno de answers.csv, prompts.csv, citations.csv, metrics.csv.

curl "http://localhost:3000/api/v1/projects/$ID/export/answers.csv" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Obtener el enlace del informe para clientes

Enlace privado al informe de marca blanca siempre actualizado.

curl "http://localhost:3000/api/v1/projects/$ID/share-link" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Cambiar el enlace del informe para clientes

El enlace anterior deja de funcionar al momento.

curl -X POST "http://localhost:3000/api/v1/projects/$ID/share-link" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Listar conjuntos de datos de BI

Cada tabla plana con sus columnas y URL de JSON y CSV listas para usar.

curl "http://localhost:3000/api/v1/bi" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Obtener un conjunto de datos de BI

Una fila por día/marca/motor de IA (o por prompt, fuente, página…) de todas las marcas del espacio de trabajo. Apunta Power BI (Obtener datos → Web) o Google Sheets (IMPORTDATA) a la URL del CSV con una clave de solo lectura.

curl "http://localhost:3000/api/v1/bi/visibility" \
  -H "Authorization: Bearer $HUGINNOVA_API_KEY"

Índice de la API

Todos los endpoints con una descripción de una línea.

curl "http://localhost:3000/api/v1"

Especificación OpenAPI 3.1

curl "http://localhost:3000/api/v1/openapi.json"