Skip to content
Developer docs
Docs menu

Schemas

Markdown

The data structures used by requests and responses, generated from the OpenAPI document.

DevAccountQueue

Your account's processing queue: the jobs that turn what you wrote into searchable content (parse, index, publish, and the index projection) and the model work after it (summaries, classification, memories). Counts are jobs, not files; one file is several jobs. For one file use GET /v2/entries/{entry_id}/processing.

FieldTypeDescription
queuedRequiredintegerJobs waiting: due ones plus delayed ones.
dueRequiredintegerJobs that can run now and wait for a worker.
delayedRequiredintegerJobs waiting for a retry backoff or a scheduled time.
runningRequiredinteger
pausedRequiredbooleanTrue when the service operator paused processing for this account; nothing runs until it is resumed.
paused_atstring (date-time)
oldest_queued_secondsintegerHow long the oldest due job has been waiting. Absent with nothing due.
eta_secondsintegerEstimated seconds until the due jobs are done, from the service's throughput over the last 15 minutes and this account's fair share of it. An estimate: absent while paused or when there is no recent throughput to go by.
limitRequiredintegertenant_queued_jobs: past this many queued jobs that make content searchable (parsing, recognition, indexing, publishing), writes get 429 ingest_backlog. Summaries, classification, relations and memories queued after a file is searchable count against their own limit of five times this number, so queued can be above limit while writes are accepted.
as_ofRequiredstring (date-time)

DevActivityActor

What one principal changed in the period.

FieldTypeDescription
principal_idDevIdWho made the changes. Absent for changes the service made itself.
last_changed_atRequiredstring (date-time)When this principal last changed something.
change_countRequiredintegerHow many changes this principal made in the period.
filesRequiredDevActivityFile[]The Entries changed, most recently changed first, at most 50.
files_truncatedtruePresent and true when the principal changed more than 50 Entries: files has the 50 latest.

DevActivityFile

One Entry a principal changed in the period, as its latest change left it.

FieldTypeDescription
entry_idRequiredDevIdThe Entry that changed.
pathDevPathWhere it was at its latest change. Absent for an Entry without a path.
opRequiredDevChangeOpThe latest change: create, update, move, delete, or restore.
version_idDevIdThe version the latest change wrote, when it wrote one.
changed_atRequiredstring (date-time)When the latest change was committed.
change_countRequiredintegerHow many times this principal changed the Entry in the period.

DevAnswer

FieldTypeDescription
statusRequiredDevAnswerStatusanswered, or abstained when the evidence did not support an answer.
answerRequiredstringEmpty when abstained. Cites evidence as [cN].
reasonDevAnswerAbstainReasonPresent when abstained.
citationsRequiredDevAnswerCitation[]Only the evidence answer cites, in order of first citation.
evidenceDevAnswerEvidence[]Only when the request has include: ["evidence"]: every item the model read, in the order it read them.
evidence_countRequiredintegerItems the model was given.
pack_idRequiredDevIdReport what you used with POST /v2/retrieval/context/{pack_id}/feedback.
partialRequiredbooleanTrue when a retrieval branch degraded, so evidence may be missing.
pending_processingDevPendingProcessingOnly when Entries in the searched Spaces are still being processed: the answer may lack them.
routeRequiredDevContextRouteHow the evidence was chosen, as on a context pack.
explainDevAnswerExplainOnly when the request set explain.

DevAnswerAbstainReason

no_evidence: nothing to cite, the model was not called. model_abstained: the evidence does not answer it. insufficient_evidence: the answer cited nothing even after one repair.

Values: no_evidence | model_abstained | insufficient_evidence

DevAnswerCitation

FieldTypeDescription
citation_idRequiredstringAppears as [cN] in answer.
entry_idRequiredDevIdThe Entry the passage is from.
version_idRequiredDevIdThe version the passage was read from.
space_idDevIdThe Space of that Entry. Absent on account memory.
pathDevPathThe file's path. Absent for an Entry without one.
urlstringOn an Entry ingested from a URL: that URL, to link back to the page. A file has path instead.
occurred_atstring (date-time)When what the passage describes happened: the Entry's occurred_at, or for a conversation the time of its messages. Absent when the source has none.
modified_atstring (date-time)When the version the passage was read from was written. With occurred_at it tells old from new.
stated_datestring (date)The date the passage is stated as of, YYYY-MM-DD. Only fully written dates (year, month, and day) count, and a date mentioned in the middle of a sentence never does: "since 2026-03-01 the API runs on cluster B" is a statement about the present, not about 2026-03-01. The first of these wins: a date the passage marks as its own ("as of", "updated", "last modified", "截至", "更新于" before it, or "updated" / "更新" after it); the date in the heading of its section; a date that starts a line, list item, or clause of the passage; the date in the document's front matter (modified, updated, date, created) or top heading. Where one of them holds several dates, the latest that is not after the version was written is used. Absent when none of them has one: no date is given rather than a wrong one. It tells an older record from a newer one when several files were written at the same moment; when occurred_at is present, prefer that.
stated_date_fromtext | heading | documentWhere stated_date was read: the passage text, a section heading above it, or the document head.
titleRequiredstringThe Entry's title; for a file, its name.
sourceRequiredDevContextSourceWhich context source supplied the passage.
textRequiredstringThe passage the model read.
explainDevHitExplainOnly when the request set explain.

DevAnswerEvidence

One item the model read, as a citation without its text.

FieldTypeDescription
citation_idRequiredstringThe id the model could cite it by.
entry_idRequiredDevIdThe Entry the passage is from.
version_idRequiredDevIdThe version the passage was read from.
space_idDevIdThe Space of that Entry. Absent on account memory.
pathDevPathThe file's path. Absent for an Entry without one.
urlstringOn an Entry ingested from a URL: that URL.
occurred_atstring (date-time)As on a citation.
modified_atstring (date-time)As on a citation.
stated_datestring (date)As on a citation.
stated_date_fromtext | heading | documentAs on a citation.
titleRequiredstringThe Entry's title; for a file, its name.
sourceRequiredDevContextSourceWhich context source supplied the passage.
explainDevHitExplainOnly when the request set explain.

DevAnswerExplain

explain on an answer: the retrieval summary, plus which citations each sentence uses.

FieldTypeDescription
termsRequiredstring[]The terms the lexical branch searched for.
candidatesRequiredDevExplainCandidateCount[]Candidates per branch, counting only those you can read. Branches that returned nothing you can read are left out.
fused_countRequiredintegerCandidates you can read after the branches were merged.
rerankRequiredDevExplainRerankSummary
clausesstring[]For a task that states several things: the clauses that were searched for separately.
sentencesRequiredDevAnswerSentence[]The answer split into sentences. Empty when the answer abstained.

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.

DevAnswerSentence

FieldTypeDescription
textRequiredstringOne sentence of answer, with its [cN] marks.
citation_idsRequiredstring[]The citations in that sentence, in order of first mention.

DevAnswerStatus

Values: answered | abstained

DevAnswerStreamDelta

data of a delta event of a streamed answer.

FieldTypeDescription
textRequiredstringThe next piece of the answer. Append it to the pieces before it.

DevAnswerStreamReplace

data of the replace event of a streamed answer: an empty object. The text streamed so far is void.

Values: object

DevAnswerStreamStart

data of the start event of a streamed answer: what is known once retrieval is done, before any text.

FieldTypeDescription
request_idRequiredstringThe request's id, the same as the X-Request-Id response header. Quote it when you report a problem.
pack_idRequiredDevIdThe same pack_id the final event carries.
evidence_countRequiredintegerItems the model is given. 0 means the answer will be an abstention with reason no_evidence.
partialRequiredbooleanTrue when a retrieval branch degraded, so evidence may be missing.
evidenceDevAnswerEvidence[]Only when the request has include: ["evidence"]: every item the model reads, the same list final carries.

DevAnswerTurn

FieldTypeDescription
roleRequireduser | assistantWho said it: user or assistant.
contentRequiredstringWhat was said, 1 to 4000 characters.length 1..4000

DevApiKey

A credential, not a principal. It can only narrow what its principal may do.

FieldTypeDescription
idRequiredDevIdStarts with key_. Not the secret: the token is shown once, when the key is created or rotated.
principal_idRequiredDevIdThe principal the key acts as.
nameRequiredstringYour label for the key.
prefixRequiredstringNon-secret token prefix, for recognizing a key in a list.
capabilitiesRequiredDevCapability[]What the key may do. Never more than its principal's capabilities.
allowed_space_idsDevId[]Absent means not narrowed to specific Spaces.
metadata_scopeDevMetadataScopeThe metadata scope the key is limited to. Absent means not limited by metadata.
expires_atstring (date-time)After this time the key stops working. Absent when it does not expire.
revoked_atstring (date-time)When the key was revoked. Absent while it is live.
last_used_atstring (date-time)When the key last called the API, to within a minute. Absent until its first call.
created_byRequiredDevIdThe principal that issued it.
issued_by_key_idDevIdThe key that issued or rotated this one. Absent when no key was used.
created_atRequiredstring (date-time)When it was issued.

DevApproveProposalRequest

FieldTypeDescription
messagestringBecomes the new version's message. At most 120 characters.max length 120

DevArchive

An export's archive. Deleted after expires_at, or as soon as a file in the Space is purged.

FieldTypeDescription
size_bytesRequiredintegerSize of the archive in bytes.
sha256RequiredstringHex SHA-256 of the archive.
media_typeRequiredstringapplication/x-tar.
expires_atRequiredstring (date-time)When the archive is deleted.

DevArchiveUrl

A short-lived signed URL for an export's archive. Anyone holding it can fetch it until expires_at, and revoking the key does not stop that: treat it like the key.

FieldTypeDescription
urlRequiredstring (uri)The signed URL. Fetch it with a plain GET.
methodRequiredGETAlways GET.
expires_atRequiredstring (date-time)UTC. At most 5 minutes after the request.
job_idRequiredDevIdlength 1..256
size_bytesRequiredintegerSize of the archive in bytes.
media_typeRequiredstringapplication/x-tar. The response carries it with Content-Disposition: attachment and Cache-Control: private, no-store.
sha256RequiredstringHex SHA-256 of the archive.

DevAuditEvent

Identifiers only. Audit events never contain user content.

FieldTypeDescription
idRequiredDevIdlength 1..256
actionRequiredstringStable action name, such as entry.read, acl.set, or api_key.revoke.
outcomeRequiredDevAuditOutcomeHow the action ended: allowed, denied, or failed.
principal_idRequiredDevIdThe principal that acted.
key_idDevIdAbsent when the request was not authenticated with an API key.
space_idDevIdAbsent when the action has no single Space.
resource_kindRequiredstringWhat was acted on: entry, version, recall, tenant, tool, api_key, memory, principal, space, branch, proposal, snapshot, webhook, job, dream, or developer_account. New kinds can be added.
resource_idDevIdFor entry and version this is the Entry id; version_id names the version.
version_idDevIdlength 1..256
request_idstringThe request that caused the event, the same id error bodies carry as request_id.
created_atRequiredstring (date-time)When the event was recorded.

DevAuditOutcome

Values: allowed | denied | failed

DevBacklog

The account's processing queue when it is full.

FieldTypeDescription
queuedRequiredintegerJobs of the kind that reached its limit queued for the account. For a key limited to some Spaces or to metadata, the limit.
limitRequiredintegertenant_queued_jobs when jobs that make content searchable (parsing, recognition, indexing, publishing) are full; five times it when summaries, classification, relations and memories are.
pausedRequiredbooleanTrue when the service operator paused processing for the account: waiting does not help until it is resumed. Always false for a key limited to some Spaces or to metadata.
eta_secondsintegerEstimated seconds until the account's due jobs are done. Absent when it cannot be estimated, and for a key limited to some Spaces or to metadata.

DevBranch

A copy-on-write layer over a Space. Reads check the branch first and fall through to the latest main version, so a path the branch never touched shows main as it is now, not as it was when the branch opened. Content on a branch is not parsed, indexed, or turned into memories, and search and context do not see it until it is merged.

FieldTypeDescription
idRequiredDevIdlength 1..256
space_idRequiredDevIdlength 1..256
nameRequiredstringThe branch's name. While the branch is active, paths and ?branch= take it in place of the id.
stateRequiredDevBranchStateabandoned also covers a branch past expires_at that the sweep has not reached yet.
parent_branch_idDevIdAbsent when the branch started from main. Nodes were copied: there is no parent chain.
base_change_seqRequiredintegerMain's change sequence when the branch opened.
main_changed_pathsRequiredintegerHow many paths main changed since base_change_seq. Paths the branch did not touch drift with main; this is how you see that. Events are kept 90 days, so the number can undercount.
created_byRequiredDevIdlength 1..256
ttl_daysRequiredintegerHow many days each write pushes expires_at out by.
expires_atRequiredstring (date-time)When the branch expires. Past this time the branch is abandoned, then reclaimed.
created_atRequiredstring (date-time)When the branch was opened.
updated_atRequiredstring (date-time)When the branch was last changed.

DevBranchChange

The branch's view of what changed. source: branch entries are compacted, one per path with the latest write, so treat them as paths to re-read. source: main entries are main changes this branch reads through. seq is per source.

FieldTypeDescription
sourceRequiredbranch | mainbranch: a change made on this branch. main: a change on main that this branch reads through.
seqRequiredintegerSequence number within its source.
opRequiredDevChangeOpThe kind of change: create, update, move, delete or restore.
pathDevPathlength 1..4096
kindDevBranchNodeKindOn a branch change: whether the path is a directory, a file, or a symlink.
entry_idDevIdlength 1..256
version_idDevIdlength 1..256
actor_principal_idDevIdlength 1..256
created_atRequiredstring (date-time)When the change was made.

DevBranchChangeFeed

FieldTypeDescription
dataRequiredDevBranchChange[]The events of this page.
cursorRequiredDevCursorPass back to continue.
has_moreRequiredbooleanTrue when more events are ready: call again with cursor right away.

DevBranchDiffItem

One changed path, compared with the version main had when this branch first touched it.

FieldTypeDescription
pathRequiredDevPathlength 1..4096
changeRequiredDevBranchDiffOpWhether the branch added, modified, or deleted the path.
kindRequiredDevBranchNodeKindWhat the path is on the branch: a directory, a file, or a symlink.
sizeintegerFor a file: the size of the branch's content in bytes.
mode644 | 755For a file: 644 or 755.
sha256stringFor a file: hex SHA-256 of the branch's content.
base_version_idDevIdlength 1..256
unified_diffstringText files only. Empty when the bytes differ only in a way line comparison cannot see.
diff_omittedtoo_largeSet when a text file's diff was too large to compute.

DevBranchDiffOp

Values: added | modified | deleted

DevBranchFileDeletion

FieldTypeDescription
branch_idRequiredDevIdlength 1..256
pathRequiredDevPathlength 1..4096
deletedRequiredtrueAlways true: the path is now hidden on the branch.

DevBranchFileMeta

view=meta on a path the branch changed. Paths read through to main return the Entry.

FieldTypeDescription
branch_idRequiredDevIdlength 1..256
pathRequiredDevPathlength 1..4096
kindRequiredfile | symlinkWhether the path is a file or a symlink on the branch.
sizeintegerFiles only: size in bytes.
media_typestringFiles only: the media type the file was written with.
mode644 | 755Files only: 644 or 755.
sha256stringFiles only: hex SHA-256 of the content.
etagstringFiles only: send it in If-Match on the next write. It is a content hash, not a version.
updated_atRequiredstring (date-time)When the branch last changed this path.

DevBranchFileText

view=text on a path the branch changed. Only text files have it: branches are not parsed.

FieldTypeDescription
branch_idRequiredDevIdlength 1..256
pathRequiredDevPathlength 1..4096
viewRequiredtextAlways text.
textRequiredstringThe file's content as UTF-8 text.

DevBranchFileWrite

Result of writing a file to a branch. Its etag is a content hash, not a version.

FieldTypeDescription
branch_idRequiredDevIdlength 1..256
pathRequiredDevPathlength 1..4096
sha256RequiredstringHex SHA-256 of the bytes written.
sizeRequiredintegerSize in bytes.
media_typeRequiredstringThe media type stored with the file.
modeRequired644 | 755644 or 755.
etagRequiredstringThe file's ETag on the branch, with quotes. Send it in If-Match on the next write.
version_idRequiredstringThe etag without quotes. changes?branch= reports this write under the same version_id.
createdRequiredbooleanTrue when nothing was at the path before this write, false when it replaced a file.
changedRequiredbooleanFalse when the bytes, media type, and mode are unchanged.

DevBranchNodeKind

Values: dir | file | symlink

DevBranchObject

An object stored in a branch.

FieldTypeDescription
branch_idRequiredDevIdlength 1..256
sha256RequiredstringHex SHA-256 of the object, which is also the name it is stored under.
sizeRequiredintegerSize in bytes.
createdRequiredbooleanFalse when this branch already held the object.

DevBranchRef

A branch id, or the name of an active branch. An id starts with brn_. Prefer the id in anything that retries: a name can move to another branch once the first one closes.

Values: string

DevBranchState

Where a branch is. active: open for writes. merged: written into main, and read-only. abandoned: closed without a merge. A merged or abandoned branch is reclaimed branch_reclaim_days after it ends.

Values: active | merged | abandoned

DevCapability

What a key may do. A request acts with the capabilities its key and its principal both hold (effective_capabilities on GET /v2/whoami). Each live operation names the one it needs in x-mirabase-capability. - knowledge:read: read Spaces, files, Entries, memories, and the change feed, and call search and context. - knowledge:answer: call POST /v2/retrieval/answer, together with knowledge:read. - knowledge:write: write, edit, trash, and restore files and Entries; ingest and upload; work on branches and snapshots; decide proposals; write an Agent's own memory; close or forget a distilled memory. - knowledge:manage: create, change, and delete Spaces and their members, erase Entries for good, and manage webhooks. - memory:confirm: write, review, correct, and undo confirmed memories. A conversation ingested with it distills confirmed memories instead of candidates. - memory:candidate: can be granted, but no /v2 operation requires it.

Values: knowledge:read | knowledge:answer | knowledge:write | knowledge:manage | memory:candidate | memory:confirm

DevChange

One change to a file or other Entry. Directories produce no events of their own: moving one gives one move per file inside it. path is where the Entry was at the time, and is absent when it has none or after a purge. Events can repeat, so apply them by entry_id.

FieldTypeDescription
seqRequiredintegerThe event's position in the Space's change feed. Numbers follow commit order with no gaps.
opRequiredDevChangeOpThe kind of change: create, update, move, delete or restore.
entry_idRequiredDevIdlength 1..256
pathDevPathlength 1..4096
version_idDevIdlength 1..256
actor_principal_idDevIdlength 1..256
created_atRequiredstring (date-time)When the change was committed.

DevChangeFeed

One page of the change feed. It uses cursor rather than next_cursor.

FieldTypeDescription
dataRequiredDevChange[]The events of this page, in commit order.
cursorRequiredDevCursorPass back to continue. Sequence numbers follow commit order with no gaps.
has_moreRequiredbooleanTrue when more events are ready: call again with cursor right away.

DevChangeOp

What changed. create: a new Entry. update: a new version, or a return to the previous version after an edit failed processing. move: a new path; path is the new one. delete: moved to the trash or erased. restore: brought back from the trash.

Values: create | update | move | delete | restore

DevCheckpoint

The branch's own changes at one moment. Paths read through to main are not pinned. Listed newest first.

FieldTypeDescription
idRequiredDevIdlength 1..256
branch_idRequiredDevIdlength 1..256
nameRequiredstringThe name it was given when it was created.
gitDevCheckpointGit
node_countRequiredintegerChanged paths this checkpoint holds.
created_byRequiredDevIdlength 1..256
created_atRequiredstring (date-time)When the checkpoint was taken.

DevCheckpointGit

Stored and returned as sent, at most 4 MiB. The keys belong to the client that wrote them, the mirabase CLI. One rule applies: a top-level remote_url must not contain credentials.

Values: object

DevCompleteUploadRequest

FieldTypeDescription
partsRequiredDevCompletedPart[]Every part of the file, each with the ETag its PUT returned.min items 1
session_idstringYour id for the conversation this file came from, as on PUT files?session_id=: it is recorded on the version this completion creates and shown by lineage. Main only: returns 422 on a branch upload.length 1..256
occurred_atstring (date-time)When the file's content occurred, such as when a recording was captured. Retrieval's occurred_from and occurred_to filters use it, and passages report it; without it, they use the time the file was written.
metadataDevMetadataReplaces the Entry's metadata as a whole, as metadata does on PATCH /v2/entries/{id}. Retrieval's filter.metadata matches it.
memory_excludebooleantrue keeps the file out of memory distillation: it is stored, indexed, and searchable, and nothing is distilled from it. false distills it again. The same switch as memory_exclude on PATCH /v2/entries/{id}.

DevCompletedPart

FieldTypeDescription
part_numberRequiredintegerThe part's number, from 1.>= 1
etagRequiredstringThe ETag header from that part's PUT.

DevContentUrl

A short-lived signed URL for the original bytes. Anyone holding it can fetch them until expires_at, and revoking the key does not stop that: treat it like the key. The URL has no file name in it.

FieldTypeDescription
urlRequiredstring (uri)The signed URL. Fetch it with a plain GET.
methodRequiredGETAlways GET.
expires_atRequiredstring (date-time)UTC. At most 5 minutes after the request.
entry_idRequiredDevIdlength 1..256
version_idRequiredDevIdlength 1..256
size_bytesRequiredintegerSize of the original in bytes.
media_typeRequiredstringThe response carries this Content-Type, Content-Disposition: attachment, and Cache-Control: private, no-store.
sha256stringHex SHA-256 of the original bytes, when known.

DevContentView

Values: text | table | recognized

DevContextChange

FieldTypeDescription
opRequiredcreate | update | move | restorecreate, update, move, or restore.
atRequiredstring (date-time)UTC, microsecond precision.

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

DevContextFlag

FieldTypeDescription
typeRequiredstale | superseded | conflict | agent_writtenstale, superseded, conflict, or agent_written.
citation_idstringOn conflict: the item that disagrees with this one.
grant_idstringOn agent_written.

DevContextItem

FieldTypeDescription
entry_idRequiredDevIdlength 1..256
version_idRequiredDevIdlength 1..256
space_idDevIdlength 1..256
titleRequiredstringTitle of the Entry the passage is from.
textRequiredstringA passage. For skills, the one-line description: read the body at path.
citation_idRequiredstringIdentifies this item within the pack, such as c1. Report the items you used by it in feedback.
sourceRequiredDevContextSource
pathDevPathlength 1..4096
urlstringOn an Entry ingested from a URL: that URL, to link back to the page. A file has path instead.
occurred_atstring (date-time)When what the passage describes happened: the Entry's occurred_at, or for a conversation the time of its messages. Absent when the source has none.
modified_atstring (date-time)When the version the passage was read from was written. With occurred_at it tells old from new.
stated_datestring (date)The date the passage is stated as of, YYYY-MM-DD. Only fully written dates (year, month, and day) count, and a date mentioned in the middle of a sentence never does: "since 2026-03-01 the API runs on cluster B" is a statement about the present, not about 2026-03-01. The first of these wins: a date the passage marks as its own ("as of", "updated", "last modified", "截至", "更新于" before it, or "updated" / "更新" after it); the date in the heading of its section; a date that starts a line, list item, or clause of the passage; the date in the document's front matter (modified, updated, date, created) or top heading. Where one of them holds several dates, the latest that is not after the version was written is used. Absent when none of them has one: no date is given rather than a wrong one. It tells an older record from a newer one when several files were written at the same moment; when occurred_at is present, prefer that.
stated_date_fromtext | heading | documentWhere stated_date was read: the passage text, a section heading above it, or the document head.
is_current_versionfalsePresent and false when a newer version than this one is live.
flagsDevContextFlag[]Absent when there are none.
freshnesspending_indexpending_index means the item came from the freshness buffer, lexically only.
memory_kindstringOn memory items.
changeDevContextChangeOn changes items.
memoryDevRoutedMemoryOnly on deployments with evidence-based memory enabled: the confirmed memory distilled from this passage. At most one per file in a response. It counts toward tokens_used.
explainDevHitExplainOnly when the request set explain. Not counted in tokens_used.

DevContextOmitted

FieldTypeDescription
countRequiredintegerHow many qualifying passages were left out.
max_scoreRequirednumber | nullThe best score among them, or null when there is none to report.

DevContextPurpose

Values: task | coding | research | audit

DevContextRendered

The pack as text, when the request set render.

FieldTypeDescription
textRequiredstringA first line that says this is reference material, then the memory view (when the pack has one) and every item under its [cN] id with where it came from, its times, and what to watch for (an older version, a value that was replaced). Same pack, same text, byte for byte. Nothing is added or left out.
tokensRequiredintegertext counted with the pack's tokenizer. With render: "text" it is not part of tokens_used: it is a second form of the same content. With render: "compact" it equals tokens_used.

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.

DevContextResponse

FieldTypeDescription
pack_idRequiredDevIdNames this pack. Report what you used with POST /v2/retrieval/context/{pack_id}/feedback.
memory_view_etagstringSend it back as have_memory_etag. Absent when the memory source was off or the view did not fit.
memory_viewDevMemoryViewAbsent when have_memory_etag matched.
itemsRequiredDevContextItem[]The passages picked for the task, each citable by its citation_id.
routeRequiredDevContextRouteWhich sources were used, with what budget, and why.
tokens_usedRequiredintegerMeasured over this whole response; with render: "compact", over rendered.text. Never more than budget_tokens.
budget_tokensRequiredintegerThe budget the pack was built for.
tokenizerRequiredcl100k_baseThe tokenizer tokens_used and budget_tokens are counted with.
omittedRequiredDevContextOmittedWhat qualified but did not fit or fell below the relevance floor.
scope_usedRequiredDevContextScopeUsedThe Spaces the pack was drawn from.
partialRequiredbooleanTrue when a retrieval branch degraded or the scores are not calibrated relevance.
pending_processingDevPendingProcessingOnly when Entries in the searched Spaces are still being processed: their text may be missing from this result. GET /v2/spaces/{space_id}/processing reports when they become searchable.
renderedDevContextRenderedOnly when the request set render.
explainDevExplainSummaryOnly when the request set explain.

DevContextRoute

Explains the deterministic routing decision, generated after authorization.

FieldTypeDescription
purposeRequiredDevContextPurposeThe purpose used, inferred from the task unless you set it.
tierRequiredDevContextTier
rules_firedRequiredstring[]Stable rule names; they never quote the task. purpose:explicit or purpose:inferred:<purpose>; budget:table:<purpose>; tier:fast:lexical_only; weights:caller; scope:no_visible_space; files:named_in_task; source:off:<source>:<why> for a source that was off, where <why> is not_agent_caller, weight_zero, or answer_default; and table_aggregate:computed or table_aggregate:not_computed:<reason> for a table aggregate. New names can be added.
sourcesRequiredDevContextRouteSource[]Sources that were on. A source that was off is named in rules_fired.
unused_tokensRequiredintegerBudget left empty: nothing above the relevance floor wanted it.

DevContextRouteSource

FieldTypeDescription
sourceRequiredDevContextSource
budgetRequiredintegerTokens this source could use, after unused budget flowed in from other sources.
usedRequiredintegerTokens this source actually used.
pickedRequiredintegerItems from this source that made it into the pack.
omittedRequiredintegerCandidates from this source that were left out.
whyRequiredstringStable code, such as filled, below_relevance_floor, or no_file_named_in_task.

DevContextScopeUsed

FieldTypeDescription
space_idsRequiredDevId[]The Spaces that were searched.

DevContextSource

Where a context item came from. memory here means memories that are relevant to the task: memories written as Entries and distilled facts. It is not the whole memory: that is memory_view, a generated index of what is confirmed, sent alongside the items. knowledge is everything else found by search, files the files the task names, changes what was written recently, skills and agent_profile an Agent's own.

Values: memory | agent_profile | skills | files | changes | knowledge

DevContextTier

fast uses no model and matches words only; standard adds semantic search and reranking; deep looks at twice as many candidates.

Values: fast | standard | deep

DevContextWeights

Per-source preference from 0 to 1, normalized by the service together with the defaults of the sources you leave out. 0 turns a source off.

FieldTypeDescription
memorynumberWeight of memory: memories relevant to the task.0..1
agent_profilenumberWeight of agent_profile: the Agent's own profile.0..1
skillsnumberWeight of skills: the Agent's own skills.0..1
filesnumberWeight of files: the files the task names.0..1
changesnumberWeight of changes: what was written recently.0..1
knowledgenumberWeight of knowledge: everything else found by search.0..1

DevConversationContentPart

One segment of a message whose content is a list. Text segments are kept; images and the like are skipped.

FieldTypeDescription
typestringThe segment's type the way chat APIs write it, such as text or image_url.
textstringThe segment's text. A segment without it is skipped.

DevConversationMessage

A chat message the way chat APIs write it, so a transcript goes in without cleaning. A message with no text, such as an assistant turn that only calls a tool, is skipped; a batch where no message has text returns 422.

FieldTypeDescription
roleRequiredstringFree text such as user or assistant, without line breaks.length 1..128
contentstring | DevConversationContentPart[] | nullThe text, or a list of segments of which the text ones are joined. null or absent on a message without text.
nameobjectAccepted and ignored.
tool_callsobjectAccepted and ignored.
tool_call_idobjectAccepted and ignored.
function_callobjectAccepted and ignored.
timestampstring (date-time) | integerWhen the message was sent: an RFC 3339 string like every other time in this API, or Unix milliseconds. An integer that reads as seconds returns 422, because it would silently date the message to 1970.

DevCorrectMemoryRequest

Writes a replacement and closes the validity of the old memory.

FieldTypeDescription
textRequiredstringThe corrected statement, 1 to 2000 characters.length 1..2000

DevCreateApiKeyRequest

Uses actor_id and grant_capabilities instead of principal_id and capabilities, which are server-controlled: a request that sends them is rejected with identity_override. The same applies to POST and PATCH /v2/principals.

FieldTypeDescription
actor_idRequiredDevIdThe principal the key acts as. A calling key narrower than its own principal (fewer capabilities, a Space list, or a metadata scope) can issue keys only for that principal.
nameRequiredstringA name for the key, 1 to 256 characters, to tell keys apart in listings.length 1..256
grant_capabilitiesRequiredDevCapability[]Must not exceed the capabilities of the principal or of the caller.min items 1
allowed_space_idsDevId[]Omit to leave Spaces unrestricted; an empty list is rejected.items 1..100
metadata_scopeDevMetadataScopeLimit the key to Entries that carry these metadata labels: 1 to 8 keys, each with one value or up to 8 values. It cannot be changed afterward, and rotating the key keeps it. A key with a scope can use whoami, limits, reading Spaces, GET /v2/entries and an Entry's content and processing, GET /v2/jobs/{id}, reading memories, search, context, answer, context feedback, ingest, and MCP; every other operation returns 403 scoped_key_route_unavailable. Ingesting with a different value for a metadata key in the scope returns 403 outside_metadata_scope. For a hard boundary between end users, give each user a Space; use a scope for finer slices inside one.
expires_atstring (date-time)Must be in the future. Required when the calling key expires, and must not be later than that key's own expiry.

DevCreateBranchRequest

from copies another active branch, checkpoint_id a checkpoint; omit both to start from main. If you send both, checkpoint_id must be a checkpoint of the branch in from, otherwise it returns 404 checkpoint_not_found.

FieldTypeDescription
nameRequiredstringThe branch's name, 1 to 255 characters.length 1..255
fromDevIdThe id of an active branch to copy.
checkpoint_idDevIdThe id of a checkpoint to copy.
ttl_daysintegerHow many days each write pushes expires_at out by, 1 to 365. Omit it for the service default.1..365

DevCreateCheckpointRequest

FieldTypeDescription
nameRequiredstringA name for the checkpoint, 1 to 255 characters.length 1..255
gitDevCheckpointGit

DevCreateExportRequest

FieldTypeDescription
snapshotDevSnapshotRefA snapshot id or name: export the files as they were then. Without it, the live tree at the moment the job starts.
pathDevPathOnly this directory (or file) and what is under it.
formattarThe only format.

DevCreateForkRequest

A fork of a Space into a new Space you own. Planned.

FieldTypeDescription
nameRequiredstringThe new Space's name.
snapshotDevSnapshotRefFork the files as a snapshot pinned them. Without it, the live tree.

DevCreateImportRequest

FieldTypeDescription
source_entry_idRequiredDevIdAn Entry you can read whose latest version is a tar or gzip-compressed tar archive. Put the archive in any Space first with PUT .../files or uploads. The version is pinned when the job is created.
pathDevPathThe directory to import into, created as needed. Default /.
on_conflictDevImportConflictWhat to do when a file is already at a member's path: skip (the default) or overwrite.default: "skip"

DevCreateMemoryRequest

FieldTypeDescription
scopeRequiredDevMemoryScopeWhose memory to write: project, agent, or account.
space_idDevSpaceRefRequired for project and agent; default names your default Space, as it does in a path. Account memory takes none.
kindRequiredstringpreference, decision, or progress. Account memory has its own list: role, project, commitment, preference, person, fact, episode_summary, interview_answer, first_screen_pin, ask_less.length 1..64
textRequiredstringThe memory itself, 1 to 2000 characters.length 1..2000
pinnedbooleanNot on account memory.default: false

DevCreatePrincipalRequest

FieldTypeDescription
kindRequiredDevPrincipalKindWhat the principal is: a person or an Agent.
grant_capabilitiesDevCapability[]Capabilities to grant; they must not exceed yours. Omitted means knowledge:read for an Agent and none for a human.

DevCreateSnapshotRequest

FieldTypeDescription
nameRequiredstring1 to 255 bytes, unique in the Space, no control characters, not starting with snp_.length 1..255

DevCreateSpaceRequest

FieldTypeDescription
nameRequiredstringThe Space's name, 1 to 512 characters.length 1..512
descriptionstringWhat the Space is for, 1 to 4096 characters.length 1..4096
external_idstringYour own id for this Space, 1 to 256 characters, such as the id of the end user whose data it keeps. Find the Space later with GET /v2/spaces?external_id= or the path ext:<external_id> instead of storing its Mirabase id. It is unique among the account's Spaces: one already in use returns 409 space_external_id_taken (field: external_id). Deleting the Space frees it.length 1..256

DevCreateUploadRequest

For files over 16 MiB; smaller ones go through PUT. A file over this deployment's size limit returns 413. A file too large to process is still stored and readable; its knowledge.state ends at failed.

FieldTypeDescription
pathRequiredDevPathResolved when the upload completes, so the file may appear or change in between.
sizeRequiredintegerSize of the whole file in bytes.>= 1
media_typeRequiredstringThe file's media type, such as application/pdf.
checksum_sha256RequiredstringBase64 SHA-256 of the whole file, checked on completion.

DevCreateWebhookRequest

FieldTypeDescription
urlRequiredstringhttps, port 443, no username or password, no fragment, and a fully qualified hostname or public IP address. Every delivery resolves the host again and refuses to connect when any address is private, loopback, link-local, unique-local, carrier-grade NAT, benchmarking, documentation, multicast, or reserved, including mapped and NAT64 forms.max length 2048
opsDevChangeOp[]The event kinds to deliver; defaults to all five. No repeats.items 1..5
descriptionstringA note for people, at most 256 characters.max length 256
cursorDevCursorStart after this changes cursor. Defaults to now. An expired cursor returns 410 cursor_expired.

DevCreatedWebhook

The created webhook with its signing secret, returned once. A replay with the same Idempotency-Key omits it.

FieldTypeDescription
idRequiredDevIdlength 1..256
space_idRequiredDevIdlength 1..256
urlRequiredstring (uri)https on port 443.
opsRequiredDevChangeOp[]Event kinds to send. Events of other kinds are skipped, not queued.
descriptionstringA note for people.
statusRequiredDevWebhookStatusactive, or disabled when deliveries have stopped; disabled_reason says why.
disabled_reasonDevWebhookDisabledReasonPresent when status is disabled.
cursorRequiredDevCursorThe change-feed position after the last batch delivered or skipped.
consecutive_failuresRequiredintegerFailed attempts since the last success.
last_success_atstring (date-time)When a batch was last delivered.
last_failure_atstring (date-time)When an attempt last failed.
next_attempt_atstring (date-time)When the next attempt may start. Absent when disabled.
created_by_principal_idRequiredDevIdlength 1..256
created_atRequiredstring (date-time)When the webhook was created.
updated_atRequiredstring (date-time)When the webhook's settings or state last changed.
secretstringwhsec_ then 43 base64url characters. The HMAC key is this whole string.

DevCursor

Opaque pagination or change cursor.

Values: string

DevDiffBasis

What a diff compared: the original bytes of two text files, or the text processing extracted from anything else.

Values: original | text

DevDiffOmitted

Why unified_diff is absent. too_large: over 1 MiB or too many changed lines. not_text: a binary file with no extracted text. content_not_ready: one side is still being processed; ask again later.

Values: too_large | not_text | content_not_ready

DevDream

One dream's report. A dream only reorganizes memories that already exist: it generates nothing, every action carries its evidence, and it can be undone.

FieldTypeDescription
idRequiredDevIdlength 1..256
space_idRequiredDevIdlength 1..256
scopeRequiredDevDreamScope
agent_principal_idDevIdFor an agent dream: whose private memory.
statusRequiredDevDreamStatusqueued, running, then succeeded or failed.
triggerRequiredDevDreamTriggermanual: someone started it. schedule: the Space's dreaming schedule did.
started_by_principal_idDevIdFor a manual dream.
created_atRequiredstring (date-time)When the dream was queued.
started_atstring (date-time)When it began to run. Absent while it is queued.
finished_atstring (date-time)When it ended, whether it succeeded or failed.
undone_atstring (date-time)When it was undone. Absent if it never was.
undone_by_principal_idDevIdlength 1..256
undo_expires_atstring (date-time)While undoable: the latest moment an undo is accepted, unless three later dreams of the scope finish first. Counted from when the dream finished, or from the last approval of one of its proposals if that is later.
undoableRequiredbooleanWhether an undo would be accepted right now.
countsRequiredDevDreamCounts
viewDevDreamView
d4DevDreamD4ReportPresent once the dream reached its comparison step.
model_tokensRequiredintegerEstimated model tokens spent on this dream; 0 for a member with a read_root in the Space.
errorDevJobFailure

DevDreamAction

One change a dream made to one memory, or (reported) one it would make under dormancy: "apply".

FieldTypeDescription
seqRequiredintegerOrder within the dream; actions are listed by it.
memory_idRequiredDevIdlength 1..256
entry_idRequiredDevIdlength 1..256
actionRequiredDevDreamActionKind
reasonRequiredDevDreamActionReason
stateRequiredDevDreamActionState
proposal_idDevIdFor supersede and merge: the approved proposal.
target_memory_idDevIdFor supersede and merge: the memory that stayed. Absent when you cannot see its source.
created_atRequiredstring (date-time)When the action was taken.

DevDreamActionKind

dormant sets a memory aside; supersede and merge closed it when a proposal of this dream was approved.

Values: dormant | supersede | merge

DevDreamActionReason

proposal: a person approved the change.

Values: quote_missing | unused | proposal

DevDreamActionState

reported: a dormancy candidate under dormancy: "report"; nothing was changed, so there is nothing to undo.

Values: applied | undone | conflict_skipped | reported

DevDreamCounts

What a dream did. dormant_marked, dormancy_candidates, dormant_unused, superseded, merged, undone, and conflict_skipped count only actions on memories whose source you can see. The other counts are for the whole scope and are absent for a member with a read_root in the Space.

FieldTypeDescription
dormant_markedRequiredintegerMemories set aside as dormant because their quotes are gone (quote_missing).
dormancy_candidatesintegerPresent once the dream reached its dormancy step: distilled memories it found unused, that is not served for 90 days and through three dreams of the scope in a row, outside the 20 most used of their kind, and not rules, preferences, or memories a person confirmed. With the Space setting dormancy: "report" they are only listed as reported actions.
dormant_unusedintegerPresent with dormancy_candidates: those marked dormant with reason unused (Space setting dormancy: "apply").
supersededintegerMemories replaced by a newer one when a supersede proposal of this dream was approved. Present once there are any.
mergedintegerMemories folded into another when a merge proposal of this dream was approved. Present once there are any.
undoneintegerAfter an undo: actions taken back.
conflict_skippedintegerAfter an undo: actions left alone because the memory changed since (forgotten, confirmed, re-distilled, or taken over by a later dream).
checkedintegerDistilled memories checked.
skipped_confirmedintegerMemories a person confirmed, never changed by a dream: approved candidates, and memories distilled from a conversation ingested with memory:confirm.
skipped_not_readyintegerMemories whose source has a newer version still processing.
skipped_no_quoteintegerMemories without a quote to check.
stale_skippedintegerMemories that changed between the check and the write and were left for the next dream.
vetoedintegerMemories an earlier undo said not to touch again.
already_dormantintegerMemories already dormant from an earlier dream.
groupsintegerGroups of two or more memories that say the same thing.
grouped_factsintegerDistilled memories that share their statement with at least one other.
remainingintegerMemories left unchecked because one dream checks at most 10000. The next dream of the scope, started by hand or on its own, goes on after the last one checked; once a dream reaches the end, the next one starts over.

DevDreamD4Report

The model comparison (D4) of a dream. Counts cover the whole scope; absent for a member with a read_root in the Space.

FieldTypeDescription
statusRequiredran | skippedskipped: it asked the model nothing this run; skipped then says why.
skippedDevDreamD4SkipReasonSet whenever D4 was skipped or stopped before running out of pairs. remaining counts what it left.
nominatedRequiredintegerPairs of memories it found worth comparing.
judgedRequiredintegerPairs it asked the model about.
cachedRequiredintegerPairs answered from a judgment already made within 30 days.
proposedRequiredintegerJudgments written as open proposals.
shadowRequiredintegerJudgments recorded only (the shadow setting).
discardedRequiredintegerJudgments that failed validation or that the model could not answer; they keep no text.
stale_skippedRequiredintegerPairs whose memories changed before the judgment could be written.
failedRequiredintegerPairs where the model call failed.
remainingRequiredintegerPairs left unjudged because of skipped.

DevDreamD4SkipReason

Why D4 did not run, or stopped early. deployment_off, model_not_configured, distill_disabled (how the deployment is set up) and distill_paused, rate_limited, token_budget (the account's usage) are shown only to a key of a tenant_admin or one holding knowledge:manage that is not limited to Spaces or to a metadata scope. Any other caller sees unavailable for all six. space_off, group_limit and too_many_open_proposals are about the Space and are shown to everyone who can read the report.

Values: unavailable | deployment_off | model_not_configured | space_off | distill_disabled | distill_paused | rate_limited | token_budget | group_limit | too_many_open_proposals

DevDreamJudgment

One pair of memories a dream asked a model to compare, with the outcome. Visible only when you can see the source of every member; a discarded judgment keeps no quote and no text.

FieldTypeDescription
idRequiredDevIdlength 1..256
dream_idRequiredDevIdlength 1..256
outcomeRequiredDevDreamJudgmentOutcome
kindDevMemoryProposalKindWhat it concluded. Absent for a discarded judgment.
member_idsRequiredDevId[]The memories that were compared.
layerRequiredDevMemoryLayerThe memory layer of the pair: rule, decision, event, or knowledge.
signalsRequiredstring[]Why this pair was compared: entity, predicate, kind.
discard_reasonDevDreamJudgmentDiscardReasonOn a discarded judgment: why it was thrown out.
planDevMemoryProposalPlan
evidenceDevMemoryProposalEvidence[]The verbatim quotes the judgment rests on. Absent on a discarded judgment, which keeps no quote.
timesDevMemoryProposalTime[]Dates that decided which memory is newer.
modelstringThe model that was asked.
prompt_versionRequiredintegerVersion of the prompt the judgment was made with. A new version stops older judgments from being reused.
cachedRequiredbooleanTrue when this judgment reused an earlier one instead of asking the model.
created_atRequiredstring (date-time)When the judgment was recorded.

DevDreamJudgmentDiscardReason

Values: too_large | model_output | model_failed | unrelated | both_confirmed | quote_unverified | quote_not_in_sources | time_unverified | guard_number | guard_negation | guard_entity | suppressed

DevDreamJudgmentOutcome

Open and later states are the proposal's status; shadow and discarded exist only here.

Values: open | approved | rejected | stale | withdrawn | shadow | discarded

DevDreamScope

Which memory a dream reorganizes: the Space's project memory, or one Agent's private memory.

Values: project | agent

DevDreamStatus

Values: queued | running | succeeded | failed

DevDreamTrigger

Values: manual | schedule

DevDreamView

The active memories of the scope before and after: a dream never makes them more or longer. Absent for a member with a read_root in the Space.

FieldTypeDescription
live_beforeRequiredintegerActive memories in the scope before the dream.
tokens_beforeRequiredintegerTheir size in tokens before the dream.
live_afterintegerActive memories in the scope after the dream. Present once it has finished.
tokens_afterintegerTheir size in tokens after the dream. Present once it has finished.

DevEmptyRequest

Values: object

DevEnrichment

Work that runs after an Entry becomes searchable. Search does not wait for it.

Values: relations | classification | summary | memory

DevEnsureSpaceRequest

Used only when the Space is created; an existing Space is returned as it is.

FieldTypeDescription
namestringName for a new Space. Defaults to the external_id.length 1..512
descriptionstringDescription for a new Space.length 1..4096

DevEntry

The source record behind a file, a URL, or a conversation, with a chain of immutable versions. file and memory appear when they apply; knowledge is its processing state. Facts distilled from an Entry are not Entries: they live in memory and point back here.

FieldTypeDescription
idRequiredDevIdStarts with ent_. Stable across versions, renames, and moves.
space_idRequiredDevIdThe Space the Entry is in.
titleRequiredstringFor a file, its name. Otherwise the title you gave, or one derived from the content.
latest_version_idRequiredDevIdThe newest version written. Reads by path or id return it by default.
current_version_idDevIdThe version search and context read from. It equals latest_version_id once that version is indexed and trails it while a newer version is still processing. Absent until the first version finishes processing.
metadataRequiredDevMetadataWhat you set on ingest, with a file write, or with PATCH, plus any mirabase. keys the service added. Empty when none.
occurred_atstring (date-time)When the source itself happened: the occurred_at you sent on ingest or with a file write, or the time of a conversation's messages. Absent when unknown; retrieval's time filter then goes by when it was written.
source_typeDevSourceTypeWhat kind of source this is: file, note (ingested text), web (an ingested URL), agent-conversation (an ingested conversation). The same value a search hit reports and filter.source_types matches.
urlstringOn an Entry ingested from a URL: that URL. Use it to link a search hit or a citation back to the page.
created_atRequiredstring (date-time)When the Entry was first written.
updated_atRequiredstring (date-time)When the Entry last changed: a new version, new metadata, a move. This is the Entry's own clock, not the modification time of a file's content; that is the created_at of its latest version.
fileRequiredDevEntryFile | nullNull for an Entry without a path, such as a URL or a conversation.
knowledgeRequiredDevEntryKnowledgeHow far processing has progressed, and which version search is serving.
memoryRequiredDevEntryMemory | nullNull unless the Entry was written as a memory.
memory_excludeRequiredbooleanTrue when this Entry is kept out of memory distillation. Any Entry can have it, so it is not under memory.
accessRequiredDevEntryAccessYour role in the Entry's Space and the capabilities of the key you are using.
trashDevEntryTrashOnly in the trash listing (GET /v2/entries?trashed=true).

DevEntryAccess

FieldTypeDescription
roleRequiredDevSpaceRoleYour role in the Entry's Space.
capabilitiesRequiredDevCapability[]The capabilities this request acts with.

DevEntryContent

FieldTypeDescription
entry_idRequiredDevIdlength 1..256
version_idRequiredDevIdlength 1..256
viewRequiredDevContentViewThe view this is: text, table, or recognized.
textstringThe content as text. Absent on the table view.
tableDevTableContentThe content as a table. Only on the table view.

DevEntryCopy

A file copied from this Entry with tree/operations copy.

FieldTypeDescription
entry_idRequiredDevIdlength 1..256
source_version_idRequiredDevIdThe source version the copy started from.
space_idRequiredDevIdlength 1..256
created_atRequiredstring (date-time)When the copy was made.

DevEntryFile

FieldTypeDescription
pathRequiredDevPathlength 1..4096
sizeRequiredintegerSize of the latest version in bytes.
media_typeRequiredstringMedia type of the latest version.
etagRequiredstringThe latest version's ETag. Send it in If-Match to change the file only if nobody else has.
modified_atstring (date-time)When the content last changed: when the latest version was written. The same value a tree listing reports.

DevEntryKnowledge

FieldTypeDescription
stateRequiredDevKnowledgeState
indexed_version_idDevIdlength 1..256
parsedDevParsedSummaryWhat the indexed version was parsed into. Present on GET /v2/entries and GET /v2/entries/{entry_id} once the Entry has an indexed version; absent before that, when parsing failed, and on write receipts.
errorDevProcessingFailureWhy processing failed: the same error that GET /v2/entries/{entry_id}/processing returns. Present on GET /v2/entries and GET /v2/entries/{entry_id} when state is failed; absent otherwise and on write receipts.

DevEntryMemory

FieldTypeDescription
scopeRequiredDevMemoryScopeWhose memory it is: project, agent, or account.
kindRequiredstringThe kind of memory, such as preference or decision.
pinnedRequiredbooleanPinned memories come first in the memory context.
excludeRequiredbooleanThe Entry's memory_exclude setting: true keeps it out of memory distillation.

DevEntryProcessing

Processing of an Entry's latest version: the one place that says whether a write is searchable yet.

FieldTypeDescription
entry_idRequiredDevIdlength 1..256
version_idRequiredDevIdThe latest version, which is the one being reported.
statusRequiredDevVersionStatusTerminal when published, no_recallable_content, failed, or discarded.
knowledge_stateRequiredDevKnowledgeStateThe same value as knowledge.state on the Entry.
errorDevProcessingFailureOnly when status is failed.
stageRequiredDevProcessingStageWhere the latest version is now. Search finds it from enriching on.
progressRequiredDevProcessingProgressThe main steps done so far.
queueDevProcessingQueueOnly while the current step waits to start.
enrichmentsDevEnrichment[]Only while stage is enriching: what still runs.
memoryDevMemoryProcessingOnly on a conversation batch: where memory distillation is. Wait for it to leave pending before reading the memories.

DevEntryTrash

Where a trashed Entry was. Its path is free again while it is in the trash, so file is null.

FieldTypeDescription
deleted_atRequiredstring (date-time)When it went to the trash. For an Entry without a path, when its cleanup finished, moments later.
pathDevPathThe path a file had. POST /v2/entries/{id}/restore puts it back there. Absent for an Entry without a path.
delete_batch_idDevIdThe delete that trashed a file. restore in tree/operations takes it and brings back everything that delete removed.
deleted_byDevIdWho moved a file to the trash: a principal id. Absent for an Entry without a path.
sizeintegerSize in bytes of its latest version, the same as file.size had. Absent when it has no stored size.

DevErrorBody

What a failed request returns under error: a stable code to branch on, the HTTP status, a message for people, the request_id, whether a retry can help, and, for a code with a fixed next step, a remediation.

FieldTypeDescription
codeRequiredstringMachine-readable code, such as path_conflict or edit_ambiguous. On a 429: rate_limited for the request rate or too many concurrent operations (limit says which), too_many_waiters when a key already holds 4 long polls, ingest_backlog when too many jobs are queued, too_many_jobs when a Space already runs 4 exports or 4 other jobs, quota_exceeded when a stored quota is used up. x-mirabase-remediation-actions on this field lists every code that has a fixed next step and the remediation.action it comes with. Branch on the action, not on the message. A code that is not listed has no fixed next step: go by the HTTP status. conflict is the one exception: it carries use_new_idempotency_key only when field is Idempotency-Key. New codes can be added, so treat an unknown one like an unlisted one. x-mirabase-error-codes on this field lists every code an API key can receive, with its HTTP status, its meaning, and, where the response carries Retry-After, the seconds it gives (retry_after).
typeDevErrorTypeThe broad class of the error, decided by the HTTP status, for code that handles a whole class the same way: invalid_request (400, 422, and other 4xx not listed here), authentication (401), permission (403), not_found (404, 410), conflict (409, 412), rate_limit (429), server (5xx). Branch on code for the specific case. Present on every /v2 error.
statusRequiredintegerThe HTTP status, repeated in the body.
messageRequiredstringEnglish text for people. It may change: branch on code.
request_idRequiredstringIdentifies this request in the service's logs. Quote it when you report a problem.
retryableRequiredbooleanFalse on quota_exceeded: retrying does not help until the quota changes.
fieldstringFirst offending field on a 422. An unknown field in a request body is reported here by its name.
errorsDevFieldError[]On a 422 from request body validation: every problem found, at most 20, so that one round fixes them all. The first one is the problem field and message describe.
limitrequest_rate | concurrencyPresent on 429 rate_limited: which limit was hit. request_rate is the per-minute request budget that the RateLimit-* headers describe. concurrency is a limit on work in flight (searches and context calls, answers, or writes to one Space); the request already waited for a free slot, the RateLimit-* headers are not sent, and running fewer calls at once helps more than waiting longer.
quotawrites | storage_bytes | model_tokens | model_spend_micro_usdPresent on 429 quota_exceeded: which quota is used up. writes, model_tokens and model_spend_micro_usd reset at the start of the next month (UTC); storage_bytes comes back when files are purged. GET /v2/usage shows how much is left.
queueDevBacklogPresent on 429 ingest_backlog: the account's queue. GET /v2/queue shows it at any time.
current_version_idDevIdPresent on 412 precondition_failed and 409 proposal_conflict: the file's latest version now.
job_idDevIdPresent on 409 job_in_flight: the work to wait for.
conflictsDevMergeConflict[]Present on 409 merge_conflict: every path that blocked the merge.
remediationDevRemediation

Every error code's status, meaning, remediation.action, and Retry-After are in Error codes.

DevErrorResponse

FieldTypeDescription
errorRequiredDevErrorBodyThe error.

DevErrorType

The broad class of an error. New values can be added: treat an unknown one like invalid_request.

Values: invalid_request | authentication | permission | not_found | conflict | rate_limit | server | string

DevExplainAdmission

What let a hit past the relevance floor.

Values: score | lexical_match | title_named | pinned | same_entry | low_confidence_fallback

DevExplainBoost

A rule that changed a hit's position.

Values: time_window | newest_on_topic | newest_first

DevExplainBranch

Which way a hit was found. Lexical and dense are the two main branches; the rest are sources with their own rule.

Values: lexical | dense | dense_document | memory | relation | window_lexical | window_dense | recent | fresh_buffer | named_file | recent_change | skill | agent_profile

DevExplainBranchRank

FieldTypeDescription
branchRequiredDevExplainBranch
rankRequiredinteger1-based position in that branch's own results, counting only results you can read.

DevExplainCandidateCount

FieldTypeDescription
branchRequiredDevExplainBranch
countRequiredintegerHow many candidates that branch returned that you can read.

DevExplainRank

FieldTypeDescription
rankRequiredinteger1-based position.
scoreRequirednumberComparable inside one response only.

DevExplainRerank

FieldTypeDescription
rankRequiredinteger1-based position.
scoreRequirednumberComparable inside one response only.
passstringPresent when the score came from one clause of the task rather than the whole task: clause_1, clause_2, ...

DevExplainRerankSummary

FieldTypeDescription
appliedRequiredbooleanFalse when the reranker was skipped, failed or gave no scores; score is then not calibrated relevance.
poolRequiredintegerHow many candidates were sent to the reranker.
below_floorRequiredintegerHow many reranked candidates fell below the relevance floor.

DevExplainSummary

How the retrieval ran, when the request set explain.

FieldTypeDescription
termsRequiredstring[]The terms the lexical branch searched for.
candidatesRequiredDevExplainCandidateCount[]Candidates per branch, counting only those you can read. Branches that returned nothing you can read are left out.
fused_countRequiredintegerCandidates you can read after the branches were merged.
rerankRequiredDevExplainRerankSummary
clausesstring[]For a task that states several things: the clauses that were searched for separately.

DevFieldError

One problem in a request body.

FieldTypeDescription
fieldstringThe field, as a dotted path such as messages.0.role. Absent when the problem is the body as a whole.
codeRequiredstringvalidation_error, or a more specific code where one exists.
messageRequiredstringEnglish text for people.

DevFileAttributes

What a file write can record on the file's Entry along with the bytes. Each field is optional and only the ones you send change: replacing a file keeps the metadata, time, and switch it already has. They apply even when the bytes are unchanged and no version is created. Main only: on a branch or on a write that becomes a proposal, setting any of them returns 422, because the Entry belongs to the file's owner.

FieldTypeDescription
occurred_atstring (date-time)When the file's content occurred, such as when a recording was captured. Retrieval's occurred_from and occurred_to filters use it, and passages report it; without it, they use the time the file was written.
metadataDevMetadataReplaces the Entry's metadata as a whole, as metadata does on PATCH /v2/entries/{id}. Retrieval's filter.metadata matches it.
memory_excludebooleantrue keeps the file out of memory distillation: it is stored, indexed, and searchable, and nothing is distilled from it. false distills it again. The same switch as memory_exclude on PATCH /v2/entries/{id}.

DevFileBatchDelete

FieldTypeDescription
opRequireddeleteAlways delete.
pathRequiredDevPathlength 1..4096
if_matchstringThe file's etag: delete only if it is still current; otherwise this item returns 412 precondition_failed.

DevFileBatchItem

Values: DevFileBatchPut | DevFileBatchDelete

DevFileBatchPut

FieldTypeDescription
opRequiredputAlways put.
pathRequiredDevPathlength 1..4096
contentRequiredstringUTF-8 text, at most 64 KiB.
media_typestringDefaults to text/plain.
if_matchstringThe file's etag.
if_none_match*Only *: write the file only if nothing is at the path yet, as If-None-Match: * does on PUT. An existing file returns 412 precondition_failed for this item and the rest of the batch continues. Not with if_match.
occurred_atstring (date-time)When the file's content occurred, such as when a recording was captured. Retrieval's occurred_from and occurred_to filters use it, and passages report it; without it, they use the time the file was written.
metadataDevMetadataReplaces the Entry's metadata as a whole, as metadata does on PATCH /v2/entries/{id}. Retrieval's filter.metadata matches it.
memory_excludebooleantrue keeps the file out of memory distillation: it is stored, indexed, and searchable, and nothing is distilled from it. false distills it again. The same switch as memory_exclude on PATCH /v2/entries/{id}.

DevFileBatchRequest

At most 50 items and 1 MiB in total. Each item commits in its own transaction, in order. One failing does not stop the rest: the response is 200 and each result has its own status. With Idempotency-Key, sending the request again finishes it: committed items replay, the rest run. An item whose Entry was purged since replays as 410 gone with path set to /: the write happened, and its receipt was erased with the Entry. Match results to items by position.

FieldTypeDescription
itemsRequiredDevFileBatchItem[]1 to 50 writes and deletes, applied in order.items 1..50
session_idstringYour id for the conversation these changes came from, as on PUT files?session_id=: it is recorded on the version each put creates and shown by lineage. Main only: with branch it returns 422.length 1..256

DevFileBatchResponse

FieldTypeDescription
dataRequiredDevFileBatchResult[]One result per item, in the order the items were sent.
queueDevQueueEstimateHow many items went on the processing queue, and roughly how long the account's queue needs.

DevFileBatchResult

FieldTypeDescription
pathRequiredDevPathlength 1..4096
statusRequiredintegerThe HTTP status this item would have had as a request of its own, such as 200, 201, 404, or 412.
writeDevFileWrite
proposalDevProposalReceiptInstead of write, with status 202, when Prefer: handling=proposal turned this item into a proposal.
deletionDevFileDeletionOn a delete that succeeded.
branch_writeDevBranchFileWriteInstead of write when the request named a branch.
branch_deletionDevBranchFileDeletionInstead of deletion when the request named a branch.
errorDevErrorBodyOn an item that failed: the error body a single request would have returned.

DevFileDeletion

FieldTypeDescription
entry_idRequiredDevIdlength 1..256
deletedRequiredtrueAlways true: the file is in the trash.

DevFileEdit

FieldTypeDescription
old_textRequiredstringMust appear exactly once, unless replace_all is set.min length 1
new_textRequiredstringWhat replaces old_text. An empty string deletes it.
replace_allbooleanReplace every occurrence of old_text instead of requiring exactly one.default: false

DevFilePatchRequest

UTF-8 text files only: anything else returns 415 unsupported_media_type. A file over 1 MiB returns 413 patch_base_too_large, so replace it with PUT. Edits apply in order, each to the result of the one before. A baseline that moves during the request retries once, then returns 412 precondition_failed. With If-Match it does not retry.

FieldTypeDescription
editsRequiredDevFileEdit[]1 to 100 edits, applied in order.items 1..100

DevFileView

Which form of a file to read. raw: the original bytes, with Range support. meta: the Entry as JSON (DevEntry). text: the text extracted from the file. table: the rows of a spreadsheet. recognized: text recognized from an image or a recording. text, table, and recognized return a DevEntryContent.

Values: raw | meta | text | table | recognized

DevFileWrite

A committed, readable write. knowledge.state reports indexing progress: text up to 64 KiB is searchable at once, everything else is readable until it is indexed. If processing a replaced file's new version fails for good, the path falls back to the last version that worked and changes reports it. The failed version stays listed in versions, with status discarded: its bytes are readable with version= and revert brings it back.

FieldTypeDescription
entryRequiredDevEntryThe Entry as it is after the write.
version_idRequiredDevIdThe version that now holds the content. It is the ETag, without the quotes.
previous_version_idDevIdThe version this write replaced. Absent on a new file and when no version was created.
version_createdRequiredbooleanFalse when the content was unchanged, so no version was created.

DevFilterCondition

One condition of filter.where. It is exactly one of four shapes, and anything else is 422: - {"and": [...]} or {"or": [...]}: 1 to 16 conditions; - {"not": condition}; - {"key": "<metadata key>", <operator>} with exactly one operator: eq (one value), in (1 to 32 values), exists (true: the Entry has the key; false: it does not), or a range of gt/gte and lt/lte. A range compares the values stored under the key. Numbers are decimals such as -12 or 3.5; dates are YYYY-MM-DD or an ISO 8601 instant, and a value without an offset is read as UTC. A value that does not read as the bound's kind is not compared. With several values under one key, the condition holds when any of them does. At most 3 levels of and, or and not, and at most 16 key conditions in all. in and eq also narrow the vector search; exists and ranges are applied by the main database only, so a very selective range can return fewer semantic matches than limit.

FieldTypeDescription
andDevFilterCondition[]All of these hold. 1 to 16.items 1..16
orDevFilterCondition[]At least one of these holds. 1 to 16.items 1..16
notDevFilterConditionThis does not hold. An Entry without the key satisfies {"not": {"key": k, "eq": v}}.
keystringThe metadata key of a key condition: 1 to 64 of a-z, 0-9, _, ., -.
eqDevMetadataValueThe Entry holds this value under the key.min length 1
inDevMetadataValue[]The Entry holds one of these values under the key, 1 to 32 of them.items 1..32
existsbooleantrue: the Entry has the key; false: it does not.
gtDevFilterRangeBoundGreater than. Not together with gte.
gteDevFilterRangeBoundGreater than or equal. Not together with gt.
ltDevFilterRangeBoundLess than. Not together with lte.
lteDevFilterRangeBoundLess than or equal. Not together with lt.

DevFilterRangeBound

A range bound: a number, or a date as YYYY-MM-DD or an ISO 8601 instant with an offset. All bounds of a condition have the same kind.

Values: number | string

DevForgottenSource

An Entry version a forgotten fact was distilled from.

FieldTypeDescription
entry_idRequiredDevIdlength 1..256
version_idRequiredDevIdlength 1..256

DevHitExplain

Why this hit came back. Only when the request set explain.

FieldTypeDescription
found_byRequiredDevExplainBranchRank[]The branches that returned it, with its position in each. Empty for a computed table.
fusedDevExplainRankIts position and score after the branches were merged, before reranking, both computed over the candidates you can read.
rerankDevExplainRerankIts position and score from the reranker. Absent when reranking did not run or gave no score.
matched_termsstring[]The query terms its text matched. Chinese is matched in two-character terms.
lexicalstrong | covered | partialHow well its words covered the query: strong skips the relevance floor, covered and partial do not.
admitted_byDevExplainAdmissionWhat let it past the relevance floor. Absent when no floor applied.
boostsDevExplainBoost[]Rules that moved it up.
reordered_by_datestringWith newest_first: the date it was ordered by (occurred_at, else stated_date), YYYY-MM-DD.
computed_tabletrueTrue on an item the service computed over a whole table (table_aggregate:computed in route.rules_fired).

DevId

Opaque server-issued identifier. Clients compare it byte for byte.

Values: string

DevIdempotencyKey

Values: string

DevImportConflict

Values: skip | overwrite

DevImportFailure

One archive member an import could not write.

FieldTypeDescription
indexRequiredintegerThe member's position in the archive, from 0, counting every member (manifest.json too).
codeRequiredstringWhy, as an error code: invalid_path, reserved_path, path_conflict, unsupported_member, payload_too_large, proposal_required…

DevIngestConversation

One batch, one Entry, however many turns it has. Facts distilled from it are confirmed if you hold memory:confirm when you send it, otherwise candidate until someone reviews them. The rendered conversation is at most 2,000,000 characters.

FieldTypeDescription
kindRequiredconversationAlways conversation.
session_idRequiredstringYour id for the conversation, 1 to 256 characters. Send one batch per stretch of the conversation with the same session_id: each batch is its own Entry, and the id is also stored as the metadata key session_id (unless your metadata already has that key), so the batches of one conversation can be listed with GET /v2/entries?metadata={"session_id":"…"} and searched together with filter.metadata. It names the Entry when title is omitted.length 1..256
messagesRequiredDevConversationMessage[]The messages of this batch, in the order they were said: 1 to 1000.items 1..1000
titlestringDefaults to Conversation <session_id>.length 1..512
metadataDevMetadataOn the Entry, like any other source. A conversation's time comes from its messages' timestamp.
memory_excludebooleanTrue keeps this Entry out of memory distillation from the start: it is stored, indexed, and searchable, and nothing is distilled from it. The same switch as memory_exclude on PATCH /v2/entries/{id}, which can turn it back.
redact_secretsbooleanTrue replaces what looks like a credential in the text (and in title) before anything is stored: private key blocks, JWTs, Bearer tokens, well-known API key formats, and the value after password=, api_key:, and the like. Search, reads, and distilled memories then only ever see the redacted text, and the receipt's secrets_redacted says how many places were replaced. Unusual key formats may not be detected.
memory_instructionsstringYour guidance for what to remember from this conversation, 1 to 2,000 characters: what matters in your app, what to ignore, how much detail to keep (for example "Remember dietary restrictions and allergies; ignore small talk about the weather"). It is passed to the model that distills the conversation, alongside the messages. It cannot change the rules: every memory still has to be backed by a quote from the messages, and nothing is invented. It is stored with this version, so reprocessing uses it again; to change it, ingest the batch again.length 1..2000

DevIngestReceipt

What ingest answers with: the Entry and version it created, the job that processes them, and how far the Entry is searchable already.

FieldTypeDescription
entry_idRequiredDevIdThe Entry that was created.
version_idRequiredDevIdIts first version.
job_idRequiredDevIdThe processing job. GET /v2/jobs/{job_id} is succeeded once this version is indexed; the same progress is at GET /v2/entries/{entry_id}/processing. A conversation is distilled after that: both report it as memory.state.
knowledgeRequiredDevEntryKnowledgeUsually searchable for text of up to 64 KiB, otherwise readable until processing finishes.
memory_statuscandidate | confirmedOnly on a conversation: whether what is distilled from it takes effect or waits for review.
memoryDevMemoryProcessingOnly on a conversation: pending when it will be distilled once indexed, or skipped with the reason it will not be. Poll GET /v2/entries/{entry_id}/processing for what follows.
secrets_redactedintegerOnly when the request set redact_secrets: how many places were replaced. 0 means nothing looked like a credential.

DevIngestRequest

Values: DevIngestUrl | DevIngestText | DevIngestConversation

DevIngestText

FieldTypeDescription
kindRequiredtextAlways text.
textRequiredstringThe text to store, 1 to 2,000,000 characters.length 1..2000000
titlestringDefaults to the first line.length 1..512
occurred_atstring (date-time)When the text's content happened, such as the date of a meeting or an email. Defaults to unknown; retrieval's occurred_from / occurred_to then go by when it was written.
metadataDevMetadata
memory_excludebooleanTrue keeps this Entry out of memory distillation from the start: it is stored, indexed, and searchable, and nothing is distilled from it. The same switch as memory_exclude on PATCH /v2/entries/{id}, which can turn it back.
redact_secretsbooleanTrue replaces what looks like a credential in the text (and in title) before anything is stored: private key blocks, JWTs, Bearer tokens, well-known API key formats, and the value after password=, api_key:, and the like. Search, reads, and distilled memories then only ever see the redacted text, and the receipt's secrets_redacted says how many places were replaced. Unusual key formats may not be detected.

DevIngestUrl

The page is fetched and parsed after the response, so a bad URL shows up as a failed job: url_fetch_failed when the page could not be fetched, url_no_readable_content when it has no article text.

FieldTypeDescription
kindRequiredurlAlways url.
urlRequiredstring (uri)The page to fetch, http or https, at most 8192 characters.max length 8192
titlestringA title for the Entry, 1 to 512 characters.length 1..512
occurred_atstring (date-time)When the page's content happened, if you know it. Retrieval's occurred_from / occurred_to go by it.
metadataDevMetadata
memory_excludebooleanTrue keeps this Entry out of memory distillation from the start: it is stored, indexed, and searchable, and nothing is distilled from it. The same switch as memory_exclude on PATCH /v2/entries/{id}, which can turn it back.

DevIssuedApiKey

Returned on creation and rotation. The service stores only a hash of token.

FieldTypeDescription
idRequiredDevIdStarts with key_. Not the secret: the token is shown once, when the key is created or rotated.
principal_idRequiredDevIdThe principal the key acts as.
nameRequiredstringYour label for the key.
prefixRequiredstringNon-secret token prefix, for recognizing a key in a list.
capabilitiesRequiredDevCapability[]What the key may do. Never more than its principal's capabilities.
allowed_space_idsDevId[]Absent means not narrowed to specific Spaces.
metadata_scopeDevMetadataScopeThe metadata scope the key is limited to. Absent means not limited by metadata.
expires_atstring (date-time)After this time the key stops working. Absent when it does not expire.
revoked_atstring (date-time)When the key was revoked. Absent while it is live.
last_used_atstring (date-time)When the key last called the API, to within a minute. Absent until its first call.
created_byRequiredDevIdThe principal that issued it.
issued_by_key_idDevIdThe key that issued or rotated this one. Absent when no key was used.
created_atRequiredstring (date-time)When it was issued.
tokenstringThe secret, shown this once. Absent on an idempotent replay, because it is not stored: rotate the key if the original response was lost.

DevJob

Work that outlives the request. Three kinds share this shape. A processing job comes from ingest and reprocess. It follows the whole chain of its version (parse, index, publish): stage is where the chain is now, and status is succeeded only once the version is indexed, failed when processing gives up. purge is a job of its own with stage purge. A tree job (ids starting tjb_) comes from Prefer: respond-async, exports, and imports. Its stage is tree.move, tree.delete, tree.restore, tree.copy, branch.merge, space.export, or space.import; its status is never cancelled. Only whoever started it and the Space owner can read it. Finished tree jobs are kept for 7 days. A dream (ids starting drm_, only with memory dreaming enabled) has stage memory.dream. Poll every second or two; a job has no long poll.

FieldTypeDescription
idRequiredDevIdlength 1..256
kindRequiredDevJobKindWhich of the three this is: processing (from ingest, reprocess, a purge), tree (ids starting tjb_), or dream (ids starting drm_). It tells you which vocabulary stage uses and which fields to expect.
statusRequiredDevJobStatusqueued, running, then succeeded, failed, or cancelled.
stageRequiredstringWhat the job is doing, as described above.
entry_idDevIdProcessing jobs: the Entry being processed.
version_idDevIdProcessing jobs: the version being processed.
errorDevJobFailureOnly when status is failed.
memoryDevMemoryProcessingProcessing jobs of a conversation batch: where memory distillation is. status does not wait for it.
space_idDevIdTree jobs.
progressDevJobProgress
resultDevTreeJobResult
queueDevQueueEstimateImports: how many imported files went on the processing queue, and roughly how long the account's queue needs.
created_atRequiredstring (date-time)When the job was created.
updated_atRequiredstring (date-time)When the job last changed state or made progress.

DevJobFailure

For a processing job, code and message are the same as on GET /v2/entries/{id}/processing.

FieldTypeDescription
codeRequiredstringStable failure code. Branch on this.
messageRequiredstringEnglish text for people. It may change.
fieldstringFor a tree job: the request field the error is about, the same as the synchronous error would name.

DevJobKind

What a job does. processing: parses and indexes a version, from ingest, reprocess, or a purge. tree: a tree operation, merge, export, or import run as a job; ids start with tjb_. dream: one offline memory consolidation run; ids start with drm_.

Values: processing | tree | dream

DevJobProgress

How far a tree job got. done counts nodes, merge paths, exported files, or archive members handled so far.

FieldTypeDescription
doneRequiredintegerUnits of work handled so far.
totalintegerKnown once the job has counted its work.

DevJobReceipt

FieldTypeDescription
job_idRequiredDevIdPoll GET /v2/jobs/{job_id} until status is succeeded or failed.

DevJobStatus

Where a job is. queued: waiting to start. running: in progress. succeeded: done; a processing job succeeds only once its version is published or no_recallable_content. failed: done without success; error says why. cancelled: the service stopped a processing job before it finished; tree jobs and dreams never report it.

Values: queued | running | succeeded | failed | cancelled

DevKnowledgeState

readable after commit. searchable means lexical search already finds it: text in the request body, up to 64 KiB. indexed once processing is done. failed when it gives up; the bytes stay readable.

Values: readable | searchable | indexed | failed

DevLimit

FieldTypeDescription
nameRequiredstringStable limit name, such as requests_per_minute_read. x-mirabase-limits on this field lists every name with its default, its scope, and what exceeding it returns (exceeded). A deployment can change the values; this endpoint reports the ones in force. Request bodies are also read under a 180-second timeout, then 408 request_timeout, which this list does not report.
valueRequiredintegerThe limit's value for this account.

Limits

NameDefaultScopeWhen exceeded
requests_per_minute_read600Per key: GET, HEAD, search, and context requests per minute429 rate_limited with limit: request_rate
requests_per_minute_write120Per key: every other request per minute429 rate_limited with limit: request_rate
retrieval_concurrency2Per principal: searches and context calls running at once429 rate_limited with limit: concurrency, after waiting up to 1 second for a slot
agent_retrieval_concurrency8Per Agent principal, in place of retrieval_concurrency429 rate_limited with limit: concurrency, after waiting up to 1 second for a slot
answer_concurrency3Per principal: answers running at once429 rate_limited with limit: concurrency, after waiting up to 10 seconds for a slot
space_write_concurrency4Per Space: writes running at once429 rate_limited with limit: concurrency, after waiting up to 1 second for a slot
space_writes_per_month100,000Per Space: writes in a UTC calendar month429 quota_exceeded
tenant_writes_per_month1,000,000Per account: writes in a UTC calendar month429 quota_exceeded
space_storage_bytes10 GiBPer Space: bytes stored429 quota_exceeded
tenant_storage_bytes100 GiBPer account: bytes stored429 quota_exceeded
tenant_model_tokens_per_month1,000,000Per account on the free plan only: tokens the service's language models generate for the account (answers, distillation, summaries, classification, memory consolidation) in a UTC calendar month. Listed only when the plan sets it429 quota_exceeded with quota: model_tokens; a processing step that needs the model fails with quota_exceeded
tenant_model_spend_micro_usd_per_month2,000,000Per account on the free plan only: every billable model call (language models, speech recognition, OCR, reranking, embeddings, web search) at the service's list prices, in millionths of a US dollar, in a UTC calendar month. Checked before each call; a long recording that does not fit is refused before it is transcribed. Listed only when the plan sets it429 quota_exceeded with quota: model_spend_micro_usd; a processing step that needs the model fails with quota_exceeded
tenant_queued_jobs10,000Per account: queued jobs that make content searchable (parsing, image, audio and video recognition, indexing, publishing). The model work after a file is searchable (summaries, classification, relations, memories) has its own limit of five times this number429 ingest_backlog
space_active_branches100Per Space: active branches409 branch_limit_reached
branch_paths10,000Per branch: paths409 branch_too_large
branch_checkpoints100Per branch: checkpoints409 checkpoint_limit_reached
branch_ttl_days30Per branch: days without a write before it expires-
branch_reclaim_days7Per branch: days from its end until it is reclaimed-
space_snapshots100Per Space: snapshots409 too_many_snapshots
snapshot_files10,000Per snapshot: files409 snapshot_too_large
export_max_bytes4 GiBPer export: original bytes409 export_too_large
import_max_bytes1 GiBPer import: archive bytes413 archive_too_large
tenant_api_keys100Per account: live keys409 tenant_limit_reached
tenant_principals200Per account: principals409 tenant_limit_reached
tenant_spaces10,000Per account: Spaces not deleted409 tenant_limit_reached
team_members50Per team: members (console)-
team_pending_invitations20Per team: invitations waiting to be accepted (console)-
team_invitations_per_day100Per team: invitations sent in a day (console)-
tenant_requests_per_minute_read6,000Per account: read requests per minute across all keys, 10 times requests_per_minute_read429 rate_limited with limit: request_rate
tenant_requests_per_minute_write1,200Per account: other requests per minute across all keys, 10 times requests_per_minute_write429 rate_limited with limit: request_rate
tenant_retrieval_concurrency80Per account: searches and context calls running at once across all principals, 10 times agent_retrieval_concurrency429 rate_limited with limit: concurrency, after waiting up to 1 second for a slot

DevLimits

FieldTypeDescription
dataRequiredDevLimit[]Every limit that applies to this account.
planDevPlanThe account's plan. On free, data already shows the plan's figures, and tenant_model_tokens_per_month and tenant_model_spend_micro_usd_per_month are listed.

DevLineage

Where an Entry came from, and one page of its versions, newest first. Who copied it is not listed.

FieldTypeDescription
entry_idRequiredDevIdlength 1..256
originRequiredDevLineageOriginHow the Entry came to exist.
dataRequiredDevLineageVersion[]One page of its versions, newest first.
next_cursorDevCursorlength 1..1024

DevLineageOrigin

FieldTypeDescription
kindRequiredDevLineageOriginKindcreated: written directly. copy: copied from another Entry. branch_merge: first written by a branch merge.
sourceDevLineageRefFor copy: the Entry and version it was copied from.
branch_idDevIdFor branch_merge: the branch, by id only. Branches are reclaimed after they close.
chainDevLineageRef[]For copy, when the source was itself a copy: further up, nearest first, at most 16.
chain_truncatedtrueThe chain goes on past 16 steps.

DevLineageOriginKind

Values: created | copy | branch_merge

DevLineageRef

One step up a copy chain. A source you cannot see is visible: false with no ids, and the chain stops there. A purged source keeps its ids, with purged: true.

FieldTypeDescription
visibleRequiredbooleanFalse when you cannot see the source: it has no ids and the chain stops there.
entry_idDevIdlength 1..256
version_idDevIdlength 1..256
purgedtrueTrue when the source has been purged. Its ids are still given.

DevLineageVersion

FieldTypeDescription
version_idRequiredDevIdlength 1..256
parent_version_idsRequiredDevId[]The versions this one was written on top of. Empty on the Entry's first version.
created_atRequiredstring (date-time)When the version was written.
author_principal_idDevIdlength 1..256
kindRequiredDevVersionKind
restored_fromDevIdFor revert.
proposal_idDevIdFor proposal_accept.
branch_idDevIdFor branch_merge.
messagestringThe version's message, when it has one.
session_idstringThe conversation this version came from: the session_id the file write carried. Look the conversation up with GET /v2/entries?metadata={"session_id":"…"}. Absent when the write named none; a revert or a copy does not inherit it.

DevMcpHandshake

tools lists what this key can call on this deployment.

FieldTypeDescription
nameRequiredstringThe MCP server's name.
versionRequiredstringThe service version.
protocolRequiredstringThe MCP protocol version the server speaks.
transportRequiredstreamable-httpAlways streamable-http.
toolsRequiredDevMcpTool[]The tools this key can call on this deployment.

DevMcpRequest

A JSON-RPC 2.0 request, or a batch of up to 32. Methods are defined by MCP; tools/call takes a tool from x-mirabase-mcp-tools and arguments that match its inputSchema.

Values: object

DevMcpResponse

A JSON-RPC 2.0 response, or a batch of them. A tool that fails returns a result with isError: true: its content text gives the error code, whether a retry can help, and the next step, and _meta["dev.mirabase/error"] holds the full error envelope. A failed result never carries structuredContent.

Values: object

DevMcpTool

FieldTypeDescription
nameRequiredDevMcpToolName
descriptionRequiredstringWhat the tool does, as it is shown to the model.
inputSchemaRequiredobjectThe tool's input as JSON Schema.

DevMcpToolName

Every tool is one /v2 request: same key, same limits, same error envelope.

Values: mira.whoami | mira.files.list | mira.files.read | mira.files.write | mira.files.edit | mira.files.delete | mira.search | mira.context | mira.context.feedback | mira.activity | mira.memory.list | mira.memory.remember | mira.memory.forget | mira.conversation.ingest | mira.text.ingest | mira.url.ingest | mira.entries.read | mira.answer | mira.memory.correct | mira.memory.review | mira.trash.list | mira.trash.restore | mira.memory.get

DevMemory

One shape for three sources: account memories, memories written as Entries, and facts distilled from Entries. id is not an Entry id unless the memory was written as an Entry. pinned only applies to those. A forgotten memory has no text left, so it is never returned. "Memory" appears in four places, and each is a different set. GET /v2/memories is the full governed list, candidates and history included. memory_view on a context pack (and MEMORY.md) is the index of what is confirmed and current, without sensitive kinds. include: ["memory"] on search adds memories to the hits and ranks with the memory profile. memory on a search hit or context item is one confirmed fact distilled from that passage.

FieldTypeDescription
idRequiredDevIdPass it to the other memory endpoints. A distilled fact's id contains colons, so percent-encode it in a path.
entry_idDevIdThe Entry this memory is, or the Entry it was distilled from. Absent on account memory.
space_idDevIdAbsent on account memory, which belongs to no Space you can address.
scopeRequiredDevMemoryScopeWhose memory it is: account (the person, across Spaces), project (the Space), or agent (one Agent's own).
kindRequiredstringWhat sort of memory, such as preference, decision, or progress; distilled facts have others, such as experience. GET /v2/memories?kind= filters on it.
statusRequiredDevMemoryStatusconfirmed memories take effect in retrieval and MEMORY.md; a candidate waits for review; rejected and superseded are history.
textRequiredstringThe memory itself, as one statement.
pinnedRequiredbooleanWhether the memory is pinned. Only memories written as Entries can be pinned.
supersedesDevIdOn a correction: the memory it replaced.
valid_fromstring (date-time)When the fact became true, if the source said so.
valid_tostring (date-time)When this stopped being the current value. With replaced_by, it is when the newer value took over.
created_atRequiredstring (date-time)When the memory was first written or distilled.
updated_atRequiredstring (date-time)When it last changed: a review, a correction, a pin, or a new validity.
replaced_byDevReplacingMemoryOnly on distilled memories from GET /v2/memories and GET /v2/memories/{memory_id}, on deployments with evidence-based memory enabled: the current value of the same attribute, when a later conversation in the same Space and scope changed it ("lives in Shanghai", then "moved to Hangzhou"). The memory keeps status: "confirmed": it was true, it is just not the current value, and MEMORY.md no longer lists it. Only a newer value you can read counts.
dormantDevMemoryDormancyOnly on deployments with memory dreaming enabled, and only on GET /v2/memories and GET /v2/memories/{memory_id}: a distilled memory a dream marked dormant. It stays listed and searchable. MEMORY.md lists only memories a person wrote or confirmed, which are never dormant; undo the dream to clear it.
group_idDevIdOnly on deployments with memory dreaming enabled, and only on distilled memories from GET /v2/memories and GET /v2/memories/{memory_id}: the group this memory belongs to. Distilled memories in the same Space, scope, and status that say the same sentence (compared after Unicode normalization, case, and whitespace folding) are one group, listed once under the smallest id you can see. Only members whose source you can see count.
sourcesDevMemorySource[]With group_id: the members of the group you can see, smallest id first, this one included.
pending_proposalsDevId[]Only on deployments with memory dreaming enabled, on GET /v2/memories and GET /v2/memories/{memory_id}: open dream proposals about this memory (or a member of its group), oldest first, limited to proposals you can see. Absent when there are none.

DevMemoryD4Mode

Whether a dream asks a model to compare pairs of distilled memories (D4). off, the default, never asks; shadow asks and records the judgments without proposing anything; propose writes open proposals from judgments that pass validation. The model never writes text that lands in memory: it only says how two memories relate and quotes the source verbatim. A deployment where d4_available is false never asks a model, whatever this says.

Values: off | shadow | propose

DevMemoryDormancy

FieldTypeDescription
reasonRequiredDevMemoryDormancyReason
dream_idRequiredDevIdlength 1..256

DevMemoryDormancyMode

What a dream does with distilled memories nobody used for a long time (dormancy). report, the default, only counts them in the dream's report and lists them as reported actions; apply marks them dormant with reason unused. A dormant memory leaves RECENT.md but stays listed and searchable, and the first time it is served again (GET /v2/memories/{memory_id}, a search, a context pack, or an answer that hands it back) it wakes up. Rules and preferences are never marked unused, though a rule whose quote is gone can still be marked quote_missing. Memories a person confirmed are never marked at all, so nothing in MEMORY.md goes dormant.

Values: report | apply

DevMemoryDormancyReason

Why a dream sets a distilled memory aside. - quote_missing: none of its quotes is found in the current version of its source anymore. Only distilled memories no person reviewed get it: status: "confirmed" also covers those that took effect without review, while approved candidates and memories distilled from a conversation ingested with memory:confirm never do. A confirmation clears it. - unused: nobody was served it for 90 days and through three dreams of its scope, it is not among the 20 most used of its kind, and it is neither a rule or preference nor a memory a person confirmed; only when the Space setting dormancy is apply. Being served again (GET /v2/memories/{memory_id}, or handed back by a search, context pack, or answer) wakes it up. A later distillation of the source (including one that rewrites this memory) clears either. With both, the memory reports quote_missing.

Values: quote_missing | unused

DevMemoryDreamingMode

Whether offline memory consolidation ("dreams") runs for a Space. propose, the default, lets it run; off stops it. A dream only reorganizes memories that already exist: it generates nothing, every action carries its evidence, and it can be undone. auto is not available yet.

Values: off | propose

DevMemoryForgetReceipt

The text is gone, so there is nothing else to return.

FieldTypeDescription
memory_idRequiredDevIdlength 1..256
statusRequiredforgottenAlways forgotten.
remaining_sourcesDevForgottenSource[]Only when a distilled fact was forgotten: the Entries it came from. The fact is erased and will not be distilled again, but that source text is still there and still comes up in search. Trash or purge these Entries too when the content itself has to go.

DevMemoryLayer

How a dream treats a distilled memory, worked out from its kind and validity date. rule: rules and preferences (preference, profile, workflow, lesson, commitment), never marked dormant for being unused. decision: decisions and progress (decision, progress, task, outcome). event: events (experience, failure, and other memories with valid_from), never compared or merged, so the timeline stays. knowledge: every other distilled fact.

Values: rule | decision | event | knowledge

DevMemoryProcessing

Memory distillation for a conversation batch. It runs after the version is indexed, so a processing job can be succeeded while this is still pending.

FieldTypeDescription
stateRequiredpending | ready | skipped | failedpending until distillation has finished. Then ready: what it wrote is in GET /v2/memories. failed when distillation gives up. skipped when it does not run for this version; reason says why.
countintegerOnly when state is ready: how many memories the batch wrote, candidates included. 0 means it found nothing to keep.
reasonDevMemoryProcessingReasonWith skipped: why distillation does not run. With pending: only distill_paused, when the wait is longer than usual, and only for a caller that can see the account's state. Absent on skipped only when the service cannot tell. A version distilled before the deployment stopped distilling is still ready.
remediationDevRemediationOnly with a reason you can act on, in the same shape as on an error. clear_memory_exclude: set memory_exclude to false with PATCH /v2/entries/{id}. write_memories_directly: this deployment does not distill, so write the memories yourself with POST /v2/memories. review_usage: see GET /v2/usage. wait_and_retry: poll again later.

DevMemoryProcessingReason

Why distillation does not run for a version, or waits longer than usual. - memory_excluded: the Entry has memory_exclude. - distill_disabled: this deployment has memory distillation turned off. - model_not_configured: this deployment has no model for distillation. - distill_paused: distillation is paused for the account until its usage period resets; it resumes by itself. - processing_failed: the version failed processing; the processing error says why. - nothing_to_distill: the version has no text to distill. - distill_unavailable: distillation does not run here now. What a caller sees instead of distill_disabled and model_not_configured unless its key belongs to a tenant_admin or holds knowledge:manage, and is not limited to Spaces or to a metadata scope: those two describe how the deployment is set up. Such a caller sees pending without a reason where an admin sees distill_paused, which tells that the account reached its usage limit. More reasons may be added. Treat one you do not know as the state alone.

Values: memory_excluded | distill_disabled | model_not_configured | distill_paused | processing_failed | nothing_to_distill | distill_unavailable

DevMemoryProposal

A change a dream suggests but does not make on its own, waiting for a person: merge memories that say the same thing, let a newer memory supersede an older one, flag two that contradict each other, or promote an Agent's private memory to the project. Visible only when you can see the source of every member; otherwise returns 404. A dream writes proposals only when the Space's d4 setting is propose and this deployment has a model for it. The model never writes text that lands in memory, so proposed_text is always absent for now.

FieldTypeDescription
idRequiredDevIdlength 1..256
space_idRequiredDevIdlength 1..256
scopeRequiredDevDreamScope
agent_principal_idDevIdFor an agent proposal: whose private memory.
dream_idRequiredDevIdThe dream that proposed it.
kindRequiredDevMemoryProposalKindWhat it suggests: merge, supersede, conflict, or promote.
member_idsRequiredDevId[]The memories it is about, sorted.
proposed_textstringThe statement it proposes. Absent for now; always absent for conflict.
evidenceDevMemoryProposalEvidence[]The verbatim quotes that back the proposal.
planDevMemoryProposalPlanWhat approve would do. Absent for conflict, which has nothing to apply.
layerDevMemoryLayerThe memory layer of its members: rule, decision, event, or knowledge.
timesDevMemoryProposalTime[]Dates that decided which memory is newer.
statusRequiredDevMemoryProposalStatuswithdrawn when its dream was undone while it was open; stale when its members changed before it was approved; rejected ones are not proposed again for the same members. approved stays approved after its dream is undone: look at the dream's actions to see whether the change still stands.
reviewed_by_principal_idDevIdWho approved or rejected it.
reviewed_atstring (date-time)When it was approved or rejected.
closed_atstring (date-time)When it stopped being open, for any reason.
created_atRequiredstring (date-time)When the dream wrote the proposal.

DevMemoryProposalEvidence

One verbatim quote backing a proposal, from the version of the source it was read from.

FieldTypeDescription
memory_idRequiredDevIdlength 1..256
entry_idRequiredDevIdlength 1..256
version_idRequiredDevIdlength 1..256
quoteRequiredstringThe quote, word for word.

DevMemoryProposalKind

What a memory proposal suggests. merge: two memories say the same thing, and one absorbs the other. supersede: a newer memory replaces an older one. conflict: two memories contradict each other; shown to a person only, and cannot be approved. promote: an Agent's private memory moves to the project; cannot be approved.

Values: merge | supersede | conflict | promote

DevMemoryProposalPlan

What approving would do: the memory that stays, and the ones it replaces or absorbs.

FieldTypeDescription
keepRequiredDevIdThe memory that stays.
closeRequiredDevId[]The memories that approving closes: the ones keep replaces or absorbs.

DevMemoryProposalStatus

Where a memory proposal stands. open: waiting for a person. approved: carried out. rejected: closed without a change; the same members are not proposed for the same change again. stale: a member changed before the proposal was approved. withdrawn: its dream was undone while it was open.

Values: open | approved | rejected | stale | withdrawn

DevMemoryProposalTime

A date backing a proposal: verbatim from the source, or the date of the source itself.

FieldTypeDescription
memory_idRequiredDevIdlength 1..256
entry_idRequiredDevIdlength 1..256
dateRequiredstringThe date, as the source states it or as the source itself is dated.
quoteRequiredstringThe words in the source that the date was read from.

DevMemoryProvenance

FieldTypeDescription
memory_idRequiredDevIdlength 1..256
sourcesRequiredDevMemoryProvenanceSource[]The Entry versions this memory rests on. All of them come back in one response: the list is not paginated.

DevMemoryProvenanceSource

FieldTypeDescription
entry_idRequiredDevIdlength 1..256
version_idRequiredDevIdlength 1..256
quotestringThe words in that version this memory rests on.
merged_fromDevIdOnly on deployments with memory dreaming enabled: this source came from a memory folded into this one when a merge proposal was approved. Its id; listed only when you can see its source.

DevMemoryScope

Whose memory it is. project: one Space's memory; creating one needs space_id. agent: one Agent's private memory, written only with that Agent's key; it has no path and no change events. account: the account's own memory, listed for its owner only and in no Space.

Values: project | agent | account

DevMemorySection

FieldTypeDescription
sourceRequiredaccount | agent | project | usageaccount, agent, project, or usage.
kindRequiredstringThe kind of memory, such as preference or decision.
textRequiredstringThe memory itself.
confidenceRequirednumberFrom 0 to 1: the confidence recorded with this memory.0..1
valid_untilstring (date-time)After this moment the memory is no longer served. Absent when it does not expire.
source_refRequiredDevMemorySourceRefWhere the memory came from.

DevMemorySettings

A Space's memory consolidation setting. A Space nobody configured reports the defaults and no updated_* fields.

FieldTypeDescription
space_idRequiredDevIdlength 1..256
memory_dreamingRequiredDevMemoryDreamingModeWhether dreams run: propose (the default) or off.
dormancyRequiredDevMemoryDormancyModeWhat a dream does with unused memories: report (the default) or apply.
d4RequiredDevMemoryD4ModeWhether a dream asks a model to compare memories: off (the default), shadow, or propose.
d4_availablebooleanWhether this deployment can ask a model for D4 at all (the operator enabled it and configured a model). It describes how the deployment is set up, so it is present only for a key of a tenant_admin or one holding knowledge:manage that is not limited to Spaces or to a metadata scope.
updated_atstring (date-time)When the settings were last changed. Absent while nobody has configured the Space.
updated_by_principal_idDevIdlength 1..256

DevMemorySource

One member of a group of distilled memories.

FieldTypeDescription
memory_idRequiredDevIdlength 1..256
entry_idRequiredDevIdlength 1..256

DevMemorySourceRef

FieldTypeDescription
memory_idDevIdlength 1..256
candidate_idDevIdlength 1..256
claim_idDevIdlength 1..256
entry_idDevIdlength 1..256
version_idDevIdlength 1..256
space_idDevIdlength 1..256
recorded_atRequiredstring (date-time)When the memory was recorded.
valid_fromRequiredstring (date-time)When the memory took effect.

DevMemoryStatus

Where a memory stands. candidate: waiting for review, and not used by retrieval. confirmed: in effect, and used by retrieval. rejected: turned down in review. superseded: replaced by a correction, or closed by an approved memory proposal. rejected and superseded memories are history: a list returns them only when you ask for that status.

Values: candidate | confirmed | rejected | superseded

DevMemoryUndoReceipt

What undo took back, and what came back with it.

FieldTypeDescription
memory_idRequiredDevIdlength 1..256
statusRequiredundoneAlways undone.
restoredRequiredDevMemory[]The memories that came back: what the undone memory had replaced. Empty when it replaced nothing.

DevMemoryView

The deterministic memory view: the same memories give the same bytes, whatever the task.

FieldTypeDescription
sectionsRequiredDevMemorySection[]The memories in the view, in a stable order.

DevMergeConflict

A path main changed after the branch first touched it. Nulls mean no such version: the file did not exist.

FieldTypeDescription
pathRequiredDevPathlength 1..4096
base_version_idRequiredDevId | nullThe main version the branch started from at this path. Null when the file did not exist then.
main_version_idRequiredDevId | nullMain's latest version at this path now. Null when the file no longer exists.
branch_version_idRequiredstring | nullThe branch's content hash, the same value as its etag without quotes. Null on a delete.

DevMergeConflictPolicy

Values: abort | keep_main | keep_branch

DevMergeProposed

FieldTypeDescription
pathRequiredDevPathlength 1..4096
entry_idRequiredDevIdlength 1..256
proposal_idRequiredDevIdlength 1..256

DevMergeRequest

paths merges just those paths, directories with everything under them, and the branch stays active; without it the branch ends merged. on_conflict applies to paths whose main latest is no longer the version the branch started from: abort fails the whole merge, keep_main skips them, keep_branch overwrites main. There is no content merge.

FieldTypeDescription
messageRequiredstring1 to 1000 characters. Recorded as the message of every version the merge writes to main.length 1..1000
pathsDevPath[]Merge only these paths, 1 to 1000 of them; a directory brings everything under it. Omit it to merge the whole branch.items 1..1000
on_conflictDevMergeConflictPolicyWhat to do with a path main changed after the branch started from it: abort, keep_main, or keep_branch.default: "abort"

DevMergeResult

FieldTypeDescription
branch_idRequiredDevIdlength 1..256
stateRequiredactive | mergedThe branch's state after the merge: merged, or still active when only paths were merged.
mergedRequiredDevPath[]Paths written to main. merged_items has the versions.
skippedRequiredDevPath[]Paths left out. skipped_items has the reasons.
merged_itemsRequiredDevMergedPath[]One item per path written to main: what was done and the resulting version.
skipped_itemsRequiredDevMergeSkipped[]One item per path left out, with the reason.
proposed_itemsDevMergeProposed[]With Prefer: handling=proposal: files the merging Agent does not own, proposed instead of written. They leave the branch like merged paths. Absent when there are none.

DevMergeSkipReason

Values: symlink | unchanged | kept_main

DevMergeSkipped

FieldTypeDescription
pathRequiredDevPathlength 1..4096
reasonRequiredDevMergeSkipReasonsymlink: symlinks are not merged. unchanged: main already has the same content. kept_main: main changed and on_conflict was keep_main.

DevMergedOp

Values: create | update | delete | mkdir

DevMergedPath

FieldTypeDescription
pathRequiredDevPathlength 1..4096
opRequiredDevMergedOpWhat the merge did on main: create, update, delete, or mkdir.
entry_idDevIdlength 1..256
version_idDevIdlength 1..256

DevMetadata

Your own keys and values on an Entry; their meaning belongs to the caller. A key is 1 to 64 of a-z, 0-9, _, ., -; a value is a string or a list of strings, at most 32 values in all. Retrieval can filter on them by exact match (filter.metadata). A list of one value is the same thing as that value: ["a"] is stored and read back as "a". Keys starting with mirabase. are written by the service and rejected in requests. Identity field names (user_id, tenant_id, principal_id, roles, capabilities, entitlements, in either case style) return 403 identity_override anywhere in a body, here included. To keep one end user's data apart, give that user a Space. Metadata narrows search, but memory is kept per Space: forgetting a sentence, the history of a changing fact, and memory_view do not look at metadata, so two end users sharing a Space also share its memory.

Values: object

DevMetadataAnyOf

Matches an Entry holding any one of these values under the key.

FieldTypeDescription
anyRequiredDevMetadataValue[]The values to match, 1 to 32 of them.items 1..32

DevMetadataScope

Permission by metadata: the labels a key is limited to. Each key of the object names one or several values. The API key then only sees an Entry that holds, under every one of these keys, at least one of the listed values; an Entry without them does not exist for it, in search, context, answers, reads by id, and memories alike. What the key ingests is stored with the first value of each key, so it can read back what it wrote and cannot write into another scope. {"customer": ["acme", "shared"]} reads what is labeled acme or shared and writes as acme.

Values: object

DevMetadataValue

One metadata value: not empty, at most 256 bytes of UTF-8.

Values: string

DevParsedSummary

A few counts that say what parsing produced. Which ones appear depends on the kind of content.

FieldTypeDescription
passagesRequiredintegerPassages the content was split into for retrieval.
charactersRequiredintegerCharacters of text extracted, including text read from images and transcribed from audio.
duration_msintegerAudio and video: length of the recording in milliseconds.
speakersintegerAudio and video: the number of distinct speakers the transcript tells apart. Absent when it does not tell them apart.
sheetsintegerSpreadsheets and CSV: number of sheets.
rowsintegerSpreadsheets and CSV: rows across all sheets.
columnsintegerSpreadsheets and CSV: columns of the widest sheet.

DevPath

Absolute path inside a Space: / then names joined by single /, no trailing /. At most 64 levels, 4096 bytes, 255 bytes per name. Names compare by NFKC and case folding and keep the spelling you wrote. ., .., control characters, backslashes, and leading or trailing whitespace are not allowed, and /.mirabase/ is reserved except for /.mirabase/skills/<name>/.... A path over these limits returns 422 path_too_long.

Values: string

DevPendingProcessing

Entries in the request's Spaces that are not searchable yet.

FieldTypeDescription
entriesRequiredintegerHow many Entries the caller can see are still queued or being processed.

DevPlan

The account's plan. standard uses this deployment's limits. free is what a self-serve signup starts on: it also caps storage, monthly writes, monthly model tokens, monthly model spending and the request rate (see GET /v2/limits). legacy is an account opened before plans existed: it keeps this deployment's limits, like standard.

Values: free | standard | legacy

DevPrincipal

There is no display name: the directory stores none. Keep your own label against id.

FieldTypeDescription
idRequiredDevIdStarts with prn_ for principals created through the API.
kindRequiredDevPrincipalKindhuman for a person, agent for an Agent.
rolesRequiredstring[]Directory roles, such as tenant_admin.
capabilitiesRequiredDevCapability[]What keys issued to this principal can be granted at most.
created_atRequiredstring (date-time)When the principal was created.

DevPrincipalKind

Values: human | agent

DevProcessingFailure

Why processing failed. Codes worth handling: url_fetch_failed (the page could not be fetched), url_no_readable_content (fetched, but there is no article text on it: ingest the text itself), unsupported_input, document_too_large, no_chunks (nothing searchable came out), extraction_timeout (reading the file took longer than its time budget, about 20 s plus 1 s per MiB, and was stopped: the file is stored; convert it to PDF or plain text, or split it, and ingest it again), upload_integrity_mismatch, upload_type_mismatch, not_configured (this deployment has no image or speech recognition, or another step the content needs: the file is stored and readable, and can be reprocessed once that step is enabled), quota_exceeded (the account's monthly model quota on the free plan cannot cover this step, for example transcribing a long recording, so it was not run: the file is stored; reprocess it next month or after the plan is upgraded). Other failures are job_failed or a code of their own; treat a code you do not know as a failed job. upload_type_mismatch is a processing failure: the bytes do not look like the media type the file declared. It is not the request error upload_media_type_mismatch, which POST /v2/uploads/{upload_id}/complete returns when the stored object's media type differs from the one the upload declared.

FieldTypeDescription
codeRequiredstringStable failure code. Branch on this.
messageRequiredstringEnglish text for people. It may change.

DevProcessingProgress

How many of the main steps (extract the text, index it, publish it to search) are done.

FieldTypeDescription
doneRequiredinteger
totalRequiredinteger

DevProcessingQueue

Why the current step has not started yet.

FieldTypeDescription
positionRequiredintegerDue jobs of this account that start before this one. Jobs of other accounts are not counted. For a key limited to some Spaces or to metadata, only jobs in the same Space count (and, with metadata, only files the key can read).
waited_secondsRequiredintegerSeconds since the step was queued.
waiting_forRequiredcapacity | retry | pausedcapacity: every worker is busy; it starts when one is free. Work from other Spaces and accounts takes turns with it, so a large import elsewhere does not hold it back. retry: the previous attempt failed and the step runs again after a short delay. paused: the operator paused processing for this account; the step keeps its place and runs after processing resumes. A key limited to some Spaces or to metadata sees capacity instead of paused.

DevProcessingStage

Where the latest version is in processing. queued: stored, no step has started. extracting: its text is being extracted. indexing: its chunks are being embedded and written to the search indexes. enriching: search finds it; relations, classification, a summary or memories are still being produced. ready: every step has finished. failed: processing gave up.

Values: queued | extracting | indexing | enriching | ready | failed

DevProposal

A proposed change to a file. Visible to its author and to reviewers: the Space owner, and editors who can change the file directly (people, and Agents in direct mode, with the file inside their write_root). Anyone else gets 404.

FieldTypeDescription
idRequiredDevIdlength 1..256
space_idRequiredDevIdlength 1..256
entry_idRequiredDevIdlength 1..256
pathDevPathWhere the file is now. Absent while it is in the trash.
statusRequiredDevProposalStatusopen until a reviewer approves or rejects it, or its author withdraws it.
base_version_idRequiredDevIdlength 1..256
proposed_version_idRequiredDevIdlength 1..256
approved_version_idDevIdThe version approval wrote.
author_principal_idDevIdlength 1..256
reviewed_by_principal_idDevIdWho approved or rejected it.
size_bytesRequiredintegerSize of the proposed content in bytes.
media_typeRequiredstringMedia type of the proposed content.
sha256stringHex SHA-256 of the proposed bytes.
created_atRequiredstring (date-time)When the proposal was made.
reviewed_atstring (date-time)When it was approved or rejected.
closed_atstring (date-time)When it stopped being open, for any reason.

DevProposalReceipt

Prefer: handling=proposal on a write that would otherwise return 403 proposal_required: an Agent in proposal mode changing a file it does not own. A reviewer decides whether to apply it. Poll GET /v2/proposals/{proposal_id} to learn the outcome.

FieldTypeDescription
appliedRequiredfalseAlways false: the write became a proposal and the file did not change.
proposal_idRequiredDevIdlength 1..256
entry_idRequiredDevIdlength 1..256
base_version_idRequiredDevIdThe file's latest version when the proposal was made. Approval needs it to still be the latest.
proposed_version_idRequiredDevIdThe proposed content. It is not a version of the file until approved.

DevProposalStatus

Where a file proposal stands. open: waiting for a reviewer. approved: written as the file's new version. rejected: closed by a reviewer. withdrawn: closed by its author.

Values: open | approved | rejected | withdrawn

DevPurgeTrashReceipt

FieldTypeDescription
purgedRequiredDevPurgedEntry[]The Entries erased by this call, at most 100.
has_moreRequiredbooleanTrue when the trash still holds more: call again.

DevPurgeTrashRequest

FieldTypeDescription
delete_batch_idDevIdErase only what this one delete removed. Without it, everything in the Space's trash that you can see.

DevPurgedEntry

One Entry that was erased, and the job finishing the erasure.

FieldTypeDescription
entry_idRequiredDevIdlength 1..256
job_idRequiredDevIdlength 1..256

DevQueueEstimate

How many items a bulk write put on the processing queue, and roughly how long the queue needs.

FieldTypeDescription
queued_itemsRequiredintegerItems that wrote a new version and so were queued for processing.
eta_secondsintegerEstimated seconds until your account's due jobs are done (see GET /v2/queue). Absent when it cannot be estimated, and for a key limited to some Spaces or to metadata.
pausedbooleanPresent and true when the service operator paused processing for your account. Never present for a key limited to some Spaces or to metadata.

DevRemediation

What to do about an error. Branch on action; the error's message may change.

FieldTypeDescription
actionRequiredstringStable action name, such as check_api_key after unauthorized.
doc_urlstring (uri)Where the action is documented.

DevReplacingMemory

FieldTypeDescription
idRequiredDevIdContains :. Percent-encode it in a path.
textRequiredstringThe statement of the current value.

DevRequestClient

The client a request came from, recognized from its User-Agent. The header itself is not kept.

Values: sdk-typescript | sdk-python | cli | mcp | console | curl | browser | postman | python | node | go | other | unknown

DevRequestLog

One API request, metadata only: no request or response body, no query string, no key. Requests that were not authenticated are not logged, because they belong to no account.

FieldTypeDescription
idRequiredDevIdlength 1..256
created_atRequiredstring (date-time)When the request arrived.
methodRequiredGET | HEAD | POST | PUT | PATCH | DELETE | OPTIONS
routeRequiredstringThe method and route template, such as GET /v2/spaces/:space_id/files. Ids and paths in the URL are not kept.
statusRequiredinteger
error_codestringThe error code the caller received. On a streamed answer that failed after the stream opened, the code of its error event (with status 200).
duration_msRequiredintegerFrom arrival to the response; for a streamed answer, to the end of the stream.
authRequiredapi_key | console | tokenHow the request authenticated: an API key, the console session, or a sign-in token.
principal_idRequiredDevIdlength 1..256
key_idDevIdThe key that made the request.
key_namestringThe key's name and prefix as they are now. Absent once the key is deleted.
key_prefixstring
space_idDevIdThe Space in the path, when there is one.
request_idRequiredstringThe same as the X-Request-Id response header.
trace_idstringOn retrieval calls: trace_id of a search, pack_id of a context pack or an answer. Read it with GET /v2/retrieval/traces/{trace_id}.
clientRequiredDevRequestClient
client_versionstringThe client's version, when its User-Agent has one.

DevRequestLogPage

FieldTypeDescription
dataRequiredDevRequestLog[]The items on this page.
next_cursorDevCursorPass it as cursor to get the next page. Absent on the last page.
retention_daysRequiredintegerHow many days requests are kept.

DevRetrievalClock

How relative time in a query is read. The same two fields on search, context, and answer. Time words are read only on deployments with evidence-based memory enabled; elsewhere the fields are accepted and only answer uses them.

FieldTypeDescription
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.

DevRetrievalExplainFlag

Retrieval options shared by search, context and answer.

FieldTypeDescription
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.

DevRetrievalFilter

Conditions an Entry must meet to be a candidate; they are ANDed, and at least one is required. They apply before ranking, so limit and budget_tokens are spent on matching Entries only, and the freshness buffer and the final authorization check use the same conditions. On search this narrows every hit. On context and answer it narrows every source that reads Entries (knowledge, files, changes, skills, agent profile); memory_view is not filtered. An Entry without metadata, which includes memory facets, never matches a metadata condition.

FieldTypeDescription
metadataobjectExact match on Entry metadata, 1 to 32 keys. A string matches Entries holding that value under the key; {any: [...]} matches Entries holding at least one of them. Keys are ANDed.
source_typesDevSourceType[]Keep Entries of these kinds: the values a hit reports as source_type. file is a file, note is ingested text, web an ingested URL, agent-conversation an ingested conversation. The ingest kind names text, url, and conversation are accepted as aliases of the last three.items 1..8
occurred_fromstring (date-time)Keep Entries that happened at or after this instant. An Entry's time is its occurred_at, or when it was written if it has none.
occurred_tostring (date-time)Keep Entries that happened at or before this instant. A value earlier than occurred_from returns 422.
whereDevFilterConditionA condition on Entry metadata with in, not, exists, numeric and date ranges, combined with and and or. It is ANDed with the other conditions, including metadata. Not taken by the MCP tools.

DevRetrievalKnobs

How much retrieval work a request spends and what it keeps. The same fields on search, context and answer, all optional: leave them out and retrieval is what it was.

FieldTypeDescription
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

DevRetrievalTrace

What a retrieval call recorded. The query text is kept for a search only; a context or answer trace has none.

FieldTypeDescription
idRequiredDevIdlength 1..256
kindRequiredsearch | context | answer
created_atRequiredstring (date-time)
principal_idDevIdlength 1..256
querystringSearch only: the query as it was sent.
citationsRequiredDevTraceCitation[]The Entries and versions the call returned or gave the model.
summaryRequiredDevTraceSummary

DevRevertRequest

FieldTypeDescription
version_idRequiredDevIdThe id of the version to revert to; its content becomes the new latest version.

DevReviewMemoryRequest

FieldTypeDescription
decisionRequiredconfirm | rejectconfirm makes the candidate a memory; reject turns it down.

DevRollbackRequest

FieldTypeDescription
checkpoint_idRequiredDevIdThe id of the checkpoint to roll back to.

DevRotatedWebhookSecret

FieldTypeDescription
webhook_idRequiredDevIdlength 1..256
secretstringThe new secret, effective at once with no overlap. Absent on an Idempotency-Key replay.

DevRoutedMemory

The confirmed distilled memory a passage supports. The passage is the evidence; this is the statement distilled from it. id and text are those of GET /v2/memories/{memory_id}, and the caller can read that memory directly. Candidate, rejected, and superseded memories are never attached. A memory whose attribute has since taken a newer value (the user moved, changed jobs) stays confirmed and is still attached: it is history, not an error. It then carries valid_to and replaced_by, and in a context pack its item is flagged stale. Both are set only when the caller can read the newer memory.

FieldTypeDescription
idRequiredDevIdContains :. Percent-encode it in a path.
kindRequiredstringThe kind of memory, such as preference or event.
textRequiredstringThe memory's statement.
valid_fromstring (date-time)When this value took effect, when that is known.
valid_tostring (date-time)When this stopped being the current value: the moment the next value took effect. Absent while current.
replaced_byDevReplacingMemoryThe current value of the same attribute. Present exactly when a newer value ended this one.

DevSearchHit

One passage a search found, with the Entry and version it was read from, its score, and where the source lives: a path for a file, a url for an ingested page.

FieldTypeDescription
entry_idRequiredDevIdThe Entry the passage is from.
version_idRequiredDevIdThe version the passage was read from.
space_idDevIdAbsent on account memory, which belongs to no Space you can address.
titleRequiredstringThe Entry's title; for a file, its name.
textRequiredstringThe matching passage.
scoreRequirednumberComparable inside one response only.
citation_idRequiredstringc1, c2, ... in the order of this response.
source_typeRequiredstringWhat kind of source it is: file, note, web, agent-conversation, or a memory type.
pathDevPathThe file's path. Absent for an Entry without one.
urlstringOn an Entry ingested from a URL: that URL, to link back to the page. A file has path instead.
occurred_atstring (date-time)When what the passage describes happened: the Entry's occurred_at, or for a conversation the time of its messages. Absent when the source has none.
modified_atstring (date-time)When the version the passage was read from was written. With occurred_at it tells old from new.
stated_datestring (date)The date the passage is stated as of, YYYY-MM-DD. Only fully written dates (year, month, and day) count, and a date mentioned in the middle of a sentence never does: "since 2026-03-01 the API runs on cluster B" is a statement about the present, not about 2026-03-01. The first of these wins: a date the passage marks as its own ("as of", "updated", "last modified", "截至", "更新于" before it, or "updated" / "更新" after it); the date in the heading of its section; a date that starts a line, list item, or clause of the passage; the date in the document's front matter (modified, updated, date, created) or top heading. Where one of them holds several dates, the latest that is not after the version was written is used. Absent when none of them has one: no date is given rather than a wrong one. It tells an older record from a newer one when several files were written at the same moment; when occurred_at is present, prefer that.
stated_date_fromtext | heading | documentWhere stated_date was read: the passage text, a section heading above it, or the document head. On search only text and document occur.
freshnesspending_indexpending_index means the match came from the freshness buffer, lexically only.
memoryDevRoutedMemoryOnly on deployments with evidence-based memory enabled: the confirmed memory distilled from this passage. At most one per file in a response. Never on a pending_index hit.
explainDevHitExplainOnly when the request set explain.

DevSearchHitField

The optional fields of a search hit that fields can keep.

Values: space_id | path | url | occurred_at | modified_at | stated_date | stated_date_from | freshness | memory

DevSearchRequest

FieldTypeDescription
queryRequiredstringWhat to look for, in natural language or keywords.length 1..1000
space_idsDevSpaceRef[]Space ids; default names your default Space, as it does in a path. Omit to search every Space you can read; a key that can read more than 200 Spaces must name them (returns 422 otherwise).items 1..64
pathDevPathRestrict results to this subtree, or to this one file. Resolved in each Space searched. Empty when it exists in none of them.
includememory[]["memory"] adds memory facets to the results and switches ranking to the memory profile: no relevance floor, and at most one passage per Entry. The only accepted value, given once.items 1..1
limitintegerHow many hits to return at most. This is a total, unlike a list's page size.1..50, default: 20
filterDevRetrievalFilterNarrow what is searched before ranking. Combines with path and space_ids: all of them must hold.
tierDevContextTierAs on context: fast uses no model and matches words only (scores are not relevance, partial is true when there are hits); standard adds semantic search and reranking; deep looks at twice as many candidates and reranks twice as many.default: "standard"
fieldsDevSearchHitField[]Keep only these optional fields on each hit. entry_id, version_id, title, text, score, citation_id and source_type are always there. Each field once. Leave it out for every field.max items 9
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.

DevSearchResponse

FieldTypeDescription
dataRequiredDevSearchHit[]The hits, best first.
trace_idRequiredDevIdlength 1..256
partialRequiredbooleanTrue when a retrieval branch degraded or the scores are not calibrated relevance.
explainDevExplainSummaryOnly when the request set explain.
pending_processingDevPendingProcessingOnly when Entries in the searched Spaces are still being processed: their text may be missing from this result. GET /v2/spaces/{space_id}/processing reports when they become searchable.

DevSetSpaceMemberRequest

FieldTypeDescription
roleRequirededitor | viewereditor can write; viewer can only read. Ownership cannot be granted here.
write_modeDevWriteModeDefaults to proposal for a new member; otherwise the current value stays.
write_rootstring | nullLimit this member's writes to the subtree under an existing directory. It only narrows: role, capabilities, and API key bounds still apply, reads are unchanged, and the directory itself cannot be renamed, moved, or deleted by the member. Absent keeps the current value; null or / removes the limit. A missing directory returns 404 not_found and a file returns 409 not_a_directory, both with field: write_root. Writes outside it return 403 outside_write_root, as do writes to Entries without a path, except the member's own Agent memory.length 1..8192
read_rootstring | nullLimit what this member can read to an existing directory and everything under it. It only narrows: role, capabilities, and API key bounds still apply. Absent keeps the current value; null or / removes the limit. A missing directory returns 404 not_found and a file returns 409 not_a_directory, both with field: read_root. Outside it, reads return 404 as if nothing were there, Entries without a path are outside it except the member's own Agent memory, and branches in this Space return 403 outside_read_root. Without a write_root the member writes under its read_root; a write_root must be the read_root or below it, or the request returns 422 write_root_outside_read_root (field: write_root), including when a new read_root leaves the current write_root outside.length 1..8192

DevSnapshot

A read-only picture of a whole Space at one moment: every file's path and the version it had. Versions are immutable, so a snapshot copies no bytes. Read it with snapshot on tree, files, and files/content-url. Files deleted later stay readable through the snapshot; a purged file leaves it as soon as the purge is requested. Directories come from file paths, so an empty directory is not in a snapshot, and neither is content without a path (memories, ingested URLs, and text).

FieldTypeDescription
idRequiredDevIdlength 1..256
space_idRequiredDevIdlength 1..256
nameRequiredstringThe snapshot's name. snapshot= takes it in place of the id.
file_countRequiredintegerFiles when the snapshot was taken. A purge does not lower it. For a member with a read_root, only the files that were under it.
changes_cursorRequiredDevCursorThe change-feed position at the same moment. Pass it to changes to follow everything written after the snapshot, with no gap and no overlap.
created_by_principal_idRequiredDevIdlength 1..256
created_atRequiredstring (date-time)When the snapshot was taken.

DevSnapshotRef

A snapshot id, or the name of a snapshot in this Space. An id starts with snp_; a name cannot.

Values: string

DevSourceType

Values: string

DevSpace

A Space keeps one end user's or one project's files, Entries, and memories apart from the rest of the account. The view also reports the caller's own role in it and the caller's read and write roots.

FieldTypeDescription
idRequiredDevIdStarts with col_. default is accepted wherever a Space id goes in a path or a query, and in the space_id and space_ids request fields that say so.
nameRequiredstringThe Space's name.
descriptionstringA note about what the Space is for.
external_idstringYour own id for this Space, such as your user id, when you set one. Unique among the account's Spaces; GET /v2/spaces?external_id= finds the Space by it.
is_defaultRequiredbooleanTrue on the Space that default resolves to for you.
access_roleRequiredDevSpaceRoleYour role in this Space: owner, editor, or viewer.
read_rootDevPathYour own read root in this Space, as its path at the moment of reading. Absent when you can read the whole Space. Start tree here: everything outside it answers as if it did not exist.
write_rootDevPathYour own write root in this Space, as its path at the moment of reading. Absent when your writes are not limited.
created_atRequiredstring (date-time)When the Space was created.
updated_atRequiredstring (date-time)When its name, description, or external_id last changed.

DevSpaceActivity

Recent changes of a Space, grouped by who made them. Principals are listed most recently active first.

FieldTypeDescription
sinceRequiredstring (date-time)The start of the period.
truncatedRequiredbooleanTrue when the period held more than the 1000 changes this looks back over: older ones are not counted.
dataRequiredDevActivityActor[]One item per principal that changed something.

DevSpaceDeletion

The receipt of a deleted Space. Its content is erased in the background.

FieldTypeDescription
space_idRequiredDevIdThe Space that was deleted.
deletedRequiredtrueAlways true: the Space is gone from every read.
entriesRequiredintegerHow many Entries the Space held, trashed ones included. They are being erased.

DevSpaceMember

FieldTypeDescription
principal_idRequiredDevIdlength 1..256
roleRequiredDevSpaceRoleowner, editor, or viewer.
write_modeRequiredDevWriteMode
write_rootDevPathThe directory this member can write under, as its path at the moment of reading. Absent when the member can write anywhere its role allows. It follows the directory through renames and moves.
read_rootDevPathThe directory this member can read under, as its path at the moment of reading. Absent when the member can read the whole Space. When the caller has a read_root itself, another member's roots are only shown if they are inside the caller's read_root.

DevSpaceMemoryProgress

Memory extraction of a Space: a separate lane that starts once an Entry is searchable.

FieldTypeDescription
pendingRequiredintegerEntries whose memory extraction is queued or running. They are already counted as searchable or processing.
eta_secondsintegerUpper bound in seconds for the pending extractions, from the account's hourly memory-extraction rate. Absent when nothing is pending.
filesRequiredindex_only | distillWhether files written by path are distilled into memories on this deployment. index_only: files are indexed and searchable, and memories come from conversations and ingested text. distill: files are distilled too.

DevSpaceProcessing

Processing progress of a Space.

FieldTypeDescription
space_idRequiredDevIdlength 1..256
countsRequiredDevSpaceProcessingCounts
stagesRequiredDevSpaceProcessingStages
searchable_per_minutenumberEntries per minute that became searchable over the last five minutes. Absent when none did.
eta_secondsintegerEstimated seconds until every queued and processing Entry is searchable, from that rate. Absent without a rate or when nothing is pending.
oldest_queued_secondsintegerSeconds the longest-waiting due step in this Space has been queued. Absent when nothing waits.
waiting_for_capacityRequiredbooleanTrue when steps of this Space are due and wait for a free worker. Work from different Spaces and accounts takes turns.
queue_positionintegerDue steps of this account, in other Spaces, that start before this Space's next one. Absent when nothing waits, and for a key limited to some Spaces.
memoryRequiredDevSpaceMemoryProgressMemory extraction, reported apart: an Entry waiting only for it is searchable, not processing.
as_ofRequiredstring (date-time)When the numbers were read.

DevSpaceProcessingCounts

Entries of a Space by where their latest version is. Each Entry is counted once.

FieldTypeDescription
queuedRequiredintegerStored; no step has started.
processingRequiredintegerText extraction or indexing has started.
searchableRequiredintegerSearch finds them; enrichment (relations, classification, summary, memories) is still running.
readyRequiredintegerEvery step has finished.
failedRequiredintegerProcessing gave up. GET /v2/entries/{id}/processing says why.

DevSpaceProcessingStages

Entries that are not ready yet, by step. enriching equals counts.searchable.

FieldTypeDescription
queuedRequiredinteger
extractingRequiredinteger
indexingRequiredinteger
enrichingRequiredinteger

DevSpaceRef

A Space id; default for your default Space (your own, or the only Space you can see); or ext:<external_id> for the Space that carries your own id for it, such as ext:user-42. All three work in a path, in ?space_id=, and in space_ids. An external_id that no visible Space carries returns 404.

Values: string

DevSpaceRole

A principal's role in one Space. An operation needs both a capability and a minimum role. viewer: read files, Entries, the tree, and memories; search, build context, answer, and export. editor: what a viewer can, plus write, edit, move, trash, restore, revert, ingest, import, take snapshots, work on branches, and review file proposals (an Agent also needs write_mode: direct). owner: what an editor can, plus manage members and webhooks, change version messages, erase Entries, and delete the Space. An operation's description states any stricter rule.

Values: owner | editor | viewer

DevSpaceUsageFigure

FieldTypeDescription
metricRequiredwrites | storage_bytes | model_tokens | model_spend_micro_usdwrites (per calendar month, UTC), storage_bytes (cumulative), model_tokens (per calendar month, UTC: tokens the service's language models generated for this account: answers, distillation, summaries, classification and memory consolidation), or model_spend_micro_usd (per calendar month, UTC: every billable model call for this account, including speech recognition, OCR, reranking, embeddings and web search, at the service's list prices, in millionths of a US dollar). The two model metrics are only in tenant_totals, only on a plan that limits them, and used includes calls still in progress.
window_startRequiredstring (date-time)The start of the window used counts from. The Unix epoch for a cumulative metric.
usedRequiredintegerHow much of the metric has been used in the window.
limitintegerThe quota. Absent when the metric is not limited.
space_idRequiredDevIdlength 1..256

DevStartDreamRequest

FieldTypeDescription
scopeDevDreamScopeDefault: agent for an Agent key (its own private memory), project otherwise. Only an Agent key has an agent scope; anyone else naming it returns 422.

DevTableContent

The first sheet and at most its first 200 rows; row_count is the whole sheet.

FieldTypeDescription
columnsRequiredstring[]Column headers, in order.
rowsRequiredstring[][]At most the first 200 rows, each a list of cell texts in column order.
row_countRequiredintegerRows in the whole sheet, which can be more than rows holds.

DevTraceCandidates

FieldTypeDescription
lexicalinteger
denseinteger
dense_documentinteger
memoryinteger
relationinteger

DevTraceCitation

FieldTypeDescription
entry_idRequiredDevIdlength 1..256
version_idRequiredDevIdlength 1..256
citation_idstring
sourcestring

DevTraceSource

FieldTypeDescription
sourceRequiredstring
budgetinteger
usedinteger
pickedinteger
omittedinteger
whystring

DevTraceStage

FieldTypeDescription
stageRequiredstringThe stage, such as embed, lexical, dense, rerank or authorize.
statusRequiredsucceeded | failed | cancelled | skipped
duration_msintegerOnly for a tenant_admin with knowledge:manage.

DevTraceSummary

Counts and decisions recorded for the retrieval. Which fields are present depends on kind.

FieldTypeDescription
candidatesDevTraceCandidatesSearch: candidates per branch, counting only those the caller could read. fused_count counts the same way. Both are absent on traces recorded before readable counting.
fused_countinteger
ranked_countinteger
final_countinteger
rerank_appliedboolean
partialboolean
duration_msinteger
stagesDevTraceStage[]Search: time spent in each stage.
purposestringContext and answer: the routing decision, as route on the response.
tierstring
rules_firedstring[]
sourcesDevTraceSource[]
tokens_usedinteger
budget_tokensinteger

DevTreeChmod

Valid only with branch; returns 422 without it. On a merge 755 becomes the metadata key mirabase.mode.

FieldTypeDescription
opRequiredchmodAlways chmod.
pathRequiredDevPathlength 1..4096
modeRequired644 | 755644, or 755 for an executable file.

DevTreeCopied

FieldTypeDescription
pathRequiredDevPathWhere the copy is.
entry_idRequiredDevIdlength 1..256
source_entry_idRequiredDevIdlength 1..256

DevTreeCopy

Copy a file or a whole directory inside this Space. to is the complete new path; missing parents are created. An occupied to returns 409 path_conflict, and copying a directory into itself returns 409 copy_into_descendant. Each copied file is a new Entry whose first version shares the source's latest bytes; the history is not copied. The copy is processed like a new file and counts one writes and its full size in storage_bytes. An Agent in proposal mode may copy files it does not own. Counts toward the request's 200-node limit. With branch it returns 422.

FieldTypeDescription
opRequiredcopyAlways copy.
fromRequiredDevPathlength 1..4096
toRequiredDevPathlength 1..4096

DevTreeDelete

FieldTypeDescription
opRequireddeleteAlways delete.
pathRequiredDevPathlength 1..4096
recursivebooleanRequired for a non-empty directory; otherwise returns 409 directory_not_empty.default: false

DevTreeJobResult

What a tree job did. Only counts and ids, apart from a failed merge's first 100 conflicts.

FieldTypeDescription
delete_batch_idDevIdA recursive delete: the id to pass to restore, which brings back everything the job deleted, including the part done before a failure.
copiesintegerFiles copied so far.
restoredintegerNodes restored.
mergedintegerA merge: paths written to main.
proposedintegerA merge: files proposed instead of written.
skippedintegerA merge, an export, or an import: items left out.
conflictsDevMergeConflict[]A merge that failed with merge_conflict: the first 100 conflicting paths.max items 100
filesintegerAn export: files in the archive. skipped counts files with no bytes to export.
bytesintegerAn export: total bytes of the files in the archive.
archiveDevArchiveAn export that succeeded: the archive. Download it with GET /v2/jobs/{job_id}/content-url.
createdintegerAn import: new files created. skipped counts members left alone (on_conflict: "skip", the same bytes, or outside files/ in an exported archive).
updatedintegerAn import: files that already existed and got a new version.
failedintegerAn import: members that could not be written.
failuresDevImportFailure[]An import: the first 100 members that could not be written, by index in the archive. Never their paths.max items 100

DevTreeMkdir

Creates missing parents too. A directory that already exists is a success.

FieldTypeDescription
opRequiredmkdirAlways mkdir.
pathRequiredDevPathlength 1..4096

DevTreeMove

Move or rename a file or directory. to is the complete new path; missing parents are created. An occupied to returns 409 path_conflict: nothing is overwritten or merged. A rename counts its whole subtree toward the request's node limit, the same as a move. Moving a directory inside itself returns 409 move_into_descendant.

FieldTypeDescription
opRequiredmoveAlways move.
fromRequiredDevPathlength 1..4096
toRequiredDevPathlength 1..4096

DevTreeNode

One node of a Space's directory tree: a directory, a file, or, on a branch listing, a symlink. A file carries what a client needs to read it or write it conditionally: its Entry, version, size, media type, and etag.

FieldTypeDescription
pathRequiredDevPathlength 1..4096
nameRequiredstringThe last segment of path, as it was written.
kindRequiredDevTreeNodeKinddir or file; a branch listing also has symlink.
entry_idDevIdlength 1..256
version_idDevIdOn files: the latest version. Through a snapshot, the version the snapshot pinned. Not on a branch listing.
size_bytesintegerOn files. On a branch listing, only on the paths the branch changed.
etagstringOn files, except through a snapshot. Send back in If-Match, or compare with the one you hold to tell whether the content changed. On a branch listing, only on the files the branch changed.
sha256stringOn files a branch changed, and on files listed through a snapshot when known.
media_typestringOn files. On a branch listing, only on the files the branch changed.
modified_atstring (date-time)On files of the main listing: when the content last changed, which is when the latest version was written. updated_at also moves on a rename or a move.
mode644 | 755644 or 755. On paths a branch changed.
updated_atRequiredstring (date-time)When the node last changed, including renames and moves.

DevTreeNodeKind

Values: dir | file | symlink

DevTreeOperation

Values: DevTreeMkdir | DevTreeMove | DevTreeCopy | DevTreeDelete | DevTreeRestore | DevTreeSymlink | DevTreeChmod

DevTreeOperationsRequest

Atomic: all operations apply in order, or none do. One request deletes, restores, or copies at most 200 nodes and moves at most 1000. With branch, restore and copy return 422 (roll back to a checkpoint instead).

FieldTypeDescription
operationsRequiredDevTreeOperation[]1 to 200 operations, applied in order.items 1..200

DevTreeOperationsResponse

FieldTypeDescription
delete_batch_idDevIdPresent when the request deleted anything; restores the batch as one unit.
copiesDevTreeCopied[]Present when the request copied anything: one item per copied file.

DevTreePage

One page of a directory. With recursive, every descendant in a stable order that is not alphabetical; without it, the direct children sorted by name. A path that names a file returns that file. / or no path is the root.

FieldTypeDescription
dataRequiredDevTreeNode[]The items on this page.
next_cursorDevCursorPass it as cursor to get the next page. Absent on the last page.
changes_cursorRequiredDevCursorPass to changes, not back to this listing: next_cursor is the page cursor. Taken before this page was read, so the feed continues from here without a gap. Keep the one from the first page: events may repeat what the listing already showed, never the reverse.

DevTreeRestore

Restore one file by path, or everything a request deleted by delete_batch_id: send exactly one. Missing parents are recreated. A name collision returns 409 path_conflict; nothing is renamed.

FieldTypeDescription
opRequiredrestoreAlways restore.
pathDevPathlength 1..4096
delete_batch_idDevIdlength 1..256

DevUpdateBranchRequest

Setting ttl_days also renews: expires_at becomes now plus that many days.

FieldTypeDescription
namestringA new name, 1 to 255 characters.length 1..255
ttl_daysinteger1 to 365. Setting it also renews the branch: expires_at becomes now plus that many days.1..365

DevUpdateEntryRequest

A new title is a new version: the title is part of what gets indexed, and versions do not change. The same title does nothing. A file's title is its name, so title on a file returns 422: rename it with tree/operations. Send at least one field.

FieldTypeDescription
titlestringA new title, 1 to 512 characters. Not supported on a file: rename it with tree/operations.length 1..512
metadataDevMetadataReplaces the Entry's metadata as a whole: send every key you want to keep, or {} to clear it. It does not create a version. Works on any Entry, a file included. Filters see the change once the Entry is reindexed, usually within seconds.
metadata_patchobjectChanges metadata key by key instead of replacing it: a key with a value is set, a key with null is removed, and the keys you do not mention stay. Two callers changing different keys do not overwrite each other. Not together with metadata. The result still holds at most 32 values.
memory_excludebooleantrue retires the facts distilled from this Entry and stops distilling it; search and reading are unaffected. false distills it again, without restoring facts you previously forgot or corrected.
occurred_atstring (date-time) | nullWhen the source itself happened. null clears it, and retrieval's time filter goes back to when the Entry was written. It does not make a version; filters see the change once the Entry is reindexed, usually within seconds. Memories already distilled keep the time they were given.

DevUpdateMemoryRequest

Send at least one.

FieldTypeDescription
pinnedbooleanOnly on a memory written as an Entry. Pinning changes what a Space starts with, so a person must own the Space.
valid_tostring (date-time)Closes a distilled fact or an account memory. A memory written as an Entry has no validity window: forget or correct it.

DevUpdateMemorySettingsRequest

Give at least one field; a field left out keeps its value.

FieldTypeDescription
memory_dreamingDevMemoryDreamingModeauto returns 422 until it is available.
dormancyDevMemoryDormancyModeWhat a dream does with unused memories: report (the default) or apply.
d4DevMemoryD4ModeWhether a dream asks a model to compare memories: off (the default), shadow, or propose.

DevUpdatePrincipalRequest

FieldTypeDescription
grant_capabilitiesRequiredDevCapability[]Replaces the principal's capabilities. You must hold every capability in this list and every capability the principal has now.

DevUpdateSpaceRequest

At least one field is required. null clears the description or the external_id.

FieldTypeDescription
namestringA new name, 1 to 512 characters.length 1..512
descriptionstring | nullA new description, or null to clear it.length 1..4096
external_idstring | nullA new external_id, 1 to 256 characters, or null to clear it. A value already in use returns 409 space_external_id_taken.length 1..256

DevUpdateVersionMessageRequest

FieldTypeDescription
messageRequiredstringThe version's new message, at most 120 characters.max length 120

DevUpdateWebhookRequest

FieldTypeDescription
urlstringA new receiver URL, under the same rules as on create.max length 2048
opsDevChangeOp[]The event kinds to send from now on. No repeats.items 1..5
descriptionstring | nullnull clears it.max length 256
statusDevWebhookStatusdisabled stops deliveries (with reason manual). active reopens a disabled webhook, clears consecutive_failures, and tries right away; the batch in flight is resent as it was.
reset_cursortrueSkip everything not yet delivered and continue from now. Required to reopen a webhook disabled with cursor_expired.

DevUpload

FieldTypeDescription
idRequiredDevIdlength 1..256
pathRequiredDevPathlength 1..4096
part_sizeRequiredintegerEvery part is exactly this long except the last.
expires_atRequiredstring (date-time)When the session ends. It is not extended.

DevUploadPartHeaders

Send these on every part.

FieldTypeDescription
content-typeRequiredstringThe Content-Type every part's PUT must carry.

DevUploadPartTarget

FieldTypeDescription
part_numberRequiredintegerThe part this URL is for, numbered from 1.
urlRequiredstring (uri)PUT the part here.

DevUploadParts

Parts already received are left out of data, so asking again resumes an upload.

FieldTypeDescription
dataRequiredDevUploadPartTarget[]One upload target per part that is still to be uploaded.
receivedRequiredDevCompletedPart[]The parts you asked about that are already uploaded, each with the etag that complete takes. A client that lost its own record (a crash, another machine) resumes with these instead of uploading the file again.
expires_atRequiredstring (date-time)At most five minutes away.
required_headersRequiredDevUploadPartHeaders

DevUploadPartsRequest

FieldTypeDescription
part_numbersRequiredinteger[]Numbered from 1.items 1..128

DevUsageFigure

FieldTypeDescription
metricRequiredwrites | storage_bytes | model_tokens | model_spend_micro_usdwrites (per calendar month, UTC), storage_bytes (cumulative), model_tokens (per calendar month, UTC: tokens the service's language models generated for this account: answers, distillation, summaries, classification and memory consolidation), or model_spend_micro_usd (per calendar month, UTC: every billable model call for this account, including speech recognition, OCR, reranking, embeddings and web search, at the service's list prices, in millionths of a US dollar). The two model metrics are only in tenant_totals, only on a plan that limits them, and used includes calls still in progress.
window_startRequiredstring (date-time)The start of the window used counts from. The Unix epoch for a cumulative metric.
usedRequiredintegerHow much of the metric has been used in the window.
limitintegerThe quota. Absent when the metric is not limited.

DevUsagePage

Paginated like every list, with tenant-wide totals beside the page rather than inside it.

FieldTypeDescription
dataRequiredDevSpaceUsageFigure[]One figure per Space and metric, ordered by Space id, then metric.
next_cursorDevCursorlength 1..1024
tenant_totalsDevUsageFigure[]On the first page only, for a tenant_admin key without Space restrictions.
planDevPlanThe account's plan. The limit of each figure is the plan's.

DevVersion

One immutable version of an Entry. Its content never changes; only status moves while it is processed.

FieldTypeDescription
idRequiredDevIdStarts with ver_.
entry_idRequiredDevIdThe Entry this is a version of.
statusRequiredDevVersionStatusHow far processing has progressed.
updated_fromDevIdThe version this one replaced. Absent on the first version.
messagestringThe note its author attached, like a commit message.
author_principal_idDevIdWho wrote it.
created_atRequiredstring (date-time)When it was written. For a file this is the modification time of that content.

DevVersionDiff

Two versions of one Entry. identical compares the bytes' SHA-256 without reading them, and an identical pair has an empty unified_diff. Text files of at most 1 MiB compare their original bytes; anything else compares the text processing extracted, once both versions are processed.

FieldTypeDescription
entry_idRequiredDevIdlength 1..256
from_version_idRequiredDevIdlength 1..256
to_version_idRequiredDevIdlength 1..256
identicalRequiredbooleanTrue when both versions hold the same bytes.
basisRequiredDevDiffBasis
unified_diffstringThe differences in unified diff format. Empty when identical; absent when diff_omitted is set.
diff_omittedDevDiffOmitted

DevVersionKind

How a version came about. Versions merged before branch merges were recorded report edit. title is a new title over the same bytes.

Values: create | edit | revert | title | proposal_accept | branch_merge | copy

DevVersionStatus

How far processing of one version has progressed. accepted: stored, not yet picked up. processing: being parsed and indexed. published: done and serving search. no_recallable_content: done, and there was nothing to index (an empty file, an image without text); not an error. failed: processing gave up; POST .../reprocess retries it. discarded: an edit whose processing failed, set aside while the previous version keeps serving search. On the Entry these read as knowledge.state: published and no_recallable_content are indexed, failed is failed, and the rest are readable, or searchable while the freshness buffer already finds the text.

Values: accepted | processing | published | no_recallable_content | failed | discarded

DevWebhook

A subscription to one Space's change feed (main only, not branches). Mirabase POSTs batches of up to 100 events in order, at least once, one batch in flight at a time. Each request carries Mirabase-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "t.body" keyed by the secret>, Mirabase-Webhook-Id, and Mirabase-Delivery-Id; a retry resends the same batch with the same delivery id. The body is a DevWebhookPayload. Any 2xx within 10 seconds is success. Any other status, a redirect (redirects are not followed), or no answer within 10 seconds is a failure, and the batch is retried after 30 seconds, doubling each time up to an hour. Verify the signature in constant time, and reject a t more than 5 minutes from your clock.

FieldTypeDescription
idRequiredDevIdlength 1..256
space_idRequiredDevIdlength 1..256
urlRequiredstring (uri)https on port 443.
opsRequiredDevChangeOp[]Event kinds to send. Events of other kinds are skipped, not queued.
descriptionstringA note for people.
statusRequiredDevWebhookStatusactive, or disabled when deliveries have stopped; disabled_reason says why.
disabled_reasonDevWebhookDisabledReasonPresent when status is disabled.
cursorRequiredDevCursorThe change-feed position after the last batch delivered or skipped.
consecutive_failuresRequiredintegerFailed attempts since the last success.
last_success_atstring (date-time)When a batch was last delivered.
last_failure_atstring (date-time)When an attempt last failed.
next_attempt_atstring (date-time)When the next attempt may start. Absent when disabled.
created_by_principal_idRequiredDevIdlength 1..256
created_atRequiredstring (date-time)When the webhook was created.
updated_atRequiredstring (date-time)When the webhook's settings or state last changed.

DevWebhookDelivery

One attempt. Neither the payload, the URL, nor the response body is kept. Kept 30 days.

FieldTypeDescription
idRequiredDevIdlength 1..256
delivery_idRequiredDevIdThe batch, the same as Mirabase-Delivery-Id. Attempts at one batch share it.
first_seqRequiredintegerThe first change sequence number of the batch, before filtering.
last_seqRequiredintegerThe last change sequence number of the batch, before filtering.
event_countRequiredintegerEvents sent after filtering.
attemptRequiredinteger1 for the first attempt at this batch.
outcomeRequiredDevWebhookOutcomedelivered on any 2xx answer, otherwise failed.
http_statusintegerThe receiver's HTTP status, when it answered.
error_codeDevWebhookErrorCode
duration_msRequiredintegerHow long the attempt took, in milliseconds.
created_atRequiredstring (date-time)When the attempt was made.

DevWebhookDisabledReason

Why a webhook stopped. failing: 20 failed attempts in a row. receiver_gone: the receiver answered 410. cursor_expired: its position fell out of the 90-day change feed. credential_revoked: the API key that created it was revoked or expired, or the developer account was suspended. access_lost: its creator no longer owns the Space or lost knowledge:read or knowledge:manage. manual: someone set status to disabled.

Values: failing | receiver_gone | cursor_expired | credential_revoked | access_lost | manual

DevWebhookErrorCode

http_status is a non-2xx answer; the others failed before one arrived.

Values: timeout | network | blocked_address | http_status | tls

DevWebhookOutcome

Values: delivered | failed

DevWebhookPayload

The JSON body of a webhook request. events are filtered by the webhook's ops, as the creator would see them on changes now. cursor is the change-feed position after this batch: pass it to changes to catch up from the same point.

FieldTypeDescription
typeRequiredspace.changesAlways space.changes.
webhook_idRequiredDevIdlength 1..256
delivery_idRequiredDevIdlength 1..256
space_idRequiredDevIdlength 1..256
eventsRequiredDevChange[]
cursorRequiredDevCursorlength 1..1024

DevWebhookStatus

Values: active | disabled

DevWhoami

FieldTypeDescription
tenant_idRequiredDevIdThe account this key belongs to.
principalRequiredDevPrincipalWho the request acts as.
keyDevWhoamiKeyAbsent when the request was not authenticated with an API key.
effective_capabilitiesRequiredDevCapability[]Principal capabilities intersected with key capabilities.

DevWhoamiKey

FieldTypeDescription
idRequiredDevIdlength 1..256
prefixRequiredstringThe first characters of the key: safe to show, enough to tell keys apart.
capabilitiesRequiredDevCapability[]What the key itself allows. A request acts with effective_capabilities, the part the principal also has.
allowed_space_idsDevId[]The Spaces the key is narrowed to. Absent means not narrowed to specific Spaces.
metadata_scopeDevMetadataScopeThe metadata scope the key is limited to. Absent means not limited by metadata.
expires_atstring (date-time)When the key stops working. Absent when it does not expire.

DevWriteMode

Only applies to Agents, and only to files they do not own. The Space owner is always direct.

Values: proposal | direct

OperatorUsageTotals

Usage and the operator's cost for one group of calls.

FieldTypeDescription
callsRequiredinteger
errorsRequiredinteger
input_tokensRequiredinteger
output_tokensRequiredinteger
total_tokensRequiredinteger
audio_secondsRequirednumber
imagesRequiredinteger
model_usdRequirednumber
unpriced_callsRequiredintegerCalls whose model has no price; their spend is not in model_usd.