For the complete documentation index, see llms.txt. Every page on this site is also served as Markdown: append `.md` to any URL, or send `Accept: text/markdown`.
Attensira Logo
Attensira

REST API endpoint

POST /v1/prompts — start tracking, and what it costs

Adds one or more prompts to the workspace so each is read across every platform the plan includes, from the next daily run onward. Spends credits.

Karl-Gustav KallasmaaKarl-Gustav Kallasmaa, Founder & CEOLast updated
POST /v1/promptsNeeds write scopeSpends creditsMCP tool: add_prompts

The request

Paste this and change the key. Every endpoint takes a bearer key and none takes a workspace id — the key names the workspace.

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

Parameters

Every parameter the published reference documents, and nothing it does not.

NameInTypeDefaultNotes
prompts*bodystring[]—One or more prompt texts, none blank.
topicbodystring—Optional. The topic to file them under, created if it does not already exist.
countrybodystring—Optional ISO 3166-1 alpha-2 code. Defaults to the workspace's country.

The response (201)

Abbreviated, never invented — this is the shape the published reference documents.

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

What goes wrong, and what it means

The condition on the left, the correct reading of it on the right.

A prompt appears under skipped rather than added
It was not added and it did not cost anything. The usual reason is that the workspace already tracks that exact text, and the response says which reason applied per prompt.
credits_spent comes back null
Your plan does not meter this action. It is not a failure and it is not a free call by accident — some plans simply do not bill it.
The call succeeds and no data appears
Nothing is read retroactively. A prompt added today produces its first readings on the next workspace-local calendar day, so an empty result an hour later is expected.

What this endpoint cannot tell you

The limits are part of the answer, not a disclaimer under it.

  • There is no platform field, so this call cannot choose which surfaces a prompt runs on. Which platforms a prompt is read across comes from the plan, and the account endpoint is the only authority on what that list contains.
  • It cannot backfill. Adding a prompt starts collection from the next run onward and produces nothing about the past, so a prompt added to explain last month's drop will not explain last month's drop.

This is one of the three endpoints in the API that spends money, and the only one that changes what gets measured. You send it prompt texts; from the next run it reads each of them across every platform your plan includes and starts building history.

The response is a per-prompt result, not a status

The most useful thing about the reply is that it splits. Prompts that were created come back under added with their new ids. Prompts that were not come back under skipped, each with a reason — most often that the workspace already tracks that exact text. A partially successful call is therefore a normal outcome rather than an error, and the correct way to read the result is per prompt rather than per request.

Credit fields sit alongside. They report what this call spent and what remains, and both are null on a plan that does not meter the action. A null there is not a failure and not a free call by accident; it is a plan that does not bill this.

There is no platform argument, on purpose

You cannot ask for a prompt to be read only on one surface. The set of platforms a prompt runs on comes from the plan, and the request has no say in it. That design removes a whole class of confusing state — a prompt that is tracked but somehow not on the surface you were looking at — and it means the account endpoint is the single authority on which surfaces were ever queried.

It also means the useful sanity check before a bulk import is a read, not a write: fetch the account, look at the plan's platform list, and know in advance which surfaces the prompts you are about to add will be read on.

Nothing happens immediately

Adding a prompt starts collection going forward. It does not reach backwards, and it cannot: the readings for last month were either taken or they were not. A prompt added today produces its first data on the next workspace-local calendar day, because each prompt runs at most once per platform per country per day.

This matters for the most common reason people add prompts, which is that something went wrong and they want to understand it. Adding the prompt is the right move for next month and does nothing for last month, and an integration that adds a prompt and then polls for an explanation will poll for a day and find nothing.

Topics and countries

Both optional fields are quietly load-bearing. A topic is created on first use, which makes it cheap to organise a batch at the point of import rather than retrofitting it later — and the topic rollup in analytics is only as useful as the topics you actually assigned. The country defaults to the workspace's own, and setting it explicitly matters whenever you are tracking a market you do not sit in, because the answers models give differ by country.

Cost discipline

Because this endpoint bills, it is worth treating a bulk import as a deliberate act rather than a sync. Two habits help. First, deduplicate before you send: the skipped list means a duplicate is harmless, but a job that re-sends its whole prompt list every night is doing work to be told nothing changed. Second, read the plan's prompt ceiling before importing, because holding prompts is capped and the way to free a slot is to remove one.

Its twin on the other surface

The add_prompts MCP tool takes the same three arguments, needs the write scope, and spends credits the same way. Where the surfaces genuinely differ is in who is deciding: an assistant with write access can add prompts on its own initiative, and that is a workspace credential rather than a read token.

Questions people ask

How many credits does adding a prompt cost?
The response tells you, per call, in credits_spent and credits_remaining. Both come back null on a plan that does not meter the action, and prices are not restated here because the plan ladder is the only place they are correct.
Can I choose which platforms a new prompt runs on?
No. There is no platform field on this endpoint. The surfaces come from your plan, which you can read from GET /v1/account.
What happens if I send a prompt that is already tracked?
It comes back under skipped with a reason, and it is not charged. The call as a whole still succeeds.
When does a new prompt produce data?
From the next workspace-local calendar day. Each prompt runs at most once per platform per country per day, so there is nothing to see immediately.
Is there a limit on how many prompts I can hold?
Yes, and it comes from the plan rather than from this endpoint. Removing a prompt frees its slot.

Sources

Every factual statement above, with the page it came from and the date that page was read.

  1. The Attensira API reference states that there is no platform field on POST /v1/prompts, and that which surfaces a prompt runs on comes from the plan rather than from the request.

    docs.attensira.com · retrieved

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

  2. The API reference states that from the next daily run, each added prompt is read across every platform the plan includes.

    docs.attensira.com · retrieved

    “From the next daily run, each is read across every platform your plan includes.”

Next

The reference this is written from →Every endpoint →The same capability over MCP →