REST API

AI-search visibility your own code can read and change

Eighteen endpoints under https://api.attensira.com/v1, reached with one workspace-scoped bearer key. A nightly export, a deploy check, an internal dashboard or an n8n HTTP step can pull mention rate, citation rate, sources and competitors — and add prompts, run automations or ask the agent — without speaking a protocol built for assistants.

Key only, no OAuth, no expiry. Three endpoints spend credits and two destroy data; everything else is a free read. Full parameter and response detail is in the endpoint reference, and the MCP server is the same capabilities for an assistant rather than a script.

Karl-Gustav Kallasmaa, Founder & CEOLast updated 3 September 2026

Which door to use

The REST API and the MCP server are twins on purpose. Every REST endpoint has an MCP tool and every MCP tool has a REST endpoint, so the answer a customer gets never depends on which one they picked. Both take the same atn_live_ key, so adding the second costs you no new credential.

When to use REST and when to use MCP
Use	When
MCP server	An assistant is doing the work — Claude Code, Cursor, ChatGPT. The assistant discovers the tools and decides which to call.
REST API	Your code is doing the work — a nightly export, a deploy check, an internal dashboard, a Zapier or n8n HTTP step.

Your first request

Call /v1/account first from a fresh integration. It confirms which workspace the key points at, and its plan.platforms field is the authority on which AI answer surfaces were queried at all — a platform missing from that list was never measured, which is not the same as measured at zero.

curl https://api.attensira.com/v1/account \
  -H "Authorization: Bearer atn_live_<your key>"

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

https://api.attensira.com/healthz is unauthenticated and answers without a key, which makes it a useful reachability check when a client is silent about why it failed.

The 18 endpoints, by group

Attensira REST endpoints grouped by what they do
Group	Endpoints
Find and measure	`GET /v1/search · GET /v1/analytics/{area} · GET /v1/prompts/{prompt} · GET /v1/pages`
Track	`POST /v1/prompts · DELETE /v1/prompts/{prompt} · POST /v1/competitors`
Inbox	`GET /v1/inbox · POST /v1/inbox/tasks/{taskId}`
Automations	`GET /v1/automations · POST /v1/automations · GET /v1/automations/{id} · DELETE /v1/automations/{id} · POST /v1/automations/{id}/runs`
Agent	`POST /v1/ask · GET /v1/sessions/{id}`
Account	`GET /v1/account · GET /v1/ai-traffic/install`

GET /v1/analytics/{area} is the one that does most of the work. The area is one of visibility, prompt, page, source, competitor, topic, platform or bot, and one call returns a ranked slice for a window of 1 to 365 days.

What costs money and what destroys data

REST endpoints that spend credits or destroy 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.

POST /v1/automations/{id}/runs takes an Idempotency-Key header. Send one. Re-sending the request without it starts — and bills — a second run.

Everything else is free to call. Credits meter agent work, not reading: the ten read-only endpoints cost nothing however often your pipeline hits them, and adding a competitor or resolving an inbox task is free too. Creating an automation is free; each run it performs is not.

Authentication, and why there is no OAuth

Every request except /healthz carries a workspace-scoped key as a bearer token. The format is atn_live_ followed by 32 hexadecimal characters. The key is displayed exactly once at mint time, because only a hash is stored — a lost key is replaced, not recovered.

curl https://api.attensira.com/v1/analytics/visibility \
  -H "Authorization: Bearer atn_live_<your key>"

The properties worth knowing

The key names the workspace. No endpoint takes a workspace or project id, so a request cannot be retargeted at someone else's data.
Scope is read, or read and write. A real key missing the scope an endpoint needs returns 403 with forbidden, not 401. GET /v1/account lists the key's scopes, which is where to look when a write fails and a read succeeds.
Redirects are never followed. A 3xx is treated as the response rather than chased, because following one could re-send a live key to another host.
A key is never cached or mirrored. Revoking at the dashboard takes effect on the next request; there is no copy in the API layer to go stale.
Mint one key per integration. Keys carry last_used_at, so a per-integration key is the difference between revoking one job and breaking every job you have.

Conventions that will bite you if you skip them

Unknown fields are rejected. A POST body containing a field the endpoint does not define is a 400, deliberately, rather than a silent drop.
Numeric parameters are clamped, not rejected. ?limit=9999 against a cap of 50 returns 50 rows. A value that is not a number at all returns 400.
Page on has_more. Only GET /v1/search pages. total is a floor rather than a grand total, and a full page is not proof there are more.
Every response carries X-Request-Id. Send your own and it is reused end to end, so one trace stays one trace. Quote it in a support request.
One error envelope, seven types. invalid_request, unauthorized, forbidden, not_found, conflict, rate_limited and server_error. Branch on type, never on message — the wording changes without notice.
The version is in the path. /v1 will not change shape under you: fields may be added, never removed or retyped. Write clients that ignore fields they do not recognise.

What the API will not tell you

The measurement rules are the same through the API as through the dashboard, and the API is where they are easiest to get wrong.

There is no blended visibility score to fetch. Mention rate and citation rate are returned separately and deliberately never collapsed into one number, because they move for different reasons and are fixed by different work.
There is no sentiment field, no brand rank and no share of voice that sums to 1. Competitor rates use your denominator, so they can total well past 100% across brands — that is expected, not a bug.
A delta that did not clear a two-proportion z-test at 95% comes back as {value: null, real: false}. That is "no change we can prove", in either direction, and reporting it as a decline is the most common misreading.
Nothing here attributes a mention or a citation to a visit, a signup or revenue. Attensira does not claim that link and the API does not expose one.
Freshness is bounded by sampling, not by polling. Each prompt runs at most once per model per country per workspace-local calendar day, so hitting an endpoint hourly returns the same numbers faster, not fresher ones.

Which plans include it

Every plan. The REST API is not one of the capabilities the billing ladder gates — those are Knowledge & Skills and Crawler Logs, both Growth and above. Three endpoints meter credits on every tier, and the monthly credit allowance, prompt slots, sampling depth and retention are what change between tiers — all of them visible on the pricing page, which is generated from the same ladder the billing system reads rather than typed by hand.

Mint a key in the app under Settings → Developer, and read Authenticating REST API requests before you put one into a pipeline.

Frequently asked questions

What can the Attensira REST API do?

The same eighteen things the MCP server can. Every REST endpoint has an MCP tool and every MCP tool has a REST endpoint, on purpose, so a customer's answer never depends on which door they came through. The groups are find and measure, track, inbox, automations, agent, and account.

Does the API use OAuth?

No, and there is no plan to change that. The REST API takes a workspace-scoped atn_live_ key sent as a bearer token, because an API is called by code and code should not need a consent screen. The MCP server additionally accepts OAuth for AI clients that can open a browser. One key reaches both surfaces.

Do API keys expire?

No. A key stays valid until you or a workspace admin revokes it, so a script deployed once keeps running without anyone re-authorising it. There is no rotation deadline and no maximum age. Access tokens on the MCP server do expire after 60 minutes, but that is a property of OAuth on that surface and has no bearing on /v1.

Which endpoints cost money or destroy data?

Three spend credits — POST /v1/prompts, POST /v1/automations/{id}/runs and POST /v1/ask. Two destroy data — DELETE /v1/prompts/{prompt} and DELETE /v1/automations/{id}. Nothing else changes state or produces a bill. Send an Idempotency-Key header on an automation run; without one, re-sending the POST starts a second billed run.

Can I point a request at another workspace?

No endpoint takes a workspace or project id. There is no path segment, query parameter or body field anywhere in /v1 that identifies a workspace, because the key already does. That is a security property rather than a convenience — a URL that cannot express a workspace cannot be pointed at someone else's. To work across two workspaces, mint two keys.

What happens if I send a field the endpoint does not define?

You get a 400, not a silent drop. A misspelled instructions field quietly ignored is an automation that does the wrong thing forever; a 400 at the moment of the typo is cheaper. Numeric parameters behave the other way: limit=9999 against a cap of 50 returns 50 rows, because as many as you can give me is what was meant.

How do I handle a null in the response?

Never coerce it to zero. A rate is {value, n}, a delta is {value, real}, and per-platform metrics carry {tracked, readable}. A null value means Attensira did not measure that thing in that window; tracked: false means the platform was never queried at all. This matters more through the API than through the dashboard, because your code is what will turn a null into a 0 on the way into a chart.

Where to go next

The MCP serverThe same 18 capabilities as tools an assistant can discover and call.IntegrationsGitHub, MCP clients, your own MCP server, and edge middleware for crawler data.Prompt trackingWhat a prompt is, how often it runs, and what the analytics endpoints are actually counting.PricingPrompt slots, sampling depth, retention and credits per plan.