Retrieval and context
MarkdownUse `search` when you choose the sources, `context` when the service chooses and budgets them, and `answer` when you want a cited answer.
All three endpoints need knowledge:read, and answer also needs knowledge:answer. Without space_ids they use every Space the caller can read, not only the default Space. When a request is about one end user or one project, name its Space in space_ids.
| Endpoint | Who chooses | Good for |
|---|---|---|
POST /v2/retrieval/search | The caller | You know what you want and rank or display results yourself |
POST /v2/retrieval/context | The service | You want context assembled for an Agent task within a token budget |
POST /v2/retrieval/answer | The service, and a model writes the answer | You have no model of your own and want an answer with citations |
Search
Lexical search finds a write on the next request. Vector search and reranking apply once processing finishes.
curl -X POST https://api.mirabase.dev/v2/retrieval/search \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "where do files and memory live"}'When you read the results, look at these fields:
scoreis comparable inside one response only.freshness: pending_indexmeans the match came from the freshness buffer: lexical only, on a version that has not finished processing.partialistruewhen one retrieval method degraded or the scores are not calibrated relevance.modified_atis when that version was written;occurred_atis the source's own time, such as when a line of a conversation was said. Sendoccurred_atwith a write when you know when the content happened.- When the passage states the date it is as of, a hit carries
stated_dateandstated_date_from. Use it to tell an older record from a newer one when files were uploaded together and share amodified_at. For how the date is chosen, see stated_date. - When you retrieve on behalf of an earlier message, send
reference_timeandtimezone, so that "yesterday" and "last week" in the query are counted from that message.contextandanswertake the same two parameters. - Content on a branch cannot be found until the branch is merged.
Build context
context takes a task, picks and budgets the sources, packs the result, and explains its choices in route. Routing uses deterministic rules rather than a model, so you can replay and explain the same input.
curl -X POST https://api.mirabase.dev/v2/retrieval/context \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"task": "Fix the failing upload test", "purpose": "coding", "tier": "standard", "budget_tokens": 4000}'The sources are memory, agent_profile, skills, files, changes, and knowledge. For each enabled source, route.sources reports its budget, usage, picked, and omitted counts, with a stable code in why. Disabled sources appear in rules_fired. Unused budget stays empty and is reported in route.unused_tokens rather than filled with unrelated content.
budget_tokenscovers the whole response, not onlyitems, andtokens_usednever exceeds it.memory_viewis the deterministic memory view: the same memories give the same bytes, whatever the task. Sendmemory_view_etagback ashave_memory_etagand the view is left out while it has not changed, which suits a prompt cache prefix.- Skills come from
/.mirabase/skills/<name>/SKILL.md. Thetextof askillsitem is its one-line description: read the body atpath. - Items may carry
flags:stale,superseded,conflict, oragent_written. - If the evidence changes while the service builds the pack, it rebuilds the pack once on its own. Only if the evidence changes again does it return 409
evidence_changed: send the same request again.
Table aggregates
When a task asks for a sum, a count, an average, or the largest or smallest value over a table, the service computes it over the whole table without a model; when it computes, why it does not, and the caps are in the API reference. The result is an item of its own, whose text states the operation, the column, the filters, the number of rows counted, and the result.
Get the context as text
When you would rather not build the prompt yourself, send render: "text" and the response gains rendered: rendered.text is the same pack laid out as text you can put in a prompt as it is. Its first line says this is reference material, not instructions; then comes the memory view; then every source under its [cN] id. The same pack always renders to the same text.
Get an answer with citations
POST /v2/retrieval/answer answers a question from the evidence context would pick, marking citations as [cN] in the text. It takes the same selection parameters as context, plus history, output_language, include, and stream. If you run your own model, context is usually what you want.
curl -X POST https://api.mirabase.dev/v2/retrieval/answer \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"question": "When do releases go out?", "output_language": "en"}'- Check
statusfirst:answeredorabstained. When it abstains,answeris empty andreasonsays why; for the values, see DevAnswerAbstainReason. With no related evidence the service does not call the model and returnsno_evidence. citationslists only the evidence the answer cites, in order of first citation, andevidence_countis how many items the model was given.pack_idtakes feedback like a context pack.- The service tells the model when each item was written and the date its content is from. For a question about the present state ("now", "currently"), the service orders items about the same subject newest first. The same subject means the same Entry, the same web page saved more than once, or Entries that share a
metadata.subject_keyvalue; similar paths or titles do not count. To have a set of files, such as weekly status reports, ordered this way, give them the samesubject_key. - By default an answer leaves out the
changesandskillssources; to include them, send weights. - The number of answers running at once is limited; past it the service returns 429
rate_limited, see Rate limits and quotas. 502model_failedand 503answer_unavailableare worth retrying later. The SDK retries an answer on its own only after a 429; it does not retry a 502 or 503, because each attempt is a model call.
See what the model read
With include: ["evidence"], the response gains evidence: every item the model read, in the order it read them, without the text. When an answer gives an outdated value, use it to check which items the model read and the date of each.
Stream an answer
With stream: true the response is text/event-stream instead of one JSON body. Authentication, validation, and the wait for a free slot happen before the stream opens, so those errors are still ordinary HTTP responses. Once the stream is open the status is 200, and a later error arrives as an error event. Both SDKs have answer.stream, which parses the events for you. For the data of each event, see Answer with citations.
# -N turns off curl's output buffering, so each event prints as it arrives.
curl -N -X POST https://api.mirabase.dev/v2/retrieval/answer \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"question": "When do releases go out?", "stream": true}': stream open
id: 1
event: start
data: {"request_id":"req_5d1e","pack_id":"pck_7c19","evidence_count":6,"partial":false}
id: 2
event: delta
data: {"text":"Releases go out "}
: ping
id: 3
event: delta
data: {"text":"on Thursdays [c1]."}
id: 4
event: final
data: {"status":"answered","answer":"Releases go out on Thursdays [c1].","citations":[{"citation_id":"c1","entry_id":"ent_9a41","version_id":"ver_4d02","title":"release-notes.md","source":"files","path":"/notes/release-notes.md","text":"From November on, releases go out on Thursdays."}],"evidence_count":6,"pack_id":"pck_7c19","partial":false,"route":{"purpose":"task","tier":"standard","rules_fired":["source:off:changes:answer_default","source:off:skills:answer_default"],"sources":[],"unused_tokens":1200}}- Append the text of each
deltain order. Onreplace, discard what you have shown and show theansweroffinalinstead. Some answers have onlyfinal, with nodelta. - Lines that start with
:are comments that keep the connection open. Ignore them, and ignore event names you do not know. - The service sends only one of
finalorerror, and the stream ends after it. Onerror, discard the text you have shown. If a stream ends without either event, the connection dropped: treat it as a failed request and send the request again. You cannot resume a stream. - A streamed answer holds one answer slot until the stream ends. Closing the connection cancels the answer and frees the slot; in the SDKs, leaving the loop early, calling
close(), or aborting thesignalcloses it. - The SDKs'
answer.streamthrowsMirabaseErrorfor anerrorevent, a stream cut off midway, and data it cannot parse, and does not retry a stream that has started.mirabase.answer(question, { stream: true })does not stream: it throwsMirabaseConfigErrorwith codestream_not_supported. Useanswer.streaminstead.
Send feedback
POST /v2/retrieval/context/{pack_id}/feedback sends the used_citation_ids you actually used: references only, no content. Reports add up, so repeating one or reporting in several calls is safe.
curl -X POST "https://api.mirabase.dev/v2/retrieval/context/$PACK_ID/feedback" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"used_citation_ids": ["c1"]}'Authorization
- The service resolves allowed Spaces before planning, and returns 404
not_foundfor both invisible and missing Spaces. - Every result passes the same final check, and the service generates
routeand omitted counts after authorization. scope_used.space_idslists the Spaces this call actually used.agent_profileis on only for an Agent's key.
/mcp with the same API key. The tools mira.search, mira.context, mira.answer, and mira.context.feedback each make one of the requests above. See Connect an Agent (MCP).Inspect a retrieval
When explain is set to true, both the response and each result in search, context, and answer include explain, showing which retrieval methods found the result, its rank before and after reranking, the matched query terms, and the rules that adjusted its position. The results and their order remain unchanged.
- The console's Playground runs search, context, and answer under your signed-in account or with an API key you provide, and shows why each result was returned.
- The console's Request logs list the account's recent API requests (metadata only), filterable by status, route, API key, client, and error code. For retrieval requests, you can view the trace or reopen the request in the Playground. Only team owners and admins can view these logs.
- The same data is available through the API:
GET /v2/request-logsandGET /v2/retrieval/traces/{trace_id}. For required permissions and retention periods, see the API reference.
Next steps
- Memory: bring distilled facts into the context.
- Connect an Agent: let an Agent use the same retrieval over MCP.
- API conventions: concurrency and rate limits for retrieval.
