REST API endpoint reference

Sixteen endpoints under https://api.attensira.com/v1. Every one takes Authorization: Bearer atn_live_<32 hex>; none takes a workspace id, because the key names the workspace. Each endpoint below names the MCP tool it is the twin of. The two surfaces carry the same capabilities on purpose.

Before you start: what costs money and what destroys data

Endpoint	Effect	Why
`POST /v1/prompts`	Spends credits	Each new prompt is read across your tracked platforms from the next run onward
`POST /v1/automations/{id}/runs`	Spends credits	Triggers an automation immediately instead of waiting for its schedule
`POST /v1/ask`	Spends credits	Runs the agent on an agent model
`DELETE /v1/prompts/{prompt}`	Destructive	Stops tracking a prompt; its history goes with it
`DELETE /v1/automations/{id}`	Destructive	Removes the automation, its schedule and its run history

Nothing else on this page changes state or produces a bill.

Status codes

A POST that creates a durable resource answers 201. POST /v1/ask and POST /v1/automations/{id}/runs answer 200, because what they return is a handle to work in progress rather than a resource at a new URL. Everything else answers 200. Failures are the error envelope.

Find and measure

GET /v1/search

Read-only. No credits. MCP tool: search.

Full-text search across answers, prompts, pages, sessions and automations in one pass. Use it to locate something by wording when you do not have an id.

Parameter	In	Type	Default	Notes
`q`	query	string	—	Required. Matched against titles, prompt text, page URLs and answer bodies
`limit`	query	integer	20	Maximum 50
`offset`	query	integer	0	For paging

Shell

curl -G https://api.attensira.com/v1/search \
  --data-urlencode "q=pricing" --data-urlencode "limit=2" \
  -H "Authorization: Bearer atn_live_<your key>"

Response

{
  "total": 37,
  "has_more": true,
  "hits": [
    {
      "type": "prompt",
      "id": "prm_8f21",
      "title": "best crm for small teams pricing",
      "snippet": "…compared against three competitors on price…",
      "when": "2026-08-30T09:12:00Z"
    },
    { "type": "page", "id": "pg_44a1", "title": "acme.com/pricing", "snippet": "…", "when": null }
  ]
}

type tells you which endpoint can fetch the hit in full: prompt → GET /v1/prompts/{prompt}, page → GET /v1/pages, session → GET /v1/sessions/{id}, automation → GET /v1/automations/{id}.

Every string on a hit is capped at 400 characters, not just snippet. A complete model answer can never come back through search, no matter which fields a hit carries. Fetch the session for the full text.

Page on has_more. total is how many items matched up to the server’s fetch ceiling — a floor, not a grand total.

GET /v1/analytics/

Read-only. No credits. MCP tool: get_analytics.

The main measurement endpoint. One call returns an aggregated, ranked slice of your tracking data for a window.

Parameter	In	Type	Default	Notes
`area`	path	enum	—	Required. See the table below
`days`	query	integer	30	1–365
`order`	query	enum	`worst_first`	Or `best_first`
`limit`	query	integer	20	Maximum 100
`filter`	query	string	—	Free-text filter on row labels — a topic name, a platform, a URL fragment

`area`	One row per	Answers
`visibility`	the workspace	Share of voice per platform — the orienting call
`prompt`	tracked prompt	Which prompts you win and lose
`page`	page of yours	Which of your pages get cited
`source`	external domain	Which domains the models cite in your category
`competitor`	rival	Workspace-wide share of voice per competitor
`topic`	prompt topic	Per-topic rollup
`platform`	AI answer surface	Per-platform rollup
`bot`	AI system that fetched your site	Reads, pages reached, purpose mix, when it last came

Shell

curl -G https://api.attensira.com/v1/analytics/prompt \
  --data-urlencode "days=30" --data-urlencode "order=worst_first" --data-urlencode "limit=1" \
  -H "Authorization: Bearer atn_live_<your key>"

Response

{
  "area": "prompt",
  "days": 30,
  "rows": [
    {
      "id": "prm_8f21",
      "label": "best crm for small teams",
      "visibility": { "value": 0.12, "n": 25 },
      "mention": { "value": 0.12, "n": 25 },
      "citation": { "value": 0.04, "n": 25 },
      "position": null,
      "delta": { "value": -0.05, "real": true },
      "platforms": {
        "chatgpt": { "tracked": true, "readable": true, "rate": { "value": 0.2, "n": 15 },
                     "delta": { "value": -0.03, "real": false } },
        "claude":  { "tracked": false, "readable": false }
      }
    }
  ]
}

area=bot rows carry visits, pages, purpose_mix, last_seen (null when it never came) and agents instead of the rate fields. A model can only cite a page it has fetched, so check bot before concluding a page underperforms on content — but a row here counts only what our middleware recorded, so absence is no proof nothing came.

competitor and source are workspace-wide aggregates. For the rivals and cited sources of one prompt, GET /v1/prompts/{prompt} already returns both — no second call needed.

GET /v1/prompts/

Read-only. No credits. MCP tool: get_prompt.

Everything recorded for one prompt: its topic and country, its per-platform rates and delta, the competitors seen in its answers, and the sources those answers cited.

Parameter	In	Type	Default	Notes
`prompt`	path	string	—	Required. A prompt id, or the prompt’s exact text, percent-encoded
`days`	query	integer	30	1–365

Shell

curl https://api.attensira.com/v1/prompts/prm_8f21?days=30 \
  -H "Authorization: Bearer atn_live_<your key>"

Response

{
  "id": "prm_8f21",
  "text": "best crm for small teams",
  "topic": "buying intent",
  "country": "US",
  "visibility": { "value": 0.12, "n": 25 },
  "delta": { "value": -0.05, "real": true },
  "platforms": {
    "chatgpt": { "tracked": true, "readable": true, "rate": { "value": 0.2, "n": 15 },
                 "delta": { "value": -0.03, "real": false } }
  },
  "competitors": [{ "name": "rival.com", "rate": { "value": 0.6, "n": 25 } }],
  "sources": [{ "url": "https://g2.com/categories/crm", "rate": { "value": 0.44, "n": 25 } }]
}

Passing exact text saves a search round-trip when you already know the wording; inexact text will not match. Percent-encode it — a prompt containing / or ? will otherwise change the route.

GET /v1/pages

Read-only. No credits. MCP tool: get_page.

Everything recorded for one URL on your site: its citation rate overall and per platform, its delta, and the prompts whose answers cited it.

Parameter	In	Type	Default	Notes
`url`	query	string	—	Required. Absolute URL, exactly as it appears on the site
`days`	query	integer	30	1–365

Shell

curl -G https://api.attensira.com/v1/pages \
  --data-urlencode "url=https://acme.com/pricing" \
  -H "Authorization: Bearer atn_live_<your key>"

Response

{
  "url": "https://acme.com/pricing",
  "title": "Pricing — Acme",
  "citation": { "value": 0.04, "n": 120 },
  "delta": { "value": null, "real": false },
  "platforms": { "perplexity": { "tracked": true, "readable": true, "rate": { "value": 0.09, "n": 60 } } },
  "prompts": [{ "id": "prm_8f21", "text": "best crm for small teams", "rate": { "value": 0.08, "n": 25 } }]
}

If this comes back empty, check GET /v1/analytics/bot before rewriting the page — a model cannot cite a page it has never fetched.

Track

POST /v1/prompts

Spends credits. Answers 201. MCP tool: add_prompts.

Starts tracking one or more prompts. From the next daily run, each is read across every platform your plan includes.

Field	Type	Notes
`prompts`	string[]	Required. One or more prompt texts, none blank
`topic`	string	Optional. Created if it does not exist
`country`	string	Optional ISO 3166-1 alpha-2 code, e.g. `US`. Defaults to the workspace’s country

There is no platform field. Which surfaces a prompt runs on comes from your plan, not from the request.

Shell

curl -X POST https://api.attensira.com/v1/prompts \
  -H "Authorization: Bearer atn_live_<your key>" \
  -H "Content-Type: application/json" \
  -d '{"prompts":["best crm for small teams","crm with free tier"],"topic":"buying intent"}'

201 Response

{
  "added": [{ "id": "prm_8f21", "text": "best crm for small teams" }],
  "skipped": [{ "text": "crm with free tier", "reason": "already tracked" }],
  "credits_spent": 2,
  "credits_remaining": 4198
}

credits_spent and credits_remaining are null when your plan does not meter the action. Your plan also caps how many prompts you can hold at once — see Plans.

DELETE /v1/prompts/

Destructive. MCP tool: remove_prompt.

Permanently stops tracking a prompt and frees its slot. Its historical data goes with it and this cannot be undone — fetch it first if you want it.

Parameter	In	Type	Notes
`prompt`	path	string	Required. Prompt id

Response

{ "id": "prm_8f21", "removed": true }

POST /v1/competitors

Answers 201. No credits. MCP tool: add_competitor.

Registers a brand to detect alongside yours in answers already being collected. It creates no new readings, so it costs nothing.

Field	Type	Notes
`domain`	string	Required. Bare hostname, e.g. `rival.com` — no scheme or path
`name`	string	Optional display name. Defaults to the domain

201 Response

{ "id": "cmp_10b3", "domain": "rival.com", "name": "Rival", "created": true }

created: false means the domain was already tracked, so nothing changed. Competitor rates use the same denominator as your own, so adding one never changes your numbers.

Automations

GET /v1/automations

Read-only. No credits. MCP tool: list_automations.

Lists every automation with its cadence and last run. No parameters.

Response

{
  "automations": [
    {
      "id": "aut_71cd",
      "name": "Monday visibility report",
      "instruction": "summarise last week's visibility and flag anything that moved",
      "trigger": "weekly",
      "tools": [],
      "status": "active",
      "timezone": "Europe/London",
      "run_at_minute": 540,
      "last_run_at": "2026-09-01T08:00:00Z"
    }
  ]
}

status is active (runs on its trigger), paused (does not), or done (a once trigger that already fired). tools: [] means the default read-only set.

GET /v1/automations/

Read-only. No credits. MCP tool: get_automation.

One automation in full, with its most recent run inline — so “did my Monday report run?” costs one call, not two.

Response

{
  "automation": { "id": "aut_71cd", "name": "Monday visibility report", "trigger": "weekly", "status": "active" },
  "latest_run": { "id": "ses_9d02", "status": "complete" }
}

latest_run is null when the automation has never run. Pass its id to GET /v1/sessions/{id} for the full trace.

POST /v1/automations

Answers 201. Creating is free; each run it performs spends credits. MCP tool: create_automation.

Field	Type	Default	Notes
`name`	string	—	Required
`instruction`	string	—	Required. What it should do each run, in plain language
`trigger`	enum	—	Required. `manual`, `once`, `daily` or `weekly`. `manual` and `once` never fire on a clock
`tools`	string[]	—	Optional allow-list of tool names it may use. Omit to allow everything the plan includes
`timezone`	string	UTC	Optional IANA zone the schedule is written in, e.g. `Europe/London`
`run_at_minute`	integer	—	Optional minutes past local midnight, 0–1439. `540` is 09:00. Only meaningful for `daily` and `weekly`

Shell

curl -X POST https://api.attensira.com/v1/automations \
  -H "Authorization: Bearer atn_live_<your key>" \
  -H "Content-Type: application/json" \
  -d '{"name":"Monday visibility report","instruction":"summarise last week","trigger":"weekly","timezone":"Europe/London","run_at_minute":540}'

Returns the created automation in the shape shown under GET /v1/automations.

POST /v1/automations//runs

Spends credits. Answers 200. MCP tool: run_automation.

Runs an automation immediately, outside its cadence. Returns a session handle, not a finished result.

Parameter	In	Type	Notes
`id`	path	string	Required
`Idempotency-Key`	header	string	Strongly recommended. A repeat call with the same key does not start — or bill — a second run

Shell

curl -X POST https://api.attensira.com/v1/automations/aut_71cd/runs \
  -H "Authorization: Bearer atn_live_<your key>" \
  -H "Idempotency-Key: 2026-09-02-monday-report"

Response

{ "session_id": "ses_9d02", "status": "running" }

Poll GET /v1/sessions/{id}. Re-sending this POST without an Idempotency-Key starts a second billed run.

DELETE /v1/automations/

Destructive. MCP tool: delete_automation.

Permanently deletes an automation and its run history. This cannot be undone — confirm with GET /v1/automations/{id} first.

Response

{ "id": "aut_71cd", "deleted": true }

Agent

POST /v1/ask

Spends credits. Answers 200. MCP tool: ask.

Open-ended investigation the measurement endpoints cannot answer — why a prompt is losing, what to change on a page — run by the Attensira agent, which crawls pages, audits them as a model sees them, and searches the web. Try a measurement endpoint first: /v1/analytics/{area} for any metric or ranked list, /v1/prompts/{prompt} for one named prompt, /v1/pages for one URL. Those are free and immediate; this costs credits and takes time.

Field	Type	Notes
`question`	string	Required. In plain language
`session`	string	Optional session id from a previous ask, to continue that thread

Response

{
  "session_id": "ses_9d02",
  "status": "running",
  "answer": null,
  "poll_after_ms": 4000
}

status is complete (the answer is present), running (poll the session after poll_after_ms) or failed (the run ended without an answer). A running response is the success case, not an error.

The agent runs on an agent model — the LLM powering the chat. That is a different thing from a tracked platform, which is the answer surface Attensira reads on your behalf. Changing your agent model does not change what is measured.

GET /v1/sessions/

Read-only. No credits. MCP tool: get_session.

Fetches a session started by an ask or an automation run: its status and, once finished, its answer. This is how you poll async work.

Parameter	In	Type	Notes
`id`	path	string	Required
`include`	query	string	Optional. `events` returns the step-by-step trace. The only supported value; repeat the parameter or comma-separate

Shell

curl "https://api.attensira.com/v1/sessions/ses_9d02?include=events" \
  -H "Authorization: Bearer atn_live_<your key>"

Response

{
  "id": "ses_9d02",
  "status": "complete",
  "answer": "Your pricing page is cited on Perplexity but not on ChatGPT, because…",
  "events": [{ "type": "fetch", "at": "2026-09-02T08:00:04Z", "detail": "read acme.com/pricing" }]
}

The events trace shows which tools the agent called and with what arguments — the place to look when an answer seems wrong and you want to know which slice it read.

Account

GET /v1/account

Read-only. No credits. MCP tool: get_account.

The org, workspace, plan, credit balance, which platforms the plan tracks, and what this key may do. No parameters.

Response

{
  "org": { "id": "org_3a10", "name": "Acme" },
  "project": { "id": "prj_5b22", "name": "Acme", "domain": "acme.com" },
  "plan": { "name": "Growth", "platforms": ["chatgpt", "perplexity"] },
  "credits": { "balance": 4200, "renews": "2026-10-01T00:00:00Z" },
  "scopes": ["read", "write"]
}

Call this before reporting any per-platform number: plan.platforms is the authority on which surfaces were queried at all, so a platform missing from it was never measured rather than measured at zero. credits.balance and credits.renews are null when the plan does not meter credits. An endpoint that fails with 403 is missing a scope listed in scopes.

GET /v1/ai-traffic/install

Read-only. No credits. MCP tool: get_ai_traffic_install.

Everything needed to start sending AI-crawler hits: the ingest endpoint, your workspace’s HMAC signing secret, the signature header name, the replay window, the daily cap, and a copy-pasteable edge worker. No parameters.

Response

{
  "endpoint": "https://webapp.attensira.com/v1/visits",
  "method": "POST",
  "signature_header": "X-Attensira-Signature",
  "signing_secret": "…",
  "project_id": "prj_5b22",
  "replay_window_seconds": 300,
  "daily_visit_cap": 100000,
  "worker": "export default { async fetch(request, env) { … } }",
  "notes": ["Deploy in front of the tracked domain."]
}

Call it when AI traffic is empty and you need to know how to send us any. The signing secret is derived from the workspace id, so it is stable and can be shown again — unlike your API key, which is displayed exactly once.

Get started

What you track

Reading the numbers

Pages and AI traffic

The agent

MCP

Account

Reference

REST API endpoint reference

Before you start: what costs money and what destroys data

Status codes

Find and measure

GET /v1/search

GET /v1/analytics/

GET /v1/prompts/

GET /v1/pages

Track

POST /v1/prompts

DELETE /v1/prompts/

POST /v1/competitors

Automations

GET /v1/automations

GET /v1/automations/

POST /v1/automations

POST /v1/automations//runs

DELETE /v1/automations/

Agent

POST /v1/ask

GET /v1/sessions/

Account

GET /v1/account

GET /v1/ai-traffic/install

​Before you start: what costs money and what destroys data

​Status codes

​Find and measure

​GET /v1/search

​GET /v1/analytics/

​GET /v1/prompts/

​GET /v1/pages

​Track

​POST /v1/prompts

​DELETE /v1/prompts/

​POST /v1/competitors

​Automations

​GET /v1/automations

​GET /v1/automations/

​POST /v1/automations

​POST /v1/automations//runs

​DELETE /v1/automations/

​Agent

​POST /v1/ask

​GET /v1/sessions/

​Account

​GET /v1/account

​GET /v1/ai-traffic/install

Before you start: what costs money and what destroys data

Status codes

Find and measure

GET /v1/search

GET /v1/analytics/

GET /v1/prompts/

GET /v1/pages

Track

POST /v1/prompts

DELETE /v1/prompts/

POST /v1/competitors

Automations

GET /v1/automations

GET /v1/automations/

POST /v1/automations

POST /v1/automations//runs

DELETE /v1/automations/

Agent

POST /v1/ask

GET /v1/sessions/

Account

GET /v1/account

GET /v1/ai-traffic/install