REST API endpoint reference

Every endpoint lives under https://api.attensira.com/v1. Every one takes Authorization: Bearer atn_live_<32 hex>, and every one also takes an optional ?project=<workspace id> when the key’s organisation has more than one workspace — see authentication. Each endpoint below names the MCP tool it is the twin of, and answers with the same payload. The tools without a REST endpoint yet are listed under MCP-only for now at the end of this page. ?project= is always the workspace, never a project. A project is a work area on the wire: it is read and steered under /v1/work-areas, and a goal or a deliverable that points at one carries its id as work_area_id. Creating a project and changing its settings are in the dashboard only.

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
`POST /v1/sessions/{id}/context` with `run: true`	Spends credits	Queues the session again to act on the new context
`POST /v1/inbox/tasks/{id}/answer`	Spends credits when the run that asked had finished	A finished, failed or suspended run starts a new turn on the answer
`POST /v1/work-areas/{id}/steer`	The reply spends credits	Posting is free; the project’s crew answers the post with an ordinary agent run
`DELETE /v1/prompts/{prompt}`	Destructive	Stops tracking a prompt; its history goes with it
`DELETE /v1/competitors/{id}`	Destructive	Stops scoring a rival; past readings keep what they recorded
`DELETE /v1/automations/{id}`	Destructive	Removes the automation and its schedule. Past runs are kept as sessions
`DELETE /v1/sessions/{id}`	Destructive	Deletes a finished session and its trace

Nothing else on this page produces a bill or erases history.

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.

One search across prompts, pages, automations and sessions. 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 prompt text, page URLs and titles, automation names and instructions, and session titles and transcripts
`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": "https://acme.com/pricing", "title": "https://acme.com/pricing", "snippet": "Pricing — Acme", "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}. A hit whose label starts with the query ranks above one that merely contains it; at equal footing prompts come before pages, then automations, then sessions. Answers themselves are not searched — they are read verbatim through GET /v1/memory/answers/history and GET /v1/memory/answers/slice.

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`. Rows nothing was measured for sort last either way
`limit`	query	integer	20	Maximum 100
`filter`	query	string	—	Case-insensitive substring on row labels. For `area=platform` it names the platform and is required

`area`	One row per	Answers
`visibility`	tracked platform	Share of voice per platform, with the workspace’s own rate alongside — the orienting call
`prompt`	tracked prompt	Which prompts you win and lose
`page`	page of yours	Which of your pages get cited, as a rate on every answer sampled
`source`	external domain	Which domains the models cite in your category, as a share of every citation
`competitor`	rival	Workspace-wide share of voice per competitor, with the competitor id
`topic`	prompt topic	Per-topic rollup; prompts under no topic are one row with id `no_topic`
`platform`	the platform named in `filter`	That platform end to end
`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,
  "order": "worst_first",
  "filter": "",
  "total_rows": 12,
  "truncated": true,
  "visibility": { "value": 0.3, "n": 20 },
  "rows": [
    {
      "id": "prm_8f21",
      "label": "best crm for small teams",
      "topic": "buying intent",
      "country": "US",
      "visibility": { "value": 0.12, "n": 25 },
      "share_of_voice": { "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 } },
        "perplexity": { "tracked": true, "readable": false, "rate": { "value": null, "n": 0 } }
      },
      "answers_read": 25,
      "failures": 1
    }
  ]
}

total_rows is how many rows survived the filter and truncated whether limit cut them, so a short list can be told from a cut one. A tracked platform with no readings in the window appears as tracked: true, readable: false with a null rate — present, and not zero. 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 },
  "citation": { "value": 0.04, "n": 25 },
  "delta": { "value": -0.05, "real": true },
  "position": 2,
  "answers_read": 25,
  "failures": 1,
  "platforms": {
    "chatgpt": { "tracked": true, "readable": true, "rate": { "value": 0.2, "n": 15 }, "citation": { "value": 0.07, "n": 15 } }
  },
  "competitors": [{ "name": "rival.com", "count": 15, "rate": { "value": 0.6, "n": 25 } }],
  "sources": [{ "url": "g2.com", "domain": "g2.com", "count": 11, "rate": { "value": 0.44, "n": 25 } }],
  "why": ["Named in 3 of 25 answers; rival.com was named in 15."]
}

topic is null when the prompt is not filed under one and country is null for the workspace default. Competitor and source rates are on this prompt’s own answers_read. 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",
  "citations": 5,
  "total_answers": 120,
  "citation": { "value": 0.04, "n": 120 },
  "delta": { "value": null, "real": false },
  "platforms": {
    "perplexity": { "tracked": true, "readable": true, "rate": { "value": 0.08, "n": 60 }, "citations": 5 },
    "chatgpt":    { "tracked": true, "readable": true, "rate": { "value": 0, "n": 60 }, "citations": 0 }
  },
  "prompts": [{ "id": "prm_8f21", "text": "best crm for small teams", "citations": 2, "rate": { "value": 0.08, "n": 25 } }],
  "in_sitemap": true
}

The delta is always {value: null, real: false} here: the page fold has no earlier window to compare against, and the contract’s word for that is “no basis”, not a number. If this comes back empty, check GET /v1/analytics/bot before rewriting the page — a model cannot cite a page it has never fetched.

POST /v1/evidence/query

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

Your own data question as a table: one metric, grouped by up to two dimensions, filtered, over a window. It reads the same stored days and folds them the same way as the dashboard boards, so the numbers match what the dashboard shows for the same window. The body is a JSON object with the same fields, values and limits as the MCP tool: metric (required), group_by, days or from and to, the filters topic_ids, prompt_ids, engines, surface, country, markets, property_ids, competitor, intent, stage, state, domain and text_contains, and limit. The query_evidence reference lists every metric with what it can be grouped and filtered by. A field the query does not know is refused rather than ignored, so a misspelt filter cannot come back as unfiltered numbers.

Shell

curl https://api.attensira.com/v1/evidence/query \
  -H "Authorization: Bearer atn_live_<your key>" \
  -H "Content-Type: application/json" \
  -d '{"metric": "gsc_clicks", "group_by": ["page"], "days": 28, "limit": 2}'

Response

{
  "metric": "gsc_clicks",
  "group_by": ["page"],
  "window": { "from": "2026-09-05", "to": "2026-10-02", "days": 28 },
  "day_basis": "search_console",
  "unit": "count",
  "rows": [
    { "key": { "page": "acme.com/pricing" }, "value": 412, "n": 9310 },
    { "key": { "page": "acme.com/blog/crm-guide" }, "value": 0, "n": 220 }
  ],
  "gaps": [{ "key": "2026-09-30..2026-10-02", "reason": "not_recorded", "detail": "Search Console has not reported these days yet" }],
  "truncated": true
}

value is in unit, and null means unmeasured, never 0: the row’s gap says why. n is on every row; for Search Console it is the impressions behind the row. gaps names everything the answer could not measure, and an empty list is the claim that nothing is missing. day_basis says which calendar the day labels count in (slot_day, search_console or utc; see Google search). A question with no honest answer — an unknown metric, a metric grouped or filtered in a way it does not support, a from–to span over 365 days, an id the workspace does not have — is a 400 with type: "invalid_request" and a message that names the problem and what to ask instead. A question too broad to answer in time is a 422 whose message says what to narrow. days and limit outside their ranges are clamped to the nearest bound rather than refused.

GET /v1/deciding-sources

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

Which pages and domains decided the AI answers, whether you already appear on each, and the next move for each. GET /v1/analytics/source ranks by citations; this ranks by influence over a decision. See Deciding sources.

Parameter	In	Type	Default	Notes
`prompt`	query	string	—	Optional. One tracked prompt, by id or exact text. Omit for every prompt
`days`	query	integer	30	1–365

Returns groups, most influential first, one per prompt, platform and surface. Each carries a label, n, present, a recommendation, and sources ranked by weight, each with domain, url, citations, share, present and action. The full row is described under deciding_sources.

GET /v1/win-plan

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

The ordered plan for winning one tracked prompt. See Win this answer.

Parameter	In	Type	Default	Notes
`prompt`	query	string	—	Required. Prompt id or exact text
`days`	query	integer	30	1–365

Returns prompt, n, evidence, the steps in order, rereads_at and credits_estimate, as described under win_plan.

The receipts

The numbers above are folds over stored answers. These endpoints hand back the rows themselves, verbatim. See Deep reads.

GET /v1/memory/answers/history

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

Every sampled answer to one tracked prompt, verbatim and newest first, with citations and reading ids.

Parameter	In	Type	Default	Notes
`prompt`	query	string	—	Required. The prompt id
`platform`	query	string	—	One platform; omit for all
`days`	query	integer	28	1–365
`limit`	query	integer	10	Readings per page, 1–50
`cursor`	query	string	—	`next_cursor` from the previous page

Returns answers, readings, has_more and next_cursor. An answer over 8 KB is cut and carries truncated: true, with text_bytes the full length. A failed sample is listed with failed: true, never dropped. The row shape is described under answer_history.

GET /v1/memory/answers/slice

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

Every answer matching a predicate, verbatim. Terms AND together and select the sample; at least one is required.

Parameter	In	Type	Default	Notes
`platform`	query	string	—	Repeat for several
`country`	query	string	—	ISO 3166-1 alpha-2
`topic_id`	query	string	—	The prompts filed under this topic now
`prompt_ids`	query	string	—	Repeat, or comma-separate, for several; at most 100
`surface`	query	enum	—	`consumer` or `api`
`model`	query	string	—	The start of the model’s name, case-insensitive
`competitor`	query	string	—	A rival’s domain the answer named or linked
`cited_domain`	query	string	—	A domain among the citations; subdomains match
`brand_named`	query	boolean	—	`true` or `false`
`sentiment`	query	enum	—	`positive`, `neutral`, `negative`, `none` (scored, no stance) or `unscored` (never scored)
`brand_position_min`, `brand_position_max`	query	integer	—	Your brand’s place in the answer’s order of brands, 1 for first, inclusive
`text_contains`	query	string	—	A phrase in the answer’s text, literal and case-insensitive, at most 80 characters
`from`, `to`	query	string	—	`YYYY-MM-DD`, inclusive
`days`	query	integer	28	1–365, when `from` and `to` are omitted
`limit`, `cursor`	query			As for answer history

Shell

curl -G https://api.attensira.com/v1/memory/answers/slice \
  --data-urlencode "topic_id=top_41a2" --data-urlencode "sentiment=negative" \
  --data-urlencode "brand_position_min=3" --data-urlencode "days=60" \
  -H "Authorization: Bearer atn_live_<your key>"

The answer terms (surface, model, competitor, cited_domain, brand_named, sentiment, the brand positions and text_contains) must all hold for one sample, and only matching samples come back. Without topic_id or prompt_ids, text_contains covers at most 30 days; a wider window is a 400 saying what to narrow. The full semantics are in the answer_slice reference.

GET /v1/memory/citations/timeline

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

One domain’s or one page’s citations per day, per platform.

Parameter	In	Type	Default	Notes
`domain`	query	string	—	A site, e.g. `g2.com`. Or pass `url` for one page
`url`	query	string	—	One page’s URL, instead of `domain`
`days`	query	integer	28	1–365

Returns domain, url, total, prompts and series, one entry per platform, each with points for every day of the window: day, citations, mean_position (null when nothing that day carried a position) and prompts. A zero day is a real zero.

GET /v1/memory/pages/history

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

One page’s versions: every version captured, when, and what changed between them. It covers your own pages and the cited and competitor pages the workspace watches.

Parameter	In	Type	Default	Notes
`url`	query	string	—	Required. Absolute: one of your own pages, or a cited or competitor page the workspace watches

Metadata on a version taken before it was recorded reads not_captured, and is never reported as a change. Any other page on another domain is a 404. Returns url, known, and versions oldest first, each with what changed since the one before. The row shape is described under page_history.

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, at most 50 per call, each at most 500 characters
`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" },
    { "id": "prm_2c07", "text": "crm with free tier" }
  ],
  "skipped": [],
  "credits_spent": null,
  "credits_remaining": null
}

A prompt that was already tracked comes back in added with its existing id, so a repeated call is idempotent all the way out; skipped is empty today. credits_spent and credits_remaining are null because tracking is charged as the prompts are read, not on this call. Your plan caps how many prompts you can hold at once, and a paste that would exceed it is refused with a 409 naming how many slots remain — 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" }

Competitor rates use the same denominator as your own, so adding one never changes your numbers.

DELETE /v1/competitors/

Destructive. MCP tool: remove_competitor.

Stops scoring a rival. Past readings keep what they already recorded, so history does not move; the rival simply stops being scored from here on.

Parameter	In	Type	Notes
`id`	path	string	Required. Competitor id, from `GET /v1/analytics/competitor`

Response

{ "id": "cmp_10b3", "tracked": false }

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. Paused and retired automations are always listed. One the product paused on its own carries retired_reason and retired_at. next_run_at is null for an event automation.

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	`daily`	`daily`, `weekly`, `monthly`, `quarterly`, `event`, `manual` or `once`. `monthly` and `quarterly` fire on the 1st. `manual` and `once` run only through `POST /v1/automations/{id}/runs`, and `once` then retires
`tools`	string[]	—	Optional allow-list of tool names it may use. Omit to allow everything the plan includes
`timezone`	string	The workspace’s	Optional IANA zone the schedule is written in, e.g. `Europe/London`. UTC only if the workspace has none
`run_at_minute`	integer	540	Minutes past local midnight, 0–1439. `540` is 09:00. Only meaningful for the clock triggers: `daily`, `weekly`, `monthly` and `quarterly`
`run_on_weekday`	integer	—	For `weekly`: 0 = Sunday to 6 = Saturday
`event_types`	string[]	—	Required and non-empty when `trigger` is `event`; valid only then. Any of `prompt_lost`, `citation_lost`, `new_deciding_source`, `competitor_changed`, `page_changed`. See Event automations

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.

Shell — an event automation

curl -X POST https://api.attensira.com/v1/automations \
  -H "Authorization: Bearer atn_live_<your key>" \
  -H "Content-Type: application/json" \
  -d '{"name":"React to lost citations","instruction":"For each lost citation, propose one fix","trigger":"event","event_types":["citation_lost","prompt_lost"]}'

PATCH /v1/automations/

No credits. MCP tool: update_automation.

A partial edit. A field you leave out is left alone, so pausing an automation cannot quietly rewrite what it does. Takes name, instruction, trigger, event_types, tools, status (active or paused), timezone, run_at_minute and run_on_weekday, with the same rules as POST /v1/automations. event_types is valid only when the trigger is event. Returns the 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 schedule. This cannot be undone — confirm with GET /v1/automations/{id} first. Its past runs are kept as sessions, readable through GET /v1/sessions.

Response

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

Inbox

Everything waiting on a person, and every act the dashboard’s Inbox offers on it. Each act goes through the same path as a click in the dashboard, so a yes or an answer means the same thing wherever it was given, and the action log records your key as the one who gave it. Each row’s type says which endpoint acts on it, and its ask_kind (approve, answer, do or info) says what it asks of a person:

Row	`ask_kind`	Act on it with
`work_item`	`approve`	`POST /v1/inbox/{id}/approve` (with an edit, for an article, post or rewrite) or `/decline`
`work_item`	`do`	Nothing to approve: a copy handoff or an outreach draft the person sends themselves
`ask`	`approve`	`POST /v1/inbox/asks/{ask_id}/approve` or `/decline`
`ask`	`answer`	Answered in its own session, not here
`task`	`answer`	`POST /v1/inbox/tasks/{id}/answer`
`task`	`do`	`POST /v1/inbox/tasks/{id}/resolve`, once the person has done it

Every write needs a read-and-write key; a read key gets 403. Approve, answer and decline only on the person’s instruction. Every act returns next_item_ref when something else is waiting: the row the ranking puts first now, readable with GET /v1/inbox/items/{ref}.

GET /v1/inbox

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

What is waiting on a person: approvals the agent stopped for, questions, work it could not finish alone, failed automations, and approvals that expired unanswered.

Parameter	In	Type	Default	Notes
`category`	query	string	`needs_you`	`needs_you` (waiting on a person) or `in_flight` (approved and running, and Done rows still being checked)
`view`	query	string	`list`	`list` returns every row, newest first, under `items`. `triage` returns the `needs_you` rows as decisions under `triage`, and is `400` with `category=in_flight`
`limit`	query	integer	3	`view=triage` only: how many decisions are ranked first. Held to 1–20, so a larger number is read as 20; `400` with `view=list`

Each row in items carries type (work_item, ask or task), id, ref, ask_kind, title, reason, session_id and updated_at, plus ask_id on an ask. A task row also carries what it asks: task.question (prompt, up to six options, and fact_ref when it fills a profile field), task.steps, and task.verification while a Done is being checked. list_approvable is true only on a proposed change that may be approved without opening it: one whose effect can be undone and that is classed safe.

Shell

curl "https://api.attensira.com/v1/inbox?view=triage" \
  -H "Authorization: Bearer atn_live_<your key>"

Response

{
  "triage": {
    "top": [
      {
        "key": "task:missing_integration:github",
        "ask_kind": "do",
        "label": "Connect GitHub · 7 waiting",
        "count": 7,
        "item_refs": ["t_66f1a2", "t_66f1b9", "…"],
        "oldest_waiting_since": "2026-09-28T07:12:00Z",
        "lead": { "type": "task", "ref": "t_66f1a2", "title": "Connect GitHub", "…": "…" }
      }
    ],
    "sections": [
      { "ask_kind": "answer", "label": "2 more questions", "count": 2, "decisions": ["…"] }
    ],
    "total_open": 12,
    "decisions": 5,
    "merged_count": 9
  }
}

The triage is the Inbox’s own ranking, the same one the dashboard, the morning brief and the daily email read. Rows that wait on the same thing fold into one decision, and top holds the first limit of them; the rest are in sections, grouped by ask_kind. total_open counts rows, decisions counts decisions, and merged_count is how many sightings are not shown as rows of their own. See At most three decisions first for the order.

GET /v1/inbox/items/

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

One row by its ref, in any state, in full: the whole proposal a work item would make, the question a task asks and its answer once given, a done row as done.

Parameter	In	Type	Notes
`ref`	path	string	Required. A row’s `ref`, or any `next_item_ref`: `t_<task id>`, `w_<work item id>` or `a_<session id>_<ask id>`

To approve a specific version, copy work_item.change.proposal.captured_at from here into the approve body. A row the duplicate check folded into another carries merged_into, the ref of the row to read instead; one it only suspected carries possible_duplicate_of and is not hidden. A malformed ref is 400; a ref from another workspace is 404, the same as one that names nothing.

POST /v1/inbox/tasks//answer

Spends credits when the run that asked had already finished. MCP tool: answer_inbox_question.

Answers a task whose ask_kind is answer with the person’s words. The answer is saved to Company facts — the business profile field the question names, or a stated fact every later run reads — the row closes, and the run that asked is put back to work.

Field	Type	Notes
`text`	string	Free text, at most 2,000 characters
`option`	string	One of the row’s `task.question.options`, instead of `text`

Request

{ "text": "The launch is on 14 October." }

Response

{
  "task": { "id": "66f1c0", "state": "done", "…": "…" },
  "fact": { "kind": "stated_fact", "ref": "stated:66f1c3" },
  "resume": { "status": "resumed", "session_id": "ses_9d02" },
  "next_item_ref": "w_66f0aa"
}

resume.status is resumed (a running run reads the answer from its next step; a finished, failed or suspended one starts a new turn on it, which spends credits), queued_after_approval (the run reads it once its pending approval is answered), not_started (the run was cancelled, or no run asked) or failed (the answer is saved, but the run could not be handed it; retry from the row’s page in the dashboard). A second answer to the same row is 409; a row that is not a question is 400.

POST /v1/inbox/tasks//resolve

No credits. MCP tool: resolve_inbox_task.

Closes a task the agent raised.

Field	Type	Notes
`state`	string	Required. `done` (it has actually been handled), `dismissed` (it does not matter) or `snoozed`
`snoozed_until`	string	RFC 3339. Required when `state` is `snoozed`, refused otherwise

A task that carries a check (a DNS record, a connection, a line on a page) is not closed by done: it stays open with verification.status: "pending", moves to in_flight, and closes on its own when the check passes. If the check still fails after its retries, the row comes back to needs_you with verification.failure saying why; sending done again checks again. Snoozing a row while its check is pending is 409. Returns the task and next_item_ref.

POST /v1/inbox//approve

No credits. MCP tool: approve_work_item.

Approves a work item and lets the agent carry the change out. The body is optional; no body is a plain yes.

Field	Type	Notes
`expected_captured_at`	string	RFC 3339. The `work_item.change.proposal.captured_at` the person read. A proposal revised since is `409`; read the row again with `GET /v1/inbox/items/{ref}` for the current version, and show it to the person before approving that
`edited_value`	string	The person’s full edit, at most 200 KB. Approves their version instead of the agent’s

Idempotent: approving twice approves once, so a retry after a timeout is safe. Returns the work item and next_item_ref. A work item that a run started over the API or MCP filed is approved by a person, in the app. With a key or a token, approving it is 403 with reason: "self_approval" and an app_path; declining it still works. edited_value is accepted only for an article, a LinkedIn post or a rewritten passage that is still waiting, and is 400 for anything else (a fix is edited in its pull request). The edited change keeps the agent’s original, and is always a claim: it waits for a person in every approval mode and never goes out on its own. An edit that adds or changes code is 422, and nothing is approved. An edit is checked against the workspace’s rules like any draft; one that breaks a rule is 409.

POST /v1/inbox//decline

No credits. MCP tool: decline_work_item.

Declines a work item, with the reason why.

Field	Type	Notes
`reason`	string	Required. `wrong`, `not_now`, `already_done` or `never_touch`
`note`	string	The person’s words, at most 1,000 characters. Required with `wrong`

The reason is what stops the same proposal coming back; the reason and note are kept on the item and in its activity. Returns the work item and next_item_ref.

POST /v1/inbox/asks//approve

No credits for the call; the run it lets go carries on as before. MCP tool: approve_ask.

Allows a paused run, once, the exact call it stopped to ask about. {id} is the row’s ask_id.

Field	Type	Notes
`session_id`	string	Required. The row’s `session_id`: an ask id is unique only within its session

An ask from a run that was started over the API or MCP is approved by a person, in the app: with a key or a token it is 403 with reason: "self_approval" and an app_path. Declining it still works.

Response

{
  "ref": "a_66f19d02_ask_66f19d02_3",
  "session_id": "66f19d02",
  "ask_id": "ask_66f19d02_3",
  "outcome": "allowed-once",
  "next_item_ref": "t_66f1a2"
}

An ask is never edited: the yes is bound to the exact arguments the run asked about, so edited_value is 400. The run is back on the queue and has not made the call yet; poll GET /v1/sessions/{id}. A session in another workspace is 404; an ask already answered, expired, or no longer the one the run is waiting on is 409.

POST /v1/inbox/asks//decline

No credits. MCP tool: decline_ask.

Refuses the call a paused run asked for. The run reads the reason and note first, then carries on without the call.

Field	Type	Notes
`session_id`	string	Required. The row’s `session_id`
`reason`	string	Required. `wrong`, `not_now`, `already_done` or `never_touch`
`note`	string	The person’s words, at most 1,000 characters. Required with `wrong`

Returns outcome: "rejected" in the same shape as approve. Same 404 and 409.

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",
  "state": "completed",
  "answer": "Your pricing page is cited on Perplexity but not on ChatGPT, because…",
  "events": [
    { "type": "tool.start", "seq": 4, "at": "2026-09-02T08:00:04Z", "name": "get_page", "callId": "c1" }
  ]
}

status is the three-word vocabulary above; state is the engine’s own finer word, so a run parked on a question for you reads awaiting_person under a running status. 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. answer is the agent’s last message and is filled in for a finished session whether or not the trace was asked for.

Listing, stopping and feeding sessions

GET /v1/sessions, POST /v1/sessions/{id}/cancel, DELETE /v1/sessions/{id} and POST /v1/sessions/{id}/context are on their own page: Sessions.

Loop health

GET /v1/loop-health

Read-only. No credits. Works on a spent balance. MCP tool: get_loop_health.

Whether the workspace’s autopilot loop is working, idle or blocked, and why, with a day-by-day record. Call it first when nothing seems to be happening. See Loop health.

Parameter	In	Type	Default	Notes
`days`	query	integer	7	1–30

Response

{
  "status": "idle",
  "reasons": ["2 piece(s) of work are waiting for your approval."],
  "days": [
    {
      "date": "2026-09-22",
      "readings": { "chatgpt": { "ok": 40, "failed": 1 } },
      "runs": [{ "automation_id": "aut_71cd", "name": "Daily win plan", "status": "fired", "reason": "", "count": 1, "at": "2026-09-22T06:00:00Z" }],
      "findings": 1,
      "work_produced": 0,
      "approvals_pending": 2,
      "prs_opened": 0,
      "rereads_due": 0
    }
  ]
}

status is working, idle or blocked. Each runs entry has status fired, skipped or failed, and a skip carries a reason: no_credits, manual_trigger, parked_on_ask, flag_disabled, retired, paused, cap_reached or in_flight. Every count is read once for its date and is not a trend.

Account

GET /v1/account

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

The org, every workspace the credential can reach, the one this call resolved to, the credit balance, which platforms that workspace tracks, and what this credential may do. Takes an optional project.

Response

{
  "org": { "id": "org_3a10" },
  "project": { "id": "prj_5b22", "name": "Acme", "domain": "acme.com" },
  "workspaces": [
    { "id": "prj_5b22", "name": "Acme", "domain": "acme.com" },
    { "id": "prj_7c41", "name": "Beta", "domain": "beta.example" }
  ],
  "credits": { "available": 4200, "available_usd": 42.0, "held_units": 0 },
  "scopes": ["read", "write"],
  "platforms": ["chatgpt", "perplexity"]
}

Call this before reporting any per-platform number: 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. They belong to the resolved workspace, so the array is empty whenever project is null. project is null when the organisation has several workspaces and the request named none. That is the answer, not an error — workspaces carries the ids, and every other endpoint then needs an explicit ?project=. This is the only endpoint that answers without one, which is why the “several workspaces” error elsewhere points here. An endpoint that fails with 403 is missing a scope listed in scopes.

GET /v1/costs

Read-only. No credits. Works on a spent balance. MCP tool: get_costs.

What a UTC month has cost, in US dollars: the total, a month-end forecast, the spend by project, workspace, kind and deliverable type, and the work the budget committed us to against what was delivered. The same figures as the Costs page.

Parameter	In	Type	Default	Notes
`period`	query	string	this month	`YYYY-MM`, a UTC month that has started. A malformed or future month is a `400`
`project`	query	string	—	A workspace id, to narrow the breakdowns to that workspace. Omit for the whole organisation. An id outside the organisation is a `404`

Shell

curl "https://api.attensira.com/v1/costs?period=2026-09" \
  -H "Authorization: Bearer atn_live_<your key>"

Response

{
  "period": "2026-09",
  "currency": "usd",
  "as_of": "2026-09-18T09:12:04Z",
  "workspace_id": null,
  "spent_usd": 642.5,
  "forecast_usd": 1108.82,
  "by_work_area": [
    { "workspace_id": "prj_5b22", "work_area_id": "wa_19ac", "name": "Pricing pages", "spent_usd": 410.0 },
    { "workspace_id": "prj_5b22", "work_area_id": null, "name": "Unassigned", "spent_usd": 232.5 }
  ],
  "by_workspace": [{ "workspace_id": "prj_5b22", "name": "Acme", "spent_usd": 642.5 }],
  "by_kind": [
    { "kind": "agent_work", "spent_usd": 598.1 },
    { "kind": "data", "spent_usd": 44.4 },
    { "kind": "paid_placement", "spent_usd": 0 },
    { "kind": "creators", "spent_usd": 0 }
  ],
  "by_type": [
    { "type": "article", "delivered": 2, "spent_usd": 371.2 },
    { "type": "page_fix", "delivered": 8, "spent_usd": 160.4 },
    { "type": "monitoring_day", "delivered": null, "spent_usd": 44.4 },
    { "type": "other", "delivered": null, "spent_usd": 66.5 }
  ],
  "committed": [
    { "type": "article", "committed": 4, "delivered": 2, "waiting_on_you": 1, "shortfall": 1, "credit_usd": 0 },
    { "type": "page_fix", "committed": 12, "delivered": 8, "waiting_on_you": 0, "shortfall": 4, "credit_usd": 0 },
    { "type": "listing_fix", "committed": null, "delivered": 0, "waiting_on_you": 0, "shortfall": 0, "credit_usd": 0 },
    { "type": "outreach_pitch", "committed": 20, "delivered": 0, "waiting_on_you": 0, "shortfall": 20, "credit_usd": 0 }
  ],
  "credited_back_usd": 0,
  "ad_spend": { "usd": null, "source": null, "note": "Not connected. Ad spend is paid to the ad platform directly and is never part of your budget." }
}

spent_usd is the month’s spend less refunds, and every breakdown adds up to it. Ad spend is never part of it.
forecast_usd is spend divided by the days elapsed, times the days in the month: null for the first three days of a month, and what the month cost once it is over.
A null work_area_id is a workspace’s unassigned spend: chats and the Chief of staff. An empty workspace_id in by_workspace, named Across workspaces, is spend that belongs to the organisation rather than one workspace.
by_kind always lists agent_work, data, paid_placement and creators; nothing is charged under the last two today. unattributed appears only when a charge could not be placed.
delivered in by_type, and committed in committed, are null for a type we do not count. null is never 0.
committed and credited_back_usd are the organisation’s even when project names a workspace. credit_usd is the credit for undelivered work: what the close credited, or for an open month what it would credit now. In the example it is 0 because the month’s spend has not passed the value of what was delivered. See Plans for the rule.

The budget, its pace, the caps, the balance and how it is funded are not served here or anywhere a key can reach: a person sets them in Settings → Billing. The balance is on GET /v1/account.

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 /v1/wins

Read-only. No credits. Works on a spent balance. MCP tool: list_wins.

The workspace’s wins, newest first. A win is the first time an engine named your brand, or linked to your site, in an answer to a prompt that does not name your brand itself, after we had read that prompt on that engine on at least three earlier days with a successful answer and none of them did the same. Failed reads count toward neither half. Only the first naming (or link) can be a win: one that came before those three days of reading is not, and no later answer of the same kind on that prompt and engine becomes one. A win is a first since we started reading that prompt, not evidence that any work caused it. When you show one, use its sentence, which says exactly that. No parameters. Returns at most the 50 most recently found wins, and leaves dismissed wins out.

Shell

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

Response

{
  "wins": [
    {
      "id": "win_4e19",
      "prompt_id": "prm_8f21",
      "prompt": "best crm for small teams",
      "engine": "ChatGPT",
      "platform": "chatgpt",
      "kind": "linked",
      "sentence": "ChatGPT linked to acme.com for the first time since we started reading this prompt on 2 September 2026, in an answer to 'best crm for small teams' on 28 September 2026.",
      "quote": "Acme publishes its pricing openly (https://acme.com/pricing), with a free tier for up to three users.",
      "quote_truncated": true,
      "cited_url": "https://acme.com/pricing",
      "date": "2026-09-28",
      "reading_since": "2026-09-02",
      "detected_at": "2026-09-28T10:05:00Z",
      "seen": true,
      "share_url": "https://app.attensira.com/w/<slug>"
    }
  ],
  "unseen": 0
}

kind is named (the answer named the brand) or linked (it cited a page on your domain); one prompt on one engine can give one win of each kind, never two of the same. quote is a verbatim excerpt of at most 400 characters, never edited, and null when no answer that day gave an excerpt that passed the honesty check; quote_truncated says whether it stops short of either end of the answer. cited_url is the first page on your domain the answer cited, or null. date is the day of the answer and reading_since the first day we read the prompt on that engine, both YYYY-MM-DD in the workspace’s time zone. The list is ordered by detected_at, when the win was found. seen is whether someone has opened the win in the dashboard, and unseen counts every undismissed win nobody has opened, including any beyond the 50 returned. Reading this endpoint marks nothing seen. share_url is the public link to the win card while it is shared, and null otherwise.

GET /v1/brief

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

The morning brief, the same body as the email. See The morning brief.

Parameter	In	Type	Default	Notes
`date`	query	string	—	`YYYY-MM-DD` for one of the workspace’s own past days. Omit for today

Counts, never a day-over-day comparison, until a seven-day window exists. The fields are described under get_brief.

PATCH /v1/settings/agents

No credits. MCP tool: update_settings.

How far a run may go on its own. A partial edit: a field you leave out is left alone. This is the customer’s decision; change it on their instruction. See Approval. Only a person raises these settings. With an API key or an OAuth token you can lower them: a lower unattended_mode, or publish_without_approval and send_without_approval turned off. Raising the mode, turning either permission on, or changing act_path_allowlist is 403 with reason: "autonomy_raise_in_app" and the field. Make that change in the app under Settings → Autopilot.

Field	Type	Notes
`unattended_mode`	enum	`ask`, `draft` or `act`
`act_path_allowlist`	string[]	Path patterns act mode may change. Replaces the list; empty restores the default. Source, CI, lockfiles and dotfiles are refused whatever it says
`publish_without_approval`	boolean	Whether a run may put a page on the site without asking
`send_without_approval`	boolean	Whether a run may send email without asking

Returns the settings in force.

GET /v1/github/install-url

No credits. MCP tool: connect_github.

The GitHub App install link for this workspace, and nothing else. The install finishes in a browser, because GitHub hands its callback a code only the person completing it has. Each call mints a single-use link. Returns url.

Memory

Writes into what the workspace knows about itself. See Knowledge and skills.

POST /v1/observations

Answers 201. No credits. MCP tool: record_observation.

Field	Type	Notes
`statement`	string	Required. One sentence carrying its own sample size
`evidence`	object[]	Required, at least one. Each `{kind, id, url?, day?}`, `kind` being `reading`, `citation_day` or `action`

Every id is resolved against the workspace before anything is stored. One that does not exist there is a 400, never a stored fact.

POST /v1/skills

Answers 201. No credits. MCP tool: write_skill.

Field	Type	Notes
`title`	string	Required. The rule in a few words
`description`	string	Required. When the rule applies
`body`	string	Required. The rule itself
`kind`	enum	Required. `voice`, `compliance` or `playbook`

Set up a workspace

A key holder adds a workspace for a domain: the agents draft the business from its site, the person decides what to keep, and the person pays in their own browser. Nothing here can charge. Both endpoints act on the key’s own account and take no ?project=: there is no workspace to select yet, and a ?project= is refused with that reason. A new person with no account starts from an assistant over MCP instead, where signing in comes before any account exists; see Set up from your own assistant.

POST /v1/onboarding/workspace

Needs a read-and-write key. No charge. MCP tool: start_workspace.

Creates the workspace for a domain, or returns the one already started for it. Sending the same domain again never creates a second workspace: it is how you poll.

Field	Type	Notes
`domain`	string	Required. The business’s domain, e.g. `example.com`

Returns workspace_id, status, the drafted profile (each fact with the page it came from, or a question to ask when nothing was found), the suggested competitors and platforms, the proposed goals and the plans. status is drafting, needs_input, ready_to_confirm, awaiting_payment, active or first_readings_ready; the fields are described under start_workspace. An account holds one workspace waiting for payment at a time, so a second unpaid domain is a 409 naming the one to finish.

POST /v1/onboarding/workspace//confirm

Needs a read-and-write key. No charge. MCP tool: confirm_setup.

Saves the person’s setup choices and answers their checkout link. Every call mints a new link.

Field	Type	Notes
`plan`	string	Required. A plan id from the `plans` the start endpoint returned
`monthly_budget_usd`	number	The monthly budget the person chose, in US dollars. Not negative
`overage_cap_usd`	number	The most a month may be charged in all, in US dollars: from the budget up to 10% over it, and only sent with `monthly_budget_usd`. A cap above the budget lets new work run up to 10% over the budget, which stays the budget. A cap below the budget or more than 10% over it is a `400`. Omit it and work pauses at the budget, which is then the cap
`competitors`	string[]	The rivals they kept, by domain
`platforms`	string[]	The platforms they kept
`goals`	object[]	The goals they kept, each `{id, target?}` as `proposed_goals` returned them
`profile_edits`	object	Corrections to the profile, a fact’s field mapped to its new value

An omitted list keeps what was proposed; an empty list keeps none of it. Returns checkout_url, requires_browser (always true), expires_at and budget_consent, as described under confirm_setup. An account that already pays for a plan is a 409. The endpoint never charges and never uses a saved card: the person pays in their browser, and the start endpoint then reads active.

Goals

What the agents aim at: a metric, a target and a date, with a pace verdict from the daily readings. See Goals.

GET /v1/goals

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

Parameter	In	Type	Default	Notes
`status`	query	string	—	`active`, `hit`, `missed`, `paused`, `archived`, or `all`. Repeat it or comma-separate it for several. Omit it for every goal that is not archived

Returns goals, oldest first, each with baseline and current as {value, n} (a null value is not measured yet, not zero), target, target_date, pace (state is ahead, on_pace, behind or unmeasured), the projects it drives as work_area_ids, and status. The full row is described under get_goals.

POST /v1/goals

Needs a read-and-write key. No credits. MCP tool: set_goal.

Sets a goal. Set goals on the person’s instruction.

Field	Type	Notes
`metric`	string	Required. A metric key, such as `ai_share_of_voice` or `search_clicks`
`params`	object	What the metric is measured over, where it takes any
`target`	number	Required. In the metric’s own unit
`target_date`	string	Required. `YYYY-MM-DD`
`name`	string	Optional
`work_area_id`	string	The project it drives. Omit for the whole workspace
`Idempotency-Key`	header	Makes a retried create write once

The baseline is the first reading taken after the goal is set, never a field: a body with baseline is a 400.

PATCH /v1/goals/

Needs a read-and-write key. No credits. MCP tool: set_goal.

Changes a goal. A field you leave out is left alone, and a body with nothing to change is a 400.

Field	Type	Notes
`name`	string	Not empty
`target`	number	In the metric’s own unit
`target_date`	string	`YYYY-MM-DD`
`status`	enum	`active`, `paused` or `archived`. `hit` and `missed` are verdicts reached on the target date, never set
`work_area_id`	string	A project id, or `null` to make the goal the whole workspace’s
`version`	integer	The version you read. A goal that changed since is a `409`

A goal’s metric and its params never change: to measure something else, set a new goal and archive this one.

Projects

A project is an area of work with its own crew of agents, and on the wire it is a work area. Creating a project and changing its settings are in the dashboard only. See Projects.

GET /v1/work-areas

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

The workspace’s projects, each with id, name, description, team (each crew member with their status line), goal_id, unread, needs_you, budget_cap_usd and last_activity_at. Archived projects are left out.

GET /v1/work-areas/

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

One project: everything the list says, plus its direction (what people have told it, word for word), the triggers its crew runs on, automation_ids, and the feed’s newest 50 posts, newest first. A project outside the workspace is a 404.

POST /v1/work-areas//steer

Needs a read-and-write key. Posting is free; the crew’s reply is an agent run and spends credits. MCP tool: steer_project.

Gives a project’s crew the person’s direction, in their words. It is kept word for word as the project’s direction and posted to its feed; the crew answers it with an ordinary run that replans if the steer needs it.

Field	Type	Notes
`text`	string	Required. At most 4,000 characters
`Idempotency-Key`	header	Makes a retried post post once

A steer is a post and nothing else: it never approves work, changes a setting or publishes anything, and the run that answers it meets the same approvals as every run. A field other than text is refused. The response is described under steer_project.

Deliverables

GET /v1/deliverables

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

What the crews delivered, newest first: where each piece of work lives and what the re-reads proved about it.

Parameter	In	Type	Default	Notes
`type`	query	enum	—	`article`, `page`, `fix`, `social_post`, `listing_fix`, `product_copy` or `image`
`work_area_id`	query	string	—	One project’s deliverables
`status`	query	string	—	`waiting_on_you`, `draft`, `open`, `merged`, `synced_draft`, `live`, `shipped` or `closed`. Repeat it or comma-separate it for several
`limit`	query	integer	20	1–50
`cursor`	query	string	—	`next_cursor` from the previous page

Returns deliverables and next_cursor (null at the end). result is null until there is something to measure. The row is described under list_deliverables.

Reports

GET /v1/reports/latest

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

The latest published client report for a cadence. See Client reports.

Parameter	In	Type	Default	Notes
`cadence`	query	enum	`week`	`week`, `month` or `quarter`

Returns the report’s period, its facts with their n, the share link when it is shared, and the markdown in full: unlike the MCP tool, nothing is cut. A cadence whose first report has not published yet is a 404.

MCP-only for now

These MCP tools have no REST endpoint yet. Their payloads are the contract, so when an endpoint lands it will answer the way the tool does today.

Tool	Does
`get_markets`, `preview_markets`, `get_brand_family`	Where the workspace is read, what a markets change would cost, and the brand family. See Markets and Brand family

​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

​POST /v1/evidence/query

​GET /v1/deciding-sources

​GET /v1/win-plan

​The receipts

​GET /v1/memory/answers/history

​GET /v1/memory/answers/slice

​GET /v1/memory/citations/timeline

​GET /v1/memory/pages/history

​Track

​POST /v1/prompts

​DELETE /v1/prompts/

​POST /v1/competitors

​DELETE /v1/competitors/

​Automations

​GET /v1/automations

​GET /v1/automations/

​POST /v1/automations

​PATCH /v1/automations/

​POST /v1/automations//runs

​DELETE /v1/automations/

​Inbox

​GET /v1/inbox

​GET /v1/inbox/items/

​POST /v1/inbox/tasks//answer

​POST /v1/inbox/tasks//resolve

​POST /v1/inbox//approve

​POST /v1/inbox//decline

​POST /v1/inbox/asks//approve

​POST /v1/inbox/asks//decline

​Agent

​POST /v1/ask

​GET /v1/sessions/

​Listing, stopping and feeding sessions

​Loop health

​GET /v1/loop-health

​Account

​GET /v1/account

​GET /v1/costs

​GET /v1/ai-traffic/install

​GET /v1/wins

​GET /v1/brief

​PATCH /v1/settings/agents

​GET /v1/github/install-url

​Memory

​POST /v1/observations

​POST /v1/skills

​Set up a workspace

​POST /v1/onboarding/workspace

​POST /v1/onboarding/workspace//confirm

​Goals

​GET /v1/goals

​POST /v1/goals

​PATCH /v1/goals/

​Projects

​GET /v1/work-areas

​GET /v1/work-areas/

​POST /v1/work-areas//steer

​Deliverables

​GET /v1/deliverables

​Reports

​GET /v1/reports/latest

​MCP-only for now

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

POST /v1/evidence/query

GET /v1/deciding-sources

GET /v1/win-plan

The receipts

GET /v1/memory/answers/history

GET /v1/memory/answers/slice

GET /v1/memory/citations/timeline

GET /v1/memory/pages/history

Track

POST /v1/prompts

DELETE /v1/prompts/

POST /v1/competitors

DELETE /v1/competitors/

Automations

GET /v1/automations

GET /v1/automations/

POST /v1/automations

PATCH /v1/automations/

POST /v1/automations//runs

DELETE /v1/automations/

Inbox

GET /v1/inbox

GET /v1/inbox/items/

POST /v1/inbox/tasks//answer

POST /v1/inbox/tasks//resolve

POST /v1/inbox//approve

POST /v1/inbox//decline

POST /v1/inbox/asks//approve

POST /v1/inbox/asks//decline

Agent

POST /v1/ask

GET /v1/sessions/

Listing, stopping and feeding sessions

Loop health

GET /v1/loop-health

Account

GET /v1/account

GET /v1/costs

GET /v1/ai-traffic/install

GET /v1/wins

GET /v1/brief

PATCH /v1/settings/agents

GET /v1/github/install-url

Memory

POST /v1/observations

POST /v1/skills

Set up a workspace

POST /v1/onboarding/workspace

POST /v1/onboarding/workspace//confirm

Goals

GET /v1/goals

POST /v1/goals

PATCH /v1/goals/

Projects

GET /v1/work-areas

GET /v1/work-areas/

POST /v1/work-areas//steer

Deliverables

GET /v1/deliverables

Reports

GET /v1/reports/latest

MCP-only for now