REST API endpoint
GET /v1/search — find a prompt, page or session by wording
Full-text search across answers, prompts, pages, sessions and automations in one call, with a hard 400-character cap on every string it returns.
Karl-Gustav Kallasmaa, Founder & CEOLast updated 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 -G https://api.attensira.com/v1/search \
--data-urlencode "q=pricing" --data-urlencode "limit=2" \
-H "Authorization: Bearer atn_live_<your key>"
Parameters
Every parameter the published reference documents, and nothing it does not.
| Name | In | Type | Default | Notes |
|---|---|---|---|---|
| q* | query | string | — | Matched against titles, prompt text, page URLs and answer bodies. |
| limit | query | integer | 20 | Maximum 50. Above that the API refuses rather than silently truncating your intent. |
| offset | query | integer | 0 | For paging. Page on has_more rather than on total. |
The response (200)
Abbreviated, never invented — this is the shape the published reference documents.
{
"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"
}
]
}
What goes wrong, and what it means
The condition on the left, the correct reading of it on the right.
- has_more is true and you stopped reading
- You have one page of matches, not the matches. Page on has_more; total is a floor rather than a grand total, because it counts what matched up to the server's fetch ceiling.
- A hit looks truncated mid-sentence
- It is. Every string on a hit is capped at 400 characters, not only the snippet, so a complete model answer can never come back through this endpoint at all.
- Exact prompt text finds nothing
- Search is for locating something by wording. If you already have the exact text, GET /v1/prompts/{prompt} accepts it directly and saves the round-trip.
What this endpoint cannot tell you
The limits are part of the answer, not a disclaimer under it.
- It cannot return a full model answer. Every string on a hit is capped at 400 characters, so the complete text of an answer is only reachable by fetching the session it belongs to.
- The total it reports is not a count of everything that matches. It is how many items matched up to the server's fetch ceiling, which makes it a floor to page against rather than a number to put in a report.
Search is the endpoint you call when you know roughly what something was called and not what its identifier is. It runs one full-text pass across five different kinds of record — prompts, answers, pages, sessions and automations — and hands back a flat list of hits, each carrying the type of thing it is, its id, and a short excerpt showing why it matched.
That flat shape is the point. Most APIs make you know which collection to look in before you can look, which is fine for a program and hopeless for a person who remembers only that somebody once tracked something about pricing. Here you send the word and sort out what kind of thing it was afterwards.
What the type field is for
Every hit names its own type, and that name tells you which endpoint can fetch the whole record. A prompt hit is opened with the single-prompt endpoint, a page hit with the pages endpoint, a session hit with the sessions endpoint, and an automation hit with the automations endpoint. Search is deliberately shallow; the depth is one call away, and which call it is comes back in the response rather than being something you have to work out.
The cap you have to design around
The single most important fact about this endpoint is that everything it returns is short. The excerpt is short because it is an excerpt, but so is every other string on the hit, and the limit is the same 400 characters in each case. There is no parameter that raises it and no combination of arguments that gets around it.
That means one whole category of use is off the table. You cannot page through search results to reconstruct what a model said, you cannot grep the corpus by issuing enough queries, and any pipeline built on the assumption that a long enough answer will eventually come back through here will quietly truncate its own input. Full text lives on the session, and the session endpoint is where you go to get it.
Reading this as a limitation is the wrong frame. It is a search index, and an index that returned whole documents would be a slower, more expensive version of the endpoints that already return whole documents.
Paging without lying to yourself
Two fields describe the size of the result and only one of them is safe to quote. has_more is a fact: there is another page or there is not, and it is the field your loop should read. total is the count of what matched up to the point where the server stopped fetching, which makes it a lower bound. It is genuinely useful for deciding whether a query was too broad, and genuinely wrong to put in a report as the number of things that match.
Combine limit and offset in the ordinary way. The maximum for limit is fifty, and asking for more is refused rather than silently reduced, which is the better behaviour — a caller that asked for two hundred and got fifty without being told would go on to draw conclusions from a fifth of the data.
When to skip search entirely
If you already have the exact wording of a prompt, you do not need this endpoint at all: the single-prompt endpoint accepts the prompt's text in place of its id, percent-encoded. That turns two calls into one. Search earns its place when the wording is approximate, when you are not sure which kind of record you are looking for, or when you are exploring a workspace you did not set up yourself.
Its twin on the other surface
Everything above is equally true of the search MCP tool, which is the same capability exposed to an assistant instead of to your code. The only difference worth remembering is the name of the first argument: the REST endpoint takes q, the tool takes query. Pick the surface by who is making the call — your own software, or an assistant working on somebody's behalf — rather than by capability, because the capability is identical.
Questions people ask
- Why is the snippet cut off?
- Because every string on a hit is capped at 400 characters, not just the snippet field. That cap is deliberate and there is no parameter that lifts it — a complete model answer is fetched from its session, never from search.
- Is total the number of matching items?
- No. It counts what matched up to the server's fetch ceiling, so treat it as a floor. Page on has_more instead, which tells you whether another page exists.
- How do I turn a hit into a full record?
- Read its type. A prompt hit is fetched with GET /v1/prompts/{prompt}, a page hit with GET /v1/pages, a session hit with GET /v1/sessions/{id}, and an automation hit with GET /v1/automations/{id}.
- Does searching cost credits?
- No. Search is read-only and spends nothing. Only adding prompts, running an automation on demand and asking the agent spend credits.
- What is the MCP equivalent?
- The search tool, which takes query rather than q and is otherwise the same call with the same 400-character cap.
Sources
Every factual statement above, with the page it came from and the date that page was read.
The Attensira API reference states that every string on a search hit is capped at 400 characters, not only the snippet, and that a full answer must be fetched from its session.
docs.attensira.com · retrieved
“Every string on a hit is capped at 400 characters, not just snippet.”
The API reference states that the total returned by search is how many items matched up to the server's fetch ceiling — a floor, not a grand total — and that callers should page on has_more.
docs.attensira.com · retrieved
“total is how many items matched up to the server's fetch ceiling — a floor, not a grand total.”