REST API reference

Get workspace, plan, limits and usage

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

List projects

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

Create a project

Creates a brand with competitors and prompts and starts its first collection run (set `startRun: false` to skip). Counts against the plan's brand and prompt limits.

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}'

Get a project

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

Update a project

Any of 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"]}'

Delete a project

Deletes the brand and all its data. Irreversible.

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

List competitors

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

Add competitors

One competitor, or several with `competitors: [...]`. Mentions in answers already collected are re-detected right away.

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"]}]}'

Get a competitor

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

Update a competitor

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"]}'

Remove a competitor

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

List prompts with visibility

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

Add prompts

Prompts already tracked (same text, any case) are skipped. Counts against the plan's active prompt limit.

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"]}'

Get a prompt

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

Update a prompt

Pause or resume (`active`), retag or edit. Resuming counts against the plan's active prompt limit.

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"]}'

Delete a prompt

Also deletes its answers.

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

List prompt tags with counts

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

List runs with progress

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

Get a run

Progress by engine.

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

Visibility overview

Brand and competitors with 95% CIs, change vs the previous period (with p-value) and per-engine visibility.

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

Visibility per run

One point per run with every brand's visibility, plus completed actions as annotations.

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

Visibility by engine

Brand and competitors on each engine, with significance of the change.

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

Visibility by prompt

Your visibility per prompt, the leading competitor and the gap.

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

List answers

Newest first, with brands mentioned (in order) and sources cited.

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

Get an answer

Full text, mentions with snippets and sentiment, citations, query fan-out, shopping products, ads and local results.

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

Top cited domains

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

Top cited pages

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

Source gaps

Third-party domains AI cites in answers that don't mention you, ranked by missed answers.

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

Untracked brands AI recommends

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

Track a discovered brand

Adds it as a competitor and re-detects its mentions in collected answers.

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"}'

Ignore a discovered brand

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"}'

List actions

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

Add an action

Your own action. Link prompts with `promptIds` to measure its impact on them.

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":[]}'

Regenerate the plan

Builds new actions from the last 30 days of answers. Never duplicates existing ones.

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

Get an action with its impact

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

Update an action

`status: "done"` stamps the completion date that starts the before/after window.

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"}'

Delete an action

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

Measured impact

Visibility before vs after completion on the targeted prompts, with a two-proportion z-test.

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

AI readiness audit (latest)

The latest audit of the brand's website as AI crawlers see it: robots.txt and firewall access, content rendered without JavaScript, noindex, canonicals, speed, titles, structured data, freshness, sitemap and llms.txt, per page, with a score and a draft llms.txt. null if none yet.

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

Run an AI readiness audit

Audits the website now (plain requests to the site, no AI cost) and refreshes the action plan: new problems become actions, fixed ones are closed.

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

Latest reputation analysis

Scores, strengths, weaknesses and inaccurate claims with quotes, tone per run and the most negative mentions.

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

Reputation score history

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

Re-analyse reputation

On the latest completed run. Limited per brand per day.

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

Turn a finding into an action

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}'

Signals summary

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

Query fan-out

The searches AI engines ran behind your prompts.

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

ChatGPT shopping products and merchants

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

Ads shown in answers

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

Brand entities recognised in answers

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

Reddit and YouTube sources

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

Local businesses in answers

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

Optimization opportunities

Prompts ranked by the gap to the leading competitor, with the page to optimize.

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

List drafts

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

Create a draft

Analyses the answers, the pages AI cites instead of yours and your page, then drafts the content. Takes 1–2 minutes. Limited per workspace per day.

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"}'

Get a draft

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

Add a draft to the action plan

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

AI referral traffic summary

Sessions and conversions by engine from one data source (snippet first, then analytics imports), the sources available, and the tracking snippet.

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

AI sessions per day

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

Top landing pages from AI

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

Import a GA4 CSV

Body is a GA4 export with Date, Session source and Sessions columns. Non-AI rows are skipped; re-importing the same dates replaces them.

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

AI crawler summary

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

Hits by crawler

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

Most crawled pages

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

List alerts

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

Mark an alert read

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

Mark all alerts read

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

List integrations

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

Add an integration

Email, Slack incoming webhook or https webhook. Webhooks return a signing `secret` once; every delivery carries `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"]}'

Get an integration

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

Update an integration

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

Delete an integration

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

Send a test notification

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

Download a CSV export

`file` is one of 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"

Get the client report link

Private link to the always-up-to-date white-label report.

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

Rotate the client report link

The previous link stops working immediately.

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

List BI datasets

Every flat table with its columns and ready-made JSON and CSV URLs.

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

Get a BI dataset

One row per day/brand/engine (or per prompt, source, page…) across every brand in the workspace. Point Power BI (Get data → Web) or Google Sheets (IMPORTDATA) at the CSV URL with a read-only key.

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

API index

Every endpoint with a one-line description.

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

OpenAPI 3.1 specification

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