Skip to content
Developer docs
Docs menu

Retrieval

Markdown

Search, context packs, and cited answers over what the key can read.

Answer with citations

POST/v2/retrieval/answer

Answer a question from the evidence context would pick, citing it as [cN]. Needs knowledge:read and knowledge:answer. The model is told when each passage was written and, when known, the date its content is from (occurred_at, else stated_date); for a question about the present state ("now", "currently", "现在"), passages on the same topic are ordered newest first. With stream: true, the 200 response is text/event-stream: x-mirabase-sse-events on this operation names the model of each event's data, and stream on the request describes the order. A generated client keeps the JSON type for the call without stream. Up to answer_concurrency answers (at GET /v2/limits, 3 by default) run at a time per principal, across all of its keys; another waits up to 10 seconds, then returns 429 rate_limited with limit: "concurrency". 502 model_failed and 503 answer_unavailable are worth retrying later. 503 answer_not_configured means this deployment has no answer model, so a retry does not help: build the context and run your own model.

Capability knowledge:read knowledge:answer

Guide: Retrieval and context

Request body

application/json DevAnswerRequest

FieldTypeDescription
questionRequiredstringThe question to answer, 1 to 4000 characters.length 1..4000
space_idsDevSpaceRef[]Space ids; default names your default Space, as it does in a path. Omit to use every Space you can read; a key that can read more than 200 Spaces must name them (returns 422 otherwise).items 1..64
purposeDevContextPurposeWhat the answer is for, as on context: task, coding, research, or audit.
weightsDevContextWeightsAs on context. When you send none, an answer leaves out the changes and skills sources: they name recent files and skills whatever the question is. route.rules_fired then lists source:off:changes:answer_default and source:off:skills:answer_default. Send weights to include them.
tierDevContextTierHow much retrieval work goes into finding the evidence, as on context: fast, standard, or deep.default: "standard"
budget_tokensintegerBudget for the evidence the model reads.500..16000, default: 4000
historyDevAnswerTurn[]Earlier turns, oldest first. A follow-up question is searched together with the question it follows. When the turns add up to more than 12,000 characters, the oldest are left out.max items 10
output_languagestringA BCP 47 tag such as en or zh-CN. Only changes the language of answer.max length 35
filterDevRetrievalFilterNarrow the evidence the answer may draw on, as on context.
includeevidence[]["evidence"] adds evidence to the response: every item the model read, without its text. Use it to see what an answer was based on beyond the passages it cited.items 1..1
streambooleanTrue streams the answer as text/event-stream instead of returning one JSON body. Each event has an id (1, 2, 3, ... in order), an event name, and one line of JSON in data: - start (DevAnswerStreamStart): sent once, after retrieval and before any text. It carries the request_id, the pack_id, and how much evidence the model was given. A stream that fails during retrieval has no start. - delta (DevAnswerStreamDelta): the next piece of the answer. Append the pieces in order. - replace (DevAnswerStreamReplace): sent at most once, directly before final, when the text streamed so far is not the final answer (the service repaired a draft that cited nothing, or the answer became an abstention). Discard the streamed text and show final.answer. - final (DevAnswer): the same JSON this operation returns without stream. It is authoritative. - error (DevErrorResponse): the error envelope an HTTP error would carry; its status is the status the request would have had. Discard the streamed text: no answer was produced. retryable says whether asking again can help. Exactly one of final and error is sent, it is the last event, and the stream closes after it. A stream that ends without either was cut off: treat it as a failed request and ask again. Lines that start with : are comments, sent when the stream opens and whenever it has been idle for 15 seconds; they keep the connection open and carry nothing. A stream cannot be resumed: id shows the order only and Last-Event-ID is ignored. Ignore event names you do not know; more can be added. Closing the connection cancels the answer. Authentication, validation, and the wait for a free slot happen before the stream opens, so those errors are ordinary HTTP responses.
profilestringA retrieval profile declared on this deployment: a named set of these settings (and of the candidate and rerank widths). Fields sent in the request override the profile's. An unknown name is 422. When you send none, a profile the deployment set as the default for the Spaces searched, or for your account, applies.
rerankbooleanfalse skips the reranker: results keep the order of the fused candidates, scores are not relevance, and partial is true when there are results. Cannot be combined with min_score; true cannot be combined with tier fast.
min_scorenumberThe lowest rerank score kept, from 0 to 1. It replaces the service's default relevance floor and also removes lexical matches below it. Hits from the freshness buffer (freshness: pending_index) have no rerank score and are kept. Not applied when reranking failed (partial says so). Needs reranking.0..1
max_per_entryintegerAt most this many passages from one Entry. A hard cap: the places it frees go to other Entries, not to more passages of the same one. On context and answer it applies to search results, not to the files a task names or to recent changes.1..50
reference_timestring (date-time)The moment that relative time in the query ("yesterday", "last week") is counted from. Defaults to now. Send the time of the message when you retrieve on behalf of an older one. On answer it is also the day the model is told is today.
timezonestringIANA time zone of the person asking, such as Asia/Shanghai: it decides which day "yesterday" is. Defaults to the deployment's time zone. An unknown name returns 422.
explainbooleanTrue adds explain to every hit, item or citation and to the response: which branches found it, its position before and after reranking, the query terms it matched, what let it past the relevance floor and which rules moved it. Results and their order are the same with or without it. Costs nothing when left out. Counts, positions and scores cover only candidates you can read: nothing outside your read root, metadata scope or permissions is counted.

Responses

  • 200 application/json DevAnswer, text/event-stream string

Stream events

The events sent when the response is text/event-stream, and the schema of each event's data:

Error statuses

400 401 403 404 409 422 429 500 502 503 504 See Errors for the error shape and Error codes for what each code means.

Example request

curl
curl -X POST "https://api.mirabase.dev/v2/retrieval/answer" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question":"When does version 2.4 launch?","space_ids":["default"]}'

Example response

json
{
  "status": "answered",
  "answer": "Version 2.4 launches on Friday 21 November [c1].",
  "citations": [
    {
      "citation_id": "c1",
      "entry_id": "ent_01JD2M8Z4K",
      "version_id": "ver_01JD2M8Z4M",
      "space_id": "col_01JD2M7QK3",
      "path": "/notes/plan.md",
      "modified_at": "2026-11-17T08:02:00Z",
      "title": "plan.md",
      "source": "knowledge",
      "text": "The launch of version 2.4 moved to Friday 21 November."
    }
  ],
  "evidence_count": 1,
  "pack_id": "trc_01JD2M7R",
  "partial": false,
  "route": {
    "purpose": "task",
    "tier": "standard",
    "rules_fired": [],
    "sources": [
      {
        "source": "knowledge",
        "budget": 4000,
        "used": 38,
        "picked": 1,
        "omitted": 0,
        "why": "matched the question"
      }
    ],
    "unused_tokens": 3962
  }
}

Build context

POST/v2/retrieval/context

The service picks and budgets sources for a task. The result explains its choices in route. Shares the per-principal concurrency limit described on search. When the task asks for a sum, a count, an average, or the largest or smallest value over a table you can read, the service computes it over the whole table by fixed rules, without a model, for up to 3 tables. The result is an item of its own, placed first in its source and citing the table's Entry and version, and route.rules_fired includes table_aggregate:computed. The service computes only when it understands every word of the task and the table suits the calculation; otherwise it records table_aggregate:not_computed:<reason> and still returns the rows as evidence. Rows, cells, and time per request are capped, and past a cap nothing is computed. answer uses the same item. Needs knowledge:read.

Capability knowledge:read

Guide: Retrieval and context

Request body

application/json DevContextRequest

FieldTypeDescription
taskRequiredstringWhat the context is for, in natural language. A task that states several things is searched for each of them.length 1..1000
space_idsDevSpaceRef[]Space ids; default names your default Space, as it does in a path. Omit to use every Space you can read; a key that can read more than 200 Spaces must name them (returns 422 otherwise).items 1..64
purposeDevContextPurposeWhat the context is for (task, coding, research, or audit). Set this to skip intent inference.
weightsDevContextWeightsShift the budget between sources. Omit to use the shares that go with the purpose.
tierDevContextTierfast uses no model and matches words only; standard adds semantic search and reranking; deep looks at twice as many candidates.default: "standard"
budget_tokensintegerCovers the whole response, not only items. With render: "compact" it covers rendered.text instead: the text you put in the prompt.500..16000, default: 4000
have_memory_etagstringOmits memory_view when it still matches memory_view_etag.length 1..128
filterDevRetrievalFilterNarrow what is searched before ranking. Applies to every source that reads Entries; memory_view is not filtered.
rendertext | compacttext adds rendered to the response: the same pack laid out as text you can put in a prompt as it is, with each source under its citation id. Leave it out when you build the prompt from items yourself. compact adds rendered in a shorter layout (one line per source with its origin and one time; a repeated message timestamp inside a conversation passage is written once) and counts budget_tokens and tokens_used on that text instead of on the JSON response, so the same budget holds more evidence. Use it when the text is what your model reads. items still carries every id, time and locator.
profilestringA retrieval profile declared on this deployment: a named set of these settings (and of the candidate and rerank widths). Fields sent in the request override the profile's. An unknown name is 422. When you send none, a profile the deployment set as the default for the Spaces searched, or for your account, applies.
rerankbooleanfalse skips the reranker: results keep the order of the fused candidates, scores are not relevance, and partial is true when there are results. Cannot be combined with min_score; true cannot be combined with tier fast.
min_scorenumberThe lowest rerank score kept, from 0 to 1. It replaces the service's default relevance floor and also removes lexical matches below it. Hits from the freshness buffer (freshness: pending_index) have no rerank score and are kept. Not applied when reranking failed (partial says so). Needs reranking.0..1
max_per_entryintegerAt most this many passages from one Entry. A hard cap: the places it frees go to other Entries, not to more passages of the same one. On context and answer it applies to search results, not to the files a task names or to recent changes.1..50
reference_timestring (date-time)The moment that relative time in the query ("yesterday", "last week") is counted from. Defaults to now. Send the time of the message when you retrieve on behalf of an older one. On answer it is also the day the model is told is today.
timezonestringIANA time zone of the person asking, such as Asia/Shanghai: it decides which day "yesterday" is. Defaults to the deployment's time zone. An unknown name returns 422.
explainbooleanTrue adds explain to every hit, item or citation and to the response: which branches found it, its position before and after reranking, the query terms it matched, what let it past the relevance floor and which rules moved it. Results and their order are the same with or without it. Costs nothing when left out. Counts, positions and scores cover only candidates you can read: nothing outside your read root, metadata scope or permissions is counted.

Responses

Error statuses

400 401 403 404 409 422 429 500 503 504 See Errors for the error shape and Error codes for what each code means.

Example request

curl
curl -X POST "https://api.mirabase.dev/v2/retrieval/context" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task":"Draft the release notes for version 2.4","space_ids":["default"],"budget_tokens":4000}'

Example response

json
{
  "pack_id": "<pack_id>",
  "items": [
    {
      "entry_id": "<entry_id>",
      "version_id": "<version_id>",
      "title": "Launch notes",
      "text": "The launch moved to March 14.",
      "citation_id": "<citation_id>",
      "source": "memory"
    }
  ],
  "route": {
    "purpose": "task",
    "tier": "fast",
    "rules_fired": [
      "<rules_fired>"
    ],
    "sources": [
      {
        "source": "memory",
        "budget": 1,
        "used": 1,
        "picked": 1,
        "omitted": 1,
        "why": "<why>"
      }
    ],
    "unused_tokens": 1
  },
  "tokens_used": 1,
  "budget_tokens": 1,
  "tokenizer": "cl100k_base",
  "omitted": {
    "count": 1,
    "max_score": 1
  },
  "scope_used": {
    "space_ids": [
      "<space_ids>"
    ]
  },
  "partial": false
}

Send context feedback

POST/v2/retrieval/context/{pack_id}/feedback

Report which items of a pack were used. A citation that is not in the pack returns 422 unknown_citation. Needs knowledge:read.

Capability knowledge:read

Guide: Retrieval and context

Parameters

NameInTypeDescription
pack_idRequiredPathDevIdOpaque server-issued identifier. Clients compare it byte for byte.length 1..256

Request body

application/json DevContextFeedbackRequest

FieldTypeDescription
used_citation_idsRequiredstring[]citation_ids from the pack that you actually used. References only, no content. Reports add up: repeating one, or reporting in several calls, is safe.items 1..256

Responses

  • 204 No response body

Error statuses

400 401 403 404 409 422 429 500 503 See Errors for the error shape and Error codes for what each code means.

Example request

curl
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":["<used_citation_ids>"]}'