Schemas
MarkdownThe 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.
| Field | Type | Description |
|---|---|---|
queuedRequired | integer | Jobs waiting: due ones plus delayed ones. |
dueRequired | integer | Jobs that can run now and wait for a worker. |
delayedRequired | integer | Jobs waiting for a retry backoff or a scheduled time. |
runningRequired | integer | |
pausedRequired | boolean | True when the service operator paused processing for this account; nothing runs until it is resumed. |
paused_at | string (date-time) | |
oldest_queued_seconds | integer | How long the oldest due job has been waiting. Absent with nothing due. |
eta_seconds | integer | Estimated 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. |
limitRequired | integer | tenant_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_ofRequired | string (date-time) |
DevActivityActor
What one principal changed in the period.
| Field | Type | Description |
|---|---|---|
principal_id | DevId | Who made the changes. Absent for changes the service made itself. |
last_changed_atRequired | string (date-time) | When this principal last changed something. |
change_countRequired | integer | How many changes this principal made in the period. |
filesRequired | DevActivityFile[] | The Entries changed, most recently changed first, at most 50. |
files_truncated | true | Present 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.
| Field | Type | Description |
|---|---|---|
entry_idRequired | DevId | The Entry that changed. |
path | DevPath | Where it was at its latest change. Absent for an Entry without a path. |
opRequired | DevChangeOp | The latest change: create, update, move, delete, or restore. |
version_id | DevId | The version the latest change wrote, when it wrote one. |
changed_atRequired | string (date-time) | When the latest change was committed. |
change_countRequired | integer | How many times this principal changed the Entry in the period. |
DevAnswer
| Field | Type | Description |
|---|---|---|
statusRequired | DevAnswerStatus | answered, or abstained when the evidence did not support an answer. |
answerRequired | string | Empty when abstained. Cites evidence as [cN]. |
reason | DevAnswerAbstainReason | Present when abstained. |
citationsRequired | DevAnswerCitation[] | Only the evidence answer cites, in order of first citation. |
evidence | DevAnswerEvidence[] | Only when the request has include: ["evidence"]: every item the model read, in the order it read them. |
evidence_countRequired | integer | Items the model was given. |
pack_idRequired | DevId | Report what you used with POST /v2/retrieval/context/{pack_id}/feedback. |
partialRequired | boolean | True when a retrieval branch degraded, so evidence may be missing. |
pending_processing | DevPendingProcessing | Only when Entries in the searched Spaces are still being processed: the answer may lack them. |
routeRequired | DevContextRoute | How the evidence was chosen, as on a context pack. |
explain | DevAnswerExplain | Only 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
| Field | Type | Description |
|---|---|---|
citation_idRequired | string | Appears as [cN] in answer. |
entry_idRequired | DevId | The Entry the passage is from. |
version_idRequired | DevId | The version the passage was read from. |
space_id | DevId | The Space of that Entry. Absent on account memory. |
path | DevPath | The file's path. Absent for an Entry without one. |
url | string | On an Entry ingested from a URL: that URL, to link back to the page. A file has path instead. |
occurred_at | string (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_at | string (date-time) | When the version the passage was read from was written. With occurred_at it tells old from new. |
stated_date | string (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_from | text | heading | document | Where stated_date was read: the passage text, a section heading above it, or the document head. |
titleRequired | string | The Entry's title; for a file, its name. |
sourceRequired | DevContextSource | Which context source supplied the passage. |
textRequired | string | The passage the model read. |
explain | DevHitExplain | Only when the request set explain. |
DevAnswerEvidence
One item the model read, as a citation without its text.
| Field | Type | Description |
|---|---|---|
citation_idRequired | string | The id the model could cite it by. |
entry_idRequired | DevId | The Entry the passage is from. |
version_idRequired | DevId | The version the passage was read from. |
space_id | DevId | The Space of that Entry. Absent on account memory. |
path | DevPath | The file's path. Absent for an Entry without one. |
url | string | On an Entry ingested from a URL: that URL. |
occurred_at | string (date-time) | As on a citation. |
modified_at | string (date-time) | As on a citation. |
stated_date | string (date) | As on a citation. |
stated_date_from | text | heading | document | As on a citation. |
titleRequired | string | The Entry's title; for a file, its name. |
sourceRequired | DevContextSource | Which context source supplied the passage. |
explain | DevHitExplain | Only when the request set explain. |
DevAnswerExplain
explain on an answer: the retrieval summary, plus which citations each sentence uses.
| Field | Type | Description |
|---|---|---|
termsRequired | string[] | The terms the lexical branch searched for. |
candidatesRequired | DevExplainCandidateCount[] | Candidates per branch, counting only those you can read. Branches that returned nothing you can read are left out. |
fused_countRequired | integer | Candidates you can read after the branches were merged. |
rerankRequired | DevExplainRerankSummary | |
clauses | string[] | For a task that states several things: the clauses that were searched for separately. |
sentencesRequired | DevAnswerSentence[] | The answer split into sentences. Empty when the answer abstained. |
DevAnswerRequest
| Field | Type | Description |
|---|---|---|
questionRequired | string | The question to answer, 1 to 4000 characters.length 1..4000 |
space_ids | DevSpaceRef[] | 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 |
purpose | DevContextPurpose | What the answer is for, as on context: task, coding, research, or audit. |
weights | DevContextWeights | As 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. |
tier | DevContextTier | How much retrieval work goes into finding the evidence, as on context: fast, standard, or deep.default: "standard" |
budget_tokens | integer | Budget for the evidence the model reads.500..16000, default: 4000 |
history | DevAnswerTurn[] | 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_language | string | A BCP 47 tag such as en or zh-CN. Only changes the language of answer.max length 35 |
filter | DevRetrievalFilter | Narrow the evidence the answer may draw on, as on context. |
include | evidence[] | ["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 |
stream | boolean | True 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. |
profile | string | A 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. |
rerank | boolean | false 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_score | number | The 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_entry | integer | At 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_time | string (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. |
timezone | string | IANA 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. |
explain | boolean | True 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
| Field | Type | Description |
|---|---|---|
textRequired | string | One sentence of answer, with its [cN] marks. |
citation_idsRequired | string[] | The citations in that sentence, in order of first mention. |
DevAnswerStatus
Values: answered | abstained
DevAnswerStreamDelta
data of a delta event of a streamed answer.
| Field | Type | Description |
|---|---|---|
textRequired | string | The 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.
| Field | Type | Description |
|---|---|---|
request_idRequired | string | The request's id, the same as the X-Request-Id response header. Quote it when you report a problem. |
pack_idRequired | DevId | The same pack_id the final event carries. |
evidence_countRequired | integer | Items the model is given. 0 means the answer will be an abstention with reason no_evidence. |
partialRequired | boolean | True when a retrieval branch degraded, so evidence may be missing. |
evidence | DevAnswerEvidence[] | Only when the request has include: ["evidence"]: every item the model reads, the same list final carries. |
DevAnswerTurn
DevApiKey
A credential, not a principal. It can only narrow what its principal may do.
| Field | Type | Description |
|---|---|---|
idRequired | DevId | Starts with key_. Not the secret: the token is shown once, when the key is created or rotated. |
principal_idRequired | DevId | The principal the key acts as. |
nameRequired | string | Your label for the key. |
prefixRequired | string | Non-secret token prefix, for recognizing a key in a list. |
capabilitiesRequired | DevCapability[] | What the key may do. Never more than its principal's capabilities. |
allowed_space_ids | DevId[] | Absent means not narrowed to specific Spaces. |
metadata_scope | DevMetadataScope | The metadata scope the key is limited to. Absent means not limited by metadata. |
expires_at | string (date-time) | After this time the key stops working. Absent when it does not expire. |
revoked_at | string (date-time) | When the key was revoked. Absent while it is live. |
last_used_at | string (date-time) | When the key last called the API, to within a minute. Absent until its first call. |
created_byRequired | DevId | The principal that issued it. |
issued_by_key_id | DevId | The key that issued or rotated this one. Absent when no key was used. |
created_atRequired | string (date-time) | When it was issued. |
DevApproveProposalRequest
| Field | Type | Description |
|---|---|---|
message | string | Becomes 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.
| Field | Type | Description |
|---|---|---|
size_bytesRequired | integer | Size of the archive in bytes. |
sha256Required | string | Hex SHA-256 of the archive. |
media_typeRequired | string | application/x-tar. |
expires_atRequired | string (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.
| Field | Type | Description |
|---|---|---|
urlRequired | string (uri) | The signed URL. Fetch it with a plain GET. |
methodRequired | GET | Always GET. |
expires_atRequired | string (date-time) | UTC. At most 5 minutes after the request. |
job_idRequired | DevId | length 1..256 |
size_bytesRequired | integer | Size of the archive in bytes. |
media_typeRequired | string | application/x-tar. The response carries it with Content-Disposition: attachment and Cache-Control: private, no-store. |
sha256Required | string | Hex SHA-256 of the archive. |
DevAuditEvent
Identifiers only. Audit events never contain user content.
| Field | Type | Description |
|---|---|---|
idRequired | DevId | length 1..256 |
actionRequired | string | Stable action name, such as entry.read, acl.set, or api_key.revoke. |
outcomeRequired | DevAuditOutcome | How the action ended: allowed, denied, or failed. |
principal_idRequired | DevId | The principal that acted. |
key_id | DevId | Absent when the request was not authenticated with an API key. |
space_id | DevId | Absent when the action has no single Space. |
resource_kindRequired | string | What 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_id | DevId | For entry and version this is the Entry id; version_id names the version. |
version_id | DevId | length 1..256 |
request_id | string | The request that caused the event, the same id error bodies carry as request_id. |
created_atRequired | string (date-time) | When the event was recorded. |
DevAuditOutcome
Values: allowed | denied | failed
DevBacklog
The account's processing queue when it is full.
| Field | Type | Description |
|---|---|---|
queuedRequired | integer | Jobs of the kind that reached its limit queued for the account. For a key limited to some Spaces or to metadata, the limit. |
limitRequired | integer | tenant_queued_jobs when jobs that make content searchable (parsing, recognition, indexing, publishing) are full; five times it when summaries, classification, relations and memories are. |
pausedRequired | boolean | True 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_seconds | integer | Estimated 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.
| Field | Type | Description |
|---|---|---|
idRequired | DevId | length 1..256 |
space_idRequired | DevId | length 1..256 |
nameRequired | string | The branch's name. While the branch is active, paths and ?branch= take it in place of the id. |
stateRequired | DevBranchState | abandoned also covers a branch past expires_at that the sweep has not reached yet. |
parent_branch_id | DevId | Absent when the branch started from main. Nodes were copied: there is no parent chain. |
base_change_seqRequired | integer | Main's change sequence when the branch opened. |
main_changed_pathsRequired | integer | How 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_byRequired | DevId | length 1..256 |
ttl_daysRequired | integer | How many days each write pushes expires_at out by. |
expires_atRequired | string (date-time) | When the branch expires. Past this time the branch is abandoned, then reclaimed. |
created_atRequired | string (date-time) | When the branch was opened. |
updated_atRequired | string (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.
| Field | Type | Description |
|---|---|---|
sourceRequired | branch | main | branch: a change made on this branch. main: a change on main that this branch reads through. |
seqRequired | integer | Sequence number within its source. |
opRequired | DevChangeOp | The kind of change: create, update, move, delete or restore. |
path | DevPath | length 1..4096 |
kind | DevBranchNodeKind | On a branch change: whether the path is a directory, a file, or a symlink. |
entry_id | DevId | length 1..256 |
version_id | DevId | length 1..256 |
actor_principal_id | DevId | length 1..256 |
created_atRequired | string (date-time) | When the change was made. |
DevBranchChangeFeed
| Field | Type | Description |
|---|---|---|
dataRequired | DevBranchChange[] | The events of this page. |
cursorRequired | DevCursor | Pass back to continue. |
has_moreRequired | boolean | True 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.
| Field | Type | Description |
|---|---|---|
pathRequired | DevPath | length 1..4096 |
changeRequired | DevBranchDiffOp | Whether the branch added, modified, or deleted the path. |
kindRequired | DevBranchNodeKind | What the path is on the branch: a directory, a file, or a symlink. |
size | integer | For a file: the size of the branch's content in bytes. |
mode | 644 | 755 | For a file: 644 or 755. |
sha256 | string | For a file: hex SHA-256 of the branch's content. |
base_version_id | DevId | length 1..256 |
unified_diff | string | Text files only. Empty when the bytes differ only in a way line comparison cannot see. |
diff_omitted | too_large | Set when a text file's diff was too large to compute. |
DevBranchDiffOp
Values: added | modified | deleted
DevBranchFileDeletion
DevBranchFileMeta
view=meta on a path the branch changed. Paths read through to main return the Entry.
| Field | Type | Description |
|---|---|---|
branch_idRequired | DevId | length 1..256 |
pathRequired | DevPath | length 1..4096 |
kindRequired | file | symlink | Whether the path is a file or a symlink on the branch. |
size | integer | Files only: size in bytes. |
media_type | string | Files only: the media type the file was written with. |
mode | 644 | 755 | Files only: 644 or 755. |
sha256 | string | Files only: hex SHA-256 of the content. |
etag | string | Files only: send it in If-Match on the next write. It is a content hash, not a version. |
link_target | string | Symlinks only: where the link points. |
updated_atRequired | string (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.
DevBranchFileWrite
Result of writing a file to a branch. Its etag is a content hash, not a version.
| Field | Type | Description |
|---|---|---|
branch_idRequired | DevId | length 1..256 |
pathRequired | DevPath | length 1..4096 |
sha256Required | string | Hex SHA-256 of the bytes written. |
sizeRequired | integer | Size in bytes. |
media_typeRequired | string | The media type stored with the file. |
modeRequired | 644 | 755 | 644 or 755. |
etagRequired | string | The file's ETag on the branch, with quotes. Send it in If-Match on the next write. |
version_idRequired | string | The etag without quotes. changes?branch= reports this write under the same version_id. |
createdRequired | boolean | True when nothing was at the path before this write, false when it replaced a file. |
changedRequired | boolean | False when the bytes, media type, and mode are unchanged. |
DevBranchNodeKind
Values: dir | file | symlink
DevBranchObject
An object stored in a branch.
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.
| Field | Type | Description |
|---|---|---|
seqRequired | integer | The event's position in the Space's change feed. Numbers follow commit order with no gaps. |
opRequired | DevChangeOp | The kind of change: create, update, move, delete or restore. |
entry_idRequired | DevId | length 1..256 |
path | DevPath | length 1..4096 |
version_id | DevId | length 1..256 |
actor_principal_id | DevId | length 1..256 |
created_atRequired | string (date-time) | When the change was committed. |
DevChangeFeed
One page of the change feed. It uses cursor rather than next_cursor.
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.
| Field | Type | Description |
|---|---|---|
idRequired | DevId | length 1..256 |
branch_idRequired | DevId | length 1..256 |
nameRequired | string | The name it was given when it was created. |
git | DevCheckpointGit | |
node_countRequired | integer | Changed paths this checkpoint holds. |
created_byRequired | DevId | length 1..256 |
created_atRequired | string (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
| Field | Type | Description |
|---|---|---|
partsRequired | DevCompletedPart[] | Every part of the file, each with the ETag its PUT returned.min items 1 |
session_id | string | Your 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_at | string (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. |
metadata | DevMetadata | Replaces the Entry's metadata as a whole, as metadata does on PATCH /v2/entries/{id}. Retrieval's filter.metadata matches it. |
memory_exclude | boolean | true 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
| Field | Type | Description |
|---|---|---|
part_numberRequired | integer | The part's number, from 1.>= 1 |
etagRequired | string | The 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.
| Field | Type | Description |
|---|---|---|
urlRequired | string (uri) | The signed URL. Fetch it with a plain GET. |
methodRequired | GET | Always GET. |
expires_atRequired | string (date-time) | UTC. At most 5 minutes after the request. |
entry_idRequired | DevId | length 1..256 |
version_idRequired | DevId | length 1..256 |
size_bytesRequired | integer | Size of the original in bytes. |
media_typeRequired | string | The response carries this Content-Type, Content-Disposition: attachment, and Cache-Control: private, no-store. |
sha256 | string | Hex SHA-256 of the original bytes, when known. |
DevContentView
Values: text | table | recognized
DevContextChange
DevContextFeedbackRequest
| Field | Type | Description |
|---|---|---|
used_citation_idsRequired | string[] | 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
| Field | Type | Description |
|---|---|---|
typeRequired | stale | superseded | conflict | agent_written | stale, superseded, conflict, or agent_written. |
citation_id | string | On conflict: the item that disagrees with this one. |
grant_id | string | On agent_written. |
DevContextItem
| Field | Type | Description |
|---|---|---|
entry_idRequired | DevId | length 1..256 |
version_idRequired | DevId | length 1..256 |
space_id | DevId | length 1..256 |
titleRequired | string | Title of the Entry the passage is from. |
textRequired | string | A passage. For skills, the one-line description: read the body at path. |
citation_idRequired | string | Identifies this item within the pack, such as c1. Report the items you used by it in feedback. |
sourceRequired | DevContextSource | |
path | DevPath | length 1..4096 |
url | string | On an Entry ingested from a URL: that URL, to link back to the page. A file has path instead. |
occurred_at | string (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_at | string (date-time) | When the version the passage was read from was written. With occurred_at it tells old from new. |
stated_date | string (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_from | text | heading | document | Where stated_date was read: the passage text, a section heading above it, or the document head. |
is_current_version | false | Present and false when a newer version than this one is live. |
flags | DevContextFlag[] | Absent when there are none. |
freshness | pending_index | pending_index means the item came from the freshness buffer, lexically only. |
memory_kind | string | On memory items. |
change | DevContextChange | On changes items. |
memory | DevRoutedMemory | Only 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. |
explain | DevHitExplain | Only when the request set explain. Not counted in tokens_used. |
DevContextOmitted
DevContextPurpose
Values: task | coding | research | audit
DevContextRendered
The pack as text, when the request set render.
| Field | Type | Description |
|---|---|---|
textRequired | string | A 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. |
tokensRequired | integer | text 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
| Field | Type | Description |
|---|---|---|
taskRequired | string | What the context is for, in natural language. A task that states several things is searched for each of them.length 1..1000 |
space_ids | DevSpaceRef[] | 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 |
purpose | DevContextPurpose | What the context is for (task, coding, research, or audit). Set this to skip intent inference. |
weights | DevContextWeights | Shift the budget between sources. Omit to use the shares that go with the purpose. |
tier | DevContextTier | fast uses no model and matches words only; standard adds semantic search and reranking; deep looks at twice as many candidates.default: "standard" |
budget_tokens | integer | Covers 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_etag | string | Omits memory_view when it still matches memory_view_etag.length 1..128 |
filter | DevRetrievalFilter | Narrow what is searched before ranking. Applies to every source that reads Entries; memory_view is not filtered. |
render | text | compact | text 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. |
profile | string | A 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. |
rerank | boolean | false 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_score | number | The 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_entry | integer | At 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_time | string (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. |
timezone | string | IANA 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. |
explain | boolean | True 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
| Field | Type | Description |
|---|---|---|
pack_idRequired | DevId | Names this pack. Report what you used with POST /v2/retrieval/context/{pack_id}/feedback. |
memory_view_etag | string | Send it back as have_memory_etag. Absent when the memory source was off or the view did not fit. |
memory_view | DevMemoryView | Absent when have_memory_etag matched. |
itemsRequired | DevContextItem[] | The passages picked for the task, each citable by its citation_id. |
routeRequired | DevContextRoute | Which sources were used, with what budget, and why. |
tokens_usedRequired | integer | Measured over this whole response; with render: "compact", over rendered.text. Never more than budget_tokens. |
budget_tokensRequired | integer | The budget the pack was built for. |
tokenizerRequired | cl100k_base | The tokenizer tokens_used and budget_tokens are counted with. |
omittedRequired | DevContextOmitted | What qualified but did not fit or fell below the relevance floor. |
scope_usedRequired | DevContextScopeUsed | The Spaces the pack was drawn from. |
partialRequired | boolean | True when a retrieval branch degraded or the scores are not calibrated relevance. |
pending_processing | DevPendingProcessing | Only 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. |
rendered | DevContextRendered | Only when the request set render. |
explain | DevExplainSummary | Only when the request set explain. |
DevContextRoute
Explains the deterministic routing decision, generated after authorization.
| Field | Type | Description |
|---|---|---|
purposeRequired | DevContextPurpose | The purpose used, inferred from the task unless you set it. |
tierRequired | DevContextTier | |
rules_firedRequired | string[] | 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. |
sourcesRequired | DevContextRouteSource[] | Sources that were on. A source that was off is named in rules_fired. |
unused_tokensRequired | integer | Budget left empty: nothing above the relevance floor wanted it. |
DevContextRouteSource
| Field | Type | Description |
|---|---|---|
sourceRequired | DevContextSource | |
budgetRequired | integer | Tokens this source could use, after unused budget flowed in from other sources. |
usedRequired | integer | Tokens this source actually used. |
pickedRequired | integer | Items from this source that made it into the pack. |
omittedRequired | integer | Candidates from this source that were left out. |
whyRequired | string | Stable code, such as filled, below_relevance_floor, or no_file_named_in_task. |
DevContextScopeUsed
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.
| Field | Type | Description |
|---|---|---|
memory | number | Weight of memory: memories relevant to the task.0..1 |
agent_profile | number | Weight of agent_profile: the Agent's own profile.0..1 |
skills | number | Weight of skills: the Agent's own skills.0..1 |
files | number | Weight of files: the files the task names.0..1 |
changes | number | Weight of changes: what was written recently.0..1 |
knowledge | number | Weight 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.
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.
| Field | Type | Description |
|---|---|---|
roleRequired | string | Free text such as user or assistant, without line breaks.length 1..128 |
content | string | DevConversationContentPart[] | null | The text, or a list of segments of which the text ones are joined. null or absent on a message without text. |
name | object | Accepted and ignored. |
tool_calls | object | Accepted and ignored. |
tool_call_id | object | Accepted and ignored. |
function_call | object | Accepted and ignored. |
timestamp | string (date-time) | integer | When 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.
| Field | Type | Description |
|---|---|---|
textRequired | string | The 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.
| Field | Type | Description |
|---|---|---|
actor_idRequired | DevId | The 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. |
nameRequired | string | A name for the key, 1 to 256 characters, to tell keys apart in listings.length 1..256 |
grant_capabilitiesRequired | DevCapability[] | Must not exceed the capabilities of the principal or of the caller.min items 1 |
allowed_space_ids | DevId[] | Omit to leave Spaces unrestricted; an empty list is rejected.items 1..100 |
metadata_scope | DevMetadataScope | Limit 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_at | string (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.
DevCreateCheckpointRequest
| Field | Type | Description |
|---|---|---|
nameRequired | string | A name for the checkpoint, 1 to 255 characters.length 1..255 |
git | DevCheckpointGit |
DevCreateExportRequest
| Field | Type | Description |
|---|---|---|
snapshot | DevSnapshotRef | A snapshot id or name: export the files as they were then. Without it, the live tree at the moment the job starts. |
path | DevPath | Only this directory (or file) and what is under it. |
format | tar | The only format. |
DevCreateForkRequest
A fork of a Space into a new Space you own. Planned.
| Field | Type | Description |
|---|---|---|
nameRequired | string | The new Space's name. |
snapshot | DevSnapshotRef | Fork the files as a snapshot pinned them. Without it, the live tree. |
DevCreateImportRequest
| Field | Type | Description |
|---|---|---|
source_entry_idRequired | DevId | An 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. |
path | DevPath | The directory to import into, created as needed. Default /. |
on_conflict | DevImportConflict | What to do when a file is already at a member's path: skip (the default) or overwrite.default: "skip" |
DevCreateMemoryRequest
| Field | Type | Description |
|---|---|---|
scopeRequired | DevMemoryScope | Whose memory to write: project, agent, or account. |
space_id | DevSpaceRef | Required for project and agent; default names your default Space, as it does in a path. Account memory takes none. |
kindRequired | string | preference, 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 |
textRequired | string | The memory itself, 1 to 2000 characters.length 1..2000 |
pinned | boolean | Not on account memory.default: false |
DevCreatePrincipalRequest
| Field | Type | Description |
|---|---|---|
kindRequired | DevPrincipalKind | What the principal is: a person or an Agent. |
grant_capabilities | DevCapability[] | Capabilities to grant; they must not exceed yours. Omitted means knowledge:read for an Agent and none for a human. |
DevCreateSnapshotRequest
| Field | Type | Description |
|---|---|---|
nameRequired | string | 1 to 255 bytes, unique in the Space, no control characters, not starting with snp_.length 1..255 |
DevCreateSpaceRequest
| Field | Type | Description |
|---|---|---|
nameRequired | string | The Space's name, 1 to 512 characters.length 1..512 |
description | string | What the Space is for, 1 to 4096 characters.length 1..4096 |
external_id | string | Your 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.
| Field | Type | Description |
|---|---|---|
pathRequired | DevPath | Resolved when the upload completes, so the file may appear or change in between. |
sizeRequired | integer | Size of the whole file in bytes.>= 1 |
media_typeRequired | string | The file's media type, such as application/pdf. |
checksum_sha256Required | string | Base64 SHA-256 of the whole file, checked on completion. |
DevCreateWebhookRequest
| Field | Type | Description |
|---|---|---|
urlRequired | string | https, 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 |
ops | DevChangeOp[] | The event kinds to deliver; defaults to all five. No repeats.items 1..5 |
description | string | A note for people, at most 256 characters.max length 256 |
cursor | DevCursor | Start 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.
| Field | Type | Description |
|---|---|---|
idRequired | DevId | length 1..256 |
space_idRequired | DevId | length 1..256 |
urlRequired | string (uri) | https on port 443. |
opsRequired | DevChangeOp[] | Event kinds to send. Events of other kinds are skipped, not queued. |
description | string | A note for people. |
statusRequired | DevWebhookStatus | active, or disabled when deliveries have stopped; disabled_reason says why. |
disabled_reason | DevWebhookDisabledReason | Present when status is disabled. |
cursorRequired | DevCursor | The change-feed position after the last batch delivered or skipped. |
consecutive_failuresRequired | integer | Failed attempts since the last success. |
last_success_at | string (date-time) | When a batch was last delivered. |
last_failure_at | string (date-time) | When an attempt last failed. |
next_attempt_at | string (date-time) | When the next attempt may start. Absent when disabled. |
created_by_principal_idRequired | DevId | length 1..256 |
created_atRequired | string (date-time) | When the webhook was created. |
updated_atRequired | string (date-time) | When the webhook's settings or state last changed. |
secret | string | whsec_ 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.
| Field | Type | Description |
|---|---|---|
idRequired | DevId | length 1..256 |
space_idRequired | DevId | length 1..256 |
scopeRequired | DevDreamScope | |
agent_principal_id | DevId | For an agent dream: whose private memory. |
statusRequired | DevDreamStatus | queued, running, then succeeded or failed. |
triggerRequired | DevDreamTrigger | manual: someone started it. schedule: the Space's dreaming schedule did. |
started_by_principal_id | DevId | For a manual dream. |
created_atRequired | string (date-time) | When the dream was queued. |
started_at | string (date-time) | When it began to run. Absent while it is queued. |
finished_at | string (date-time) | When it ended, whether it succeeded or failed. |
undone_at | string (date-time) | When it was undone. Absent if it never was. |
undone_by_principal_id | DevId | length 1..256 |
undo_expires_at | string (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. |
undoableRequired | boolean | Whether an undo would be accepted right now. |
countsRequired | DevDreamCounts | |
view | DevDreamView | |
d4 | DevDreamD4Report | Present once the dream reached its comparison step. |
model_tokensRequired | integer | Estimated model tokens spent on this dream; 0 for a member with a read_root in the Space. |
error | DevJobFailure |
DevDreamAction
One change a dream made to one memory, or (reported) one it would make under dormancy: "apply".
| Field | Type | Description |
|---|---|---|
seqRequired | integer | Order within the dream; actions are listed by it. |
memory_idRequired | DevId | length 1..256 |
entry_idRequired | DevId | length 1..256 |
actionRequired | DevDreamActionKind | |
reasonRequired | DevDreamActionReason | |
stateRequired | DevDreamActionState | |
proposal_id | DevId | For supersede and merge: the approved proposal. |
target_memory_id | DevId | For supersede and merge: the memory that stayed. Absent when you cannot see its source. |
created_atRequired | string (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.
| Field | Type | Description |
|---|---|---|
dormant_markedRequired | integer | Memories set aside as dormant because their quotes are gone (quote_missing). |
dormancy_candidates | integer | Present 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_unused | integer | Present with dormancy_candidates: those marked dormant with reason unused (Space setting dormancy: "apply"). |
superseded | integer | Memories replaced by a newer one when a supersede proposal of this dream was approved. Present once there are any. |
merged | integer | Memories folded into another when a merge proposal of this dream was approved. Present once there are any. |
undone | integer | After an undo: actions taken back. |
conflict_skipped | integer | After an undo: actions left alone because the memory changed since (forgotten, confirmed, re-distilled, or taken over by a later dream). |
checked | integer | Distilled memories checked. |
skipped_confirmed | integer | Memories a person confirmed, never changed by a dream: approved candidates, and memories distilled from a conversation ingested with memory:confirm. |
skipped_not_ready | integer | Memories whose source has a newer version still processing. |
skipped_no_quote | integer | Memories without a quote to check. |
stale_skipped | integer | Memories that changed between the check and the write and were left for the next dream. |
vetoed | integer | Memories an earlier undo said not to touch again. |
already_dormant | integer | Memories already dormant from an earlier dream. |
groups | integer | Groups of two or more memories that say the same thing. |
grouped_facts | integer | Distilled memories that share their statement with at least one other. |
remaining | integer | Memories 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.
| Field | Type | Description |
|---|---|---|
statusRequired | ran | skipped | skipped: it asked the model nothing this run; skipped then says why. |
skipped | DevDreamD4SkipReason | Set whenever D4 was skipped or stopped before running out of pairs. remaining counts what it left. |
nominatedRequired | integer | Pairs of memories it found worth comparing. |
judgedRequired | integer | Pairs it asked the model about. |
cachedRequired | integer | Pairs answered from a judgment already made within 30 days. |
proposedRequired | integer | Judgments written as open proposals. |
shadowRequired | integer | Judgments recorded only (the shadow setting). |
discardedRequired | integer | Judgments that failed validation or that the model could not answer; they keep no text. |
stale_skippedRequired | integer | Pairs whose memories changed before the judgment could be written. |
failedRequired | integer | Pairs where the model call failed. |
remainingRequired | integer | Pairs 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.
| Field | Type | Description |
|---|---|---|
idRequired | DevId | length 1..256 |
dream_idRequired | DevId | length 1..256 |
outcomeRequired | DevDreamJudgmentOutcome | |
kind | DevMemoryProposalKind | What it concluded. Absent for a discarded judgment. |
member_idsRequired | DevId[] | The memories that were compared. |
layerRequired | DevMemoryLayer | The memory layer of the pair: rule, decision, event, or knowledge. |
signalsRequired | string[] | Why this pair was compared: entity, predicate, kind. |
discard_reason | DevDreamJudgmentDiscardReason | On a discarded judgment: why it was thrown out. |
plan | DevMemoryProposalPlan | |
evidence | DevMemoryProposalEvidence[] | The verbatim quotes the judgment rests on. Absent on a discarded judgment, which keeps no quote. |
times | DevMemoryProposalTime[] | Dates that decided which memory is newer. |
model | string | The model that was asked. |
prompt_versionRequired | integer | Version of the prompt the judgment was made with. A new version stops older judgments from being reused. |
cachedRequired | boolean | True when this judgment reused an earlier one instead of asking the model. |
created_atRequired | string (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.
| Field | Type | Description |
|---|---|---|
live_beforeRequired | integer | Active memories in the scope before the dream. |
tokens_beforeRequired | integer | Their size in tokens before the dream. |
live_after | integer | Active memories in the scope after the dream. Present once it has finished. |
tokens_after | integer | Their 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.
| Field | Type | Description |
|---|---|---|
name | string | Name for a new Space. Defaults to the external_id.length 1..512 |
description | string | Description 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.
| Field | Type | Description |
|---|---|---|
idRequired | DevId | Starts with ent_. Stable across versions, renames, and moves. |
space_idRequired | DevId | The Space the Entry is in. |
titleRequired | string | For a file, its name. Otherwise the title you gave, or one derived from the content. |
latest_version_idRequired | DevId | The newest version written. Reads by path or id return it by default. |
current_version_id | DevId | The 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. |
metadataRequired | DevMetadata | What you set on ingest, with a file write, or with PATCH, plus any mirabase. keys the service added. Empty when none. |
occurred_at | string (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_type | DevSourceType | What 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. |
url | string | On an Entry ingested from a URL: that URL. Use it to link a search hit or a citation back to the page. |
created_atRequired | string (date-time) | When the Entry was first written. |
updated_atRequired | string (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. |
fileRequired | DevEntryFile | null | Null for an Entry without a path, such as a URL or a conversation. |
knowledgeRequired | DevEntryKnowledge | How far processing has progressed, and which version search is serving. |
memoryRequired | DevEntryMemory | null | Null unless the Entry was written as a memory. |
memory_excludeRequired | boolean | True when this Entry is kept out of memory distillation. Any Entry can have it, so it is not under memory. |
accessRequired | DevEntryAccess | Your role in the Entry's Space and the capabilities of the key you are using. |
trash | DevEntryTrash | Only in the trash listing (GET /v2/entries?trashed=true). |
DevEntryAccess
| Field | Type | Description |
|---|---|---|
roleRequired | DevSpaceRole | Your role in the Entry's Space. |
capabilitiesRequired | DevCapability[] | The capabilities this request acts with. |
DevEntryContent
| Field | Type | Description |
|---|---|---|
entry_idRequired | DevId | length 1..256 |
version_idRequired | DevId | length 1..256 |
viewRequired | DevContentView | The view this is: text, table, or recognized. |
text | string | The content as text. Absent on the table view. |
table | DevTableContent | The content as a table. Only on the table view. |
DevEntryCopy
A file copied from this Entry with tree/operations copy.
| Field | Type | Description |
|---|---|---|
entry_idRequired | DevId | length 1..256 |
source_version_idRequired | DevId | The source version the copy started from. |
space_idRequired | DevId | length 1..256 |
created_atRequired | string (date-time) | When the copy was made. |
DevEntryFile
| Field | Type | Description |
|---|---|---|
pathRequired | DevPath | length 1..4096 |
sizeRequired | integer | Size of the latest version in bytes. |
media_typeRequired | string | Media type of the latest version. |
etagRequired | string | The latest version's ETag. Send it in If-Match to change the file only if nobody else has. |
modified_at | string (date-time) | When the content last changed: when the latest version was written. The same value a tree listing reports. |
DevEntryKnowledge
| Field | Type | Description |
|---|---|---|
stateRequired | DevKnowledgeState | |
indexed_version_id | DevId | length 1..256 |
parsed | DevParsedSummary | What 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. |
error | DevProcessingFailure | Why 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
| Field | Type | Description |
|---|---|---|
scopeRequired | DevMemoryScope | Whose memory it is: project, agent, or account. |
kindRequired | string | The kind of memory, such as preference or decision. |
pinnedRequired | boolean | Pinned memories come first in the memory context. |
excludeRequired | boolean | The 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.
| Field | Type | Description |
|---|---|---|
entry_idRequired | DevId | length 1..256 |
version_idRequired | DevId | The latest version, which is the one being reported. |
statusRequired | DevVersionStatus | Terminal when published, no_recallable_content, failed, or discarded. |
knowledge_stateRequired | DevKnowledgeState | The same value as knowledge.state on the Entry. |
error | DevProcessingFailure | Only when status is failed. |
stageRequired | DevProcessingStage | Where the latest version is now. Search finds it from enriching on. |
progressRequired | DevProcessingProgress | The main steps done so far. |
queue | DevProcessingQueue | Only while the current step waits to start. |
enrichments | DevEnrichment[] | Only while stage is enriching: what still runs. |
memory | DevMemoryProcessing | Only 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.
| Field | Type | Description |
|---|---|---|
deleted_atRequired | string (date-time) | When it went to the trash. For an Entry without a path, when its cleanup finished, moments later. |
path | DevPath | The path a file had. POST /v2/entries/{id}/restore puts it back there. Absent for an Entry without a path. |
delete_batch_id | DevId | The delete that trashed a file. restore in tree/operations takes it and brings back everything that delete removed. |
deleted_by | DevId | Who moved a file to the trash: a principal id. Absent for an Entry without a path. |
size | integer | Size 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.
| Field | Type | Description |
|---|---|---|
codeRequired | string | Machine-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). |
type | DevErrorType | The 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. |
statusRequired | integer | The HTTP status, repeated in the body. |
messageRequired | string | English text for people. It may change: branch on code. |
request_idRequired | string | Identifies this request in the service's logs. Quote it when you report a problem. |
retryableRequired | boolean | False on quota_exceeded: retrying does not help until the quota changes. |
field | string | First offending field on a 422. An unknown field in a request body is reported here by its name. |
errors | DevFieldError[] | 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. |
limit | request_rate | concurrency | Present 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. |
quota | writes | storage_bytes | model_tokens | model_spend_micro_usd | Present 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. |
queue | DevBacklog | Present on 429 ingest_backlog: the account's queue. GET /v2/queue shows it at any time. |
current_version_id | DevId | Present on 412 precondition_failed and 409 proposal_conflict: the file's latest version now. |
job_id | DevId | Present on 409 job_in_flight: the work to wait for. |
conflicts | DevMergeConflict[] | Present on 409 merge_conflict: every path that blocked the merge. |
remediation | DevRemediation |
Every error code's status, meaning, remediation.action, and Retry-After are in Error codes.
DevErrorResponse
| Field | Type | Description |
|---|---|---|
errorRequired | DevErrorBody | The 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
| Field | Type | Description |
|---|---|---|
branchRequired | DevExplainBranch | |
rankRequired | integer | 1-based position in that branch's own results, counting only results you can read. |
DevExplainCandidateCount
| Field | Type | Description |
|---|---|---|
branchRequired | DevExplainBranch | |
countRequired | integer | How many candidates that branch returned that you can read. |
DevExplainRank
DevExplainRerank
DevExplainRerankSummary
| Field | Type | Description |
|---|---|---|
appliedRequired | boolean | False when the reranker was skipped, failed or gave no scores; score is then not calibrated relevance. |
poolRequired | integer | How many candidates were sent to the reranker. |
below_floorRequired | integer | How many reranked candidates fell below the relevance floor. |
DevExplainSummary
How the retrieval ran, when the request set explain.
| Field | Type | Description |
|---|---|---|
termsRequired | string[] | The terms the lexical branch searched for. |
candidatesRequired | DevExplainCandidateCount[] | Candidates per branch, counting only those you can read. Branches that returned nothing you can read are left out. |
fused_countRequired | integer | Candidates you can read after the branches were merged. |
rerankRequired | DevExplainRerankSummary | |
clauses | string[] | For a task that states several things: the clauses that were searched for separately. |
DevFieldError
One problem in a request body.
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.
| Field | Type | Description |
|---|---|---|
occurred_at | string (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. |
metadata | DevMetadata | Replaces the Entry's metadata as a whole, as metadata does on PATCH /v2/entries/{id}. Retrieval's filter.metadata matches it. |
memory_exclude | boolean | true 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
DevFileBatchItem
Values: DevFileBatchPut | DevFileBatchDelete
DevFileBatchPut
| Field | Type | Description |
|---|---|---|
opRequired | put | Always put. |
pathRequired | DevPath | length 1..4096 |
contentRequired | string | UTF-8 text, at most 64 KiB. |
media_type | string | Defaults to text/plain. |
if_match | string | The 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_at | string (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. |
metadata | DevMetadata | Replaces the Entry's metadata as a whole, as metadata does on PATCH /v2/entries/{id}. Retrieval's filter.metadata matches it. |
memory_exclude | boolean | true 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.
| Field | Type | Description |
|---|---|---|
itemsRequired | DevFileBatchItem[] | 1 to 50 writes and deletes, applied in order.items 1..50 |
session_id | string | Your 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
| Field | Type | Description |
|---|---|---|
dataRequired | DevFileBatchResult[] | One result per item, in the order the items were sent. |
queue | DevQueueEstimate | How many items went on the processing queue, and roughly how long the account's queue needs. |
DevFileBatchResult
| Field | Type | Description |
|---|---|---|
pathRequired | DevPath | length 1..4096 |
statusRequired | integer | The HTTP status this item would have had as a request of its own, such as 200, 201, 404, or 412. |
write | DevFileWrite | |
proposal | DevProposalReceipt | Instead of write, with status 202, when Prefer: handling=proposal turned this item into a proposal. |
deletion | DevFileDeletion | On a delete that succeeded. |
branch_write | DevBranchFileWrite | Instead of write when the request named a branch. |
branch_deletion | DevBranchFileDeletion | Instead of deletion when the request named a branch. |
error | DevErrorBody | On an item that failed: the error body a single request would have returned. |
DevFileDeletion
DevFileEdit
| Field | Type | Description |
|---|---|---|
old_textRequired | string | Must appear exactly once, unless replace_all is set.min length 1 |
new_textRequired | string | What replaces old_text. An empty string deletes it. |
replace_all | boolean | Replace 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.
| Field | Type | Description |
|---|---|---|
editsRequired | DevFileEdit[] | 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.
| Field | Type | Description |
|---|---|---|
entryRequired | DevEntry | The Entry as it is after the write. |
version_idRequired | DevId | The version that now holds the content. It is the ETag, without the quotes. |
previous_version_id | DevId | The version this write replaced. Absent on a new file and when no version was created. |
version_createdRequired | boolean | False 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.
| Field | Type | Description |
|---|---|---|
and | DevFilterCondition[] | All of these hold. 1 to 16.items 1..16 |
or | DevFilterCondition[] | At least one of these holds. 1 to 16.items 1..16 |
not | DevFilterCondition | This does not hold. An Entry without the key satisfies {"not": {"key": k, "eq": v}}. |
key | string | The metadata key of a key condition: 1 to 64 of a-z, 0-9, _, ., -. |
eq | DevMetadataValue | The Entry holds this value under the key.min length 1 |
in | DevMetadataValue[] | The Entry holds one of these values under the key, 1 to 32 of them.items 1..32 |
exists | boolean | true: the Entry has the key; false: it does not. |
gt | DevFilterRangeBound | Greater than. Not together with gte. |
gte | DevFilterRangeBound | Greater than or equal. Not together with gt. |
lt | DevFilterRangeBound | Less than. Not together with lte. |
lte | DevFilterRangeBound | Less 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.
| Field | Type | Description |
|---|---|---|
entry_idRequired | DevId | length 1..256 |
version_idRequired | DevId | length 1..256 |
DevHitExplain
Why this hit came back. Only when the request set explain.
| Field | Type | Description |
|---|---|---|
found_byRequired | DevExplainBranchRank[] | The branches that returned it, with its position in each. Empty for a computed table. |
fused | DevExplainRank | Its position and score after the branches were merged, before reranking, both computed over the candidates you can read. |
rerank | DevExplainRerank | Its position and score from the reranker. Absent when reranking did not run or gave no score. |
matched_terms | string[] | The query terms its text matched. Chinese is matched in two-character terms. |
lexical | strong | covered | partial | How well its words covered the query: strong skips the relevance floor, covered and partial do not. |
admitted_by | DevExplainAdmission | What let it past the relevance floor. Absent when no floor applied. |
boosts | DevExplainBoost[] | Rules that moved it up. |
reordered_by_date | string | With newest_first: the date it was ordered by (occurred_at, else stated_date), YYYY-MM-DD. |
computed_table | true | True 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.
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.
| Field | Type | Description |
|---|---|---|
kindRequired | conversation | Always conversation. |
session_idRequired | string | Your 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 |
messagesRequired | DevConversationMessage[] | The messages of this batch, in the order they were said: 1 to 1000.items 1..1000 |
title | string | Defaults to Conversation <session_id>.length 1..512 |
metadata | DevMetadata | On the Entry, like any other source. A conversation's time comes from its messages' timestamp. |
memory_exclude | boolean | True 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_secrets | boolean | True 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_instructions | string | Your 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.
| Field | Type | Description |
|---|---|---|
entry_idRequired | DevId | The Entry that was created. |
version_idRequired | DevId | Its first version. |
job_idRequired | DevId | The 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. |
knowledgeRequired | DevEntryKnowledge | Usually searchable for text of up to 64 KiB, otherwise readable until processing finishes. |
memory_status | candidate | confirmed | Only on a conversation: whether what is distilled from it takes effect or waits for review. |
memory | DevMemoryProcessing | Only 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_redacted | integer | Only when the request set redact_secrets: how many places were replaced. 0 means nothing looked like a credential. |
DevIngestRequest
Values: DevIngestUrl | DevIngestText | DevIngestConversation
DevIngestText
| Field | Type | Description |
|---|---|---|
kindRequired | text | Always text. |
textRequired | string | The text to store, 1 to 2,000,000 characters.length 1..2000000 |
title | string | Defaults to the first line.length 1..512 |
occurred_at | string (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. |
metadata | DevMetadata | |
memory_exclude | boolean | True 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_secrets | boolean | True 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.
| Field | Type | Description |
|---|---|---|
kindRequired | url | Always url. |
urlRequired | string (uri) | The page to fetch, http or https, at most 8192 characters.max length 8192 |
title | string | A title for the Entry, 1 to 512 characters.length 1..512 |
occurred_at | string (date-time) | When the page's content happened, if you know it. Retrieval's occurred_from / occurred_to go by it. |
metadata | DevMetadata | |
memory_exclude | boolean | True 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.
| Field | Type | Description |
|---|---|---|
idRequired | DevId | Starts with key_. Not the secret: the token is shown once, when the key is created or rotated. |
principal_idRequired | DevId | The principal the key acts as. |
nameRequired | string | Your label for the key. |
prefixRequired | string | Non-secret token prefix, for recognizing a key in a list. |
capabilitiesRequired | DevCapability[] | What the key may do. Never more than its principal's capabilities. |
allowed_space_ids | DevId[] | Absent means not narrowed to specific Spaces. |
metadata_scope | DevMetadataScope | The metadata scope the key is limited to. Absent means not limited by metadata. |
expires_at | string (date-time) | After this time the key stops working. Absent when it does not expire. |
revoked_at | string (date-time) | When the key was revoked. Absent while it is live. |
last_used_at | string (date-time) | When the key last called the API, to within a minute. Absent until its first call. |
created_byRequired | DevId | The principal that issued it. |
issued_by_key_id | DevId | The key that issued or rotated this one. Absent when no key was used. |
created_atRequired | string (date-time) | When it was issued. |
token | string | The 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.
| Field | Type | Description |
|---|---|---|
idRequired | DevId | length 1..256 |
kindRequired | DevJobKind | Which 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. |
statusRequired | DevJobStatus | queued, running, then succeeded, failed, or cancelled. |
stageRequired | string | What the job is doing, as described above. |
entry_id | DevId | Processing jobs: the Entry being processed. |
version_id | DevId | Processing jobs: the version being processed. |
error | DevJobFailure | Only when status is failed. |
memory | DevMemoryProcessing | Processing jobs of a conversation batch: where memory distillation is. status does not wait for it. |
space_id | DevId | Tree jobs. |
progress | DevJobProgress | |
result | DevTreeJobResult | |
queue | DevQueueEstimate | Imports: how many imported files went on the processing queue, and roughly how long the account's queue needs. |
created_atRequired | string (date-time) | When the job was created. |
updated_atRequired | string (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.
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.
DevJobReceipt
| Field | Type | Description |
|---|---|---|
job_idRequired | DevId | Poll 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
| Field | Type | Description |
|---|---|---|
nameRequired | string | Stable 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. |
valueRequired | integer | The limit's value for this account. |
Limits
| Name | Default | Scope | When exceeded |
|---|---|---|---|
requests_per_minute_read | 600 | Per key: GET, HEAD, search, and context requests per minute | 429 rate_limited with limit: request_rate |
requests_per_minute_write | 120 | Per key: every other request per minute | 429 rate_limited with limit: request_rate |
retrieval_concurrency | 2 | Per principal: searches and context calls running at once | 429 rate_limited with limit: concurrency, after waiting up to 1 second for a slot |
agent_retrieval_concurrency | 8 | Per Agent principal, in place of retrieval_concurrency | 429 rate_limited with limit: concurrency, after waiting up to 1 second for a slot |
answer_concurrency | 3 | Per principal: answers running at once | 429 rate_limited with limit: concurrency, after waiting up to 10 seconds for a slot |
space_write_concurrency | 4 | Per Space: writes running at once | 429 rate_limited with limit: concurrency, after waiting up to 1 second for a slot |
space_writes_per_month | 100,000 | Per Space: writes in a UTC calendar month | 429 quota_exceeded |
tenant_writes_per_month | 1,000,000 | Per account: writes in a UTC calendar month | 429 quota_exceeded |
space_storage_bytes | 10 GiB | Per Space: bytes stored | 429 quota_exceeded |
tenant_storage_bytes | 100 GiB | Per account: bytes stored | 429 quota_exceeded |
tenant_model_tokens_per_month | 1,000,000 | Per 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 it | 429 quota_exceeded with quota: model_tokens; a processing step that needs the model fails with quota_exceeded |
tenant_model_spend_micro_usd_per_month | 2,000,000 | Per 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 it | 429 quota_exceeded with quota: model_spend_micro_usd; a processing step that needs the model fails with quota_exceeded |
tenant_queued_jobs | 10,000 | Per 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 number | 429 ingest_backlog |
space_active_branches | 100 | Per Space: active branches | 409 branch_limit_reached |
branch_paths | 10,000 | Per branch: paths | 409 branch_too_large |
branch_checkpoints | 100 | Per branch: checkpoints | 409 checkpoint_limit_reached |
branch_ttl_days | 30 | Per branch: days without a write before it expires | - |
branch_reclaim_days | 7 | Per branch: days from its end until it is reclaimed | - |
space_snapshots | 100 | Per Space: snapshots | 409 too_many_snapshots |
snapshot_files | 10,000 | Per snapshot: files | 409 snapshot_too_large |
export_max_bytes | 4 GiB | Per export: original bytes | 409 export_too_large |
import_max_bytes | 1 GiB | Per import: archive bytes | 413 archive_too_large |
tenant_api_keys | 100 | Per account: live keys | 409 tenant_limit_reached |
tenant_principals | 200 | Per account: principals | 409 tenant_limit_reached |
tenant_spaces | 10,000 | Per account: Spaces not deleted | 409 tenant_limit_reached |
team_members | 50 | Per team: members (console) | - |
team_pending_invitations | 20 | Per team: invitations waiting to be accepted (console) | - |
team_invitations_per_day | 100 | Per team: invitations sent in a day (console) | - |
tenant_requests_per_minute_read | 6,000 | Per account: read requests per minute across all keys, 10 times requests_per_minute_read | 429 rate_limited with limit: request_rate |
tenant_requests_per_minute_write | 1,200 | Per account: other requests per minute across all keys, 10 times requests_per_minute_write | 429 rate_limited with limit: request_rate |
tenant_retrieval_concurrency | 80 | Per account: searches and context calls running at once across all principals, 10 times agent_retrieval_concurrency | 429 rate_limited with limit: concurrency, after waiting up to 1 second for a slot |
DevLimits
DevLineage
Where an Entry came from, and one page of its versions, newest first. Who copied it is not listed.
| Field | Type | Description |
|---|---|---|
entry_idRequired | DevId | length 1..256 |
originRequired | DevLineageOrigin | How the Entry came to exist. |
dataRequired | DevLineageVersion[] | One page of its versions, newest first. |
next_cursor | DevCursor | length 1..1024 |
DevLineageOrigin
| Field | Type | Description |
|---|---|---|
kindRequired | DevLineageOriginKind | created: written directly. copy: copied from another Entry. branch_merge: first written by a branch merge. |
source | DevLineageRef | For copy: the Entry and version it was copied from. |
branch_id | DevId | For branch_merge: the branch, by id only. Branches are reclaimed after they close. |
chain | DevLineageRef[] | For copy, when the source was itself a copy: further up, nearest first, at most 16. |
chain_truncated | true | The 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.
DevLineageVersion
| Field | Type | Description |
|---|---|---|
version_idRequired | DevId | length 1..256 |
parent_version_idsRequired | DevId[] | The versions this one was written on top of. Empty on the Entry's first version. |
created_atRequired | string (date-time) | When the version was written. |
author_principal_id | DevId | length 1..256 |
kindRequired | DevVersionKind | |
restored_from | DevId | For revert. |
proposal_id | DevId | For proposal_accept. |
branch_id | DevId | For branch_merge. |
message | string | The version's message, when it has one. |
session_id | string | The 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.
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
| Field | Type | Description |
|---|---|---|
nameRequired | DevMcpToolName | |
descriptionRequired | string | What the tool does, as it is shown to the model. |
inputSchemaRequired | object | The 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.
| Field | Type | Description |
|---|---|---|
idRequired | DevId | Pass it to the other memory endpoints. A distilled fact's id contains colons, so percent-encode it in a path. |
entry_id | DevId | The Entry this memory is, or the Entry it was distilled from. Absent on account memory. |
space_id | DevId | Absent on account memory, which belongs to no Space you can address. |
scopeRequired | DevMemoryScope | Whose memory it is: account (the person, across Spaces), project (the Space), or agent (one Agent's own). |
kindRequired | string | What sort of memory, such as preference, decision, or progress; distilled facts have others, such as experience. GET /v2/memories?kind= filters on it. |
statusRequired | DevMemoryStatus | confirmed memories take effect in retrieval and MEMORY.md; a candidate waits for review; rejected and superseded are history. |
textRequired | string | The memory itself, as one statement. |
pinnedRequired | boolean | Whether the memory is pinned. Only memories written as Entries can be pinned. |
supersedes | DevId | On a correction: the memory it replaced. |
valid_from | string (date-time) | When the fact became true, if the source said so. |
valid_to | string (date-time) | When this stopped being the current value. With replaced_by, it is when the newer value took over. |
created_atRequired | string (date-time) | When the memory was first written or distilled. |
updated_atRequired | string (date-time) | When it last changed: a review, a correction, a pin, or a new validity. |
replaced_by | DevReplacingMemory | Only 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. |
dormant | DevMemoryDormancy | Only 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_id | DevId | Only 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. |
sources | DevMemorySource[] | With group_id: the members of the group you can see, smallest id first, this one included. |
pending_proposals | DevId[] | 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
| Field | Type | Description |
|---|---|---|
reasonRequired | DevMemoryDormancyReason | |
dream_idRequired | DevId | length 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.
| Field | Type | Description |
|---|---|---|
memory_idRequired | DevId | length 1..256 |
statusRequired | forgotten | Always forgotten. |
remaining_sources | DevForgottenSource[] | 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.
| Field | Type | Description |
|---|---|---|
stateRequired | pending | ready | skipped | failed | pending 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. |
count | integer | Only when state is ready: how many memories the batch wrote, candidates included. 0 means it found nothing to keep. |
reason | DevMemoryProcessingReason | With 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. |
remediation | DevRemediation | Only 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.
| Field | Type | Description |
|---|---|---|
idRequired | DevId | length 1..256 |
space_idRequired | DevId | length 1..256 |
scopeRequired | DevDreamScope | |
agent_principal_id | DevId | For an agent proposal: whose private memory. |
dream_idRequired | DevId | The dream that proposed it. |
kindRequired | DevMemoryProposalKind | What it suggests: merge, supersede, conflict, or promote. |
member_idsRequired | DevId[] | The memories it is about, sorted. |
proposed_text | string | The statement it proposes. Absent for now; always absent for conflict. |
evidence | DevMemoryProposalEvidence[] | The verbatim quotes that back the proposal. |
plan | DevMemoryProposalPlan | What approve would do. Absent for conflict, which has nothing to apply. |
layer | DevMemoryLayer | The memory layer of its members: rule, decision, event, or knowledge. |
times | DevMemoryProposalTime[] | Dates that decided which memory is newer. |
statusRequired | DevMemoryProposalStatus | withdrawn 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_id | DevId | Who approved or rejected it. |
reviewed_at | string (date-time) | When it was approved or rejected. |
closed_at | string (date-time) | When it stopped being open, for any reason. |
created_atRequired | string (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.
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.
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.
DevMemoryProvenance
| Field | Type | Description |
|---|---|---|
memory_idRequired | DevId | length 1..256 |
sourcesRequired | DevMemoryProvenanceSource[] | The Entry versions this memory rests on. All of them come back in one response: the list is not paginated. |
DevMemoryProvenanceSource
| Field | Type | Description |
|---|---|---|
entry_idRequired | DevId | length 1..256 |
version_idRequired | DevId | length 1..256 |
quote | string | The words in that version this memory rests on. |
merged_from | DevId | Only 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
| Field | Type | Description |
|---|---|---|
sourceRequired | account | agent | project | usage | account, agent, project, or usage. |
kindRequired | string | The kind of memory, such as preference or decision. |
textRequired | string | The memory itself. |
confidenceRequired | number | From 0 to 1: the confidence recorded with this memory.0..1 |
valid_until | string (date-time) | After this moment the memory is no longer served. Absent when it does not expire. |
source_refRequired | DevMemorySourceRef | Where the memory came from. |
DevMemorySettings
A Space's memory consolidation setting. A Space nobody configured reports the defaults and no updated_* fields.
| Field | Type | Description |
|---|---|---|
space_idRequired | DevId | length 1..256 |
memory_dreamingRequired | DevMemoryDreamingMode | Whether dreams run: propose (the default) or off. |
dormancyRequired | DevMemoryDormancyMode | What a dream does with unused memories: report (the default) or apply. |
d4Required | DevMemoryD4Mode | Whether a dream asks a model to compare memories: off (the default), shadow, or propose. |
d4_available | boolean | Whether 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_at | string (date-time) | When the settings were last changed. Absent while nobody has configured the Space. |
updated_by_principal_id | DevId | length 1..256 |
DevMemorySource
One member of a group of distilled memories.
DevMemorySourceRef
| Field | Type | Description |
|---|---|---|
memory_id | DevId | length 1..256 |
candidate_id | DevId | length 1..256 |
claim_id | DevId | length 1..256 |
entry_id | DevId | length 1..256 |
version_id | DevId | length 1..256 |
space_id | DevId | length 1..256 |
recorded_atRequired | string (date-time) | When the memory was recorded. |
valid_fromRequired | string (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.
DevMemoryView
The deterministic memory view: the same memories give the same bytes, whatever the task.
| Field | Type | Description |
|---|---|---|
sectionsRequired | DevMemorySection[] | 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.
| Field | Type | Description |
|---|---|---|
pathRequired | DevPath | length 1..4096 |
base_version_idRequired | DevId | null | The main version the branch started from at this path. Null when the file did not exist then. |
main_version_idRequired | DevId | null | Main's latest version at this path now. Null when the file no longer exists. |
branch_version_idRequired | string | null | The branch's content hash, the same value as its etag without quotes. Null on a delete. |
DevMergeConflictPolicy
Values: abort | keep_main | keep_branch
DevMergeProposed
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.
| Field | Type | Description |
|---|---|---|
messageRequired | string | 1 to 1000 characters. Recorded as the message of every version the merge writes to main.length 1..1000 |
paths | DevPath[] | 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_conflict | DevMergeConflictPolicy | What to do with a path main changed after the branch started from it: abort, keep_main, or keep_branch.default: "abort" |
DevMergeResult
| Field | Type | Description |
|---|---|---|
branch_idRequired | DevId | length 1..256 |
stateRequired | active | merged | The branch's state after the merge: merged, or still active when only paths were merged. |
mergedRequired | DevPath[] | Paths written to main. merged_items has the versions. |
skippedRequired | DevPath[] | Paths left out. skipped_items has the reasons. |
merged_itemsRequired | DevMergedPath[] | One item per path written to main: what was done and the resulting version. |
skipped_itemsRequired | DevMergeSkipped[] | One item per path left out, with the reason. |
proposed_items | DevMergeProposed[] | 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
| Field | Type | Description |
|---|---|---|
pathRequired | DevPath | length 1..4096 |
reasonRequired | DevMergeSkipReason | symlink: 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
| Field | Type | Description |
|---|---|---|
pathRequired | DevPath | length 1..4096 |
opRequired | DevMergedOp | What the merge did on main: create, update, delete, or mkdir. |
entry_id | DevId | length 1..256 |
version_id | DevId | length 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.
| Field | Type | Description |
|---|---|---|
anyRequired | DevMetadataValue[] | 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.
| Field | Type | Description |
|---|---|---|
passagesRequired | integer | Passages the content was split into for retrieval. |
charactersRequired | integer | Characters of text extracted, including text read from images and transcribed from audio. |
duration_ms | integer | Audio and video: length of the recording in milliseconds. |
speakers | integer | Audio and video: the number of distinct speakers the transcript tells apart. Absent when it does not tell them apart. |
sheets | integer | Spreadsheets and CSV: number of sheets. |
rows | integer | Spreadsheets and CSV: rows across all sheets. |
columns | integer | Spreadsheets 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.
| Field | Type | Description |
|---|---|---|
entriesRequired | integer | How 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.
| Field | Type | Description |
|---|---|---|
idRequired | DevId | Starts with prn_ for principals created through the API. |
kindRequired | DevPrincipalKind | human for a person, agent for an Agent. |
rolesRequired | string[] | Directory roles, such as tenant_admin. |
capabilitiesRequired | DevCapability[] | What keys issued to this principal can be granted at most. |
created_atRequired | string (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.
DevProcessingProgress
How many of the main steps (extract the text, index it, publish it to search) are done.
DevProcessingQueue
Why the current step has not started yet.
| Field | Type | Description |
|---|---|---|
positionRequired | integer | Due 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_secondsRequired | integer | Seconds since the step was queued. |
waiting_forRequired | capacity | retry | paused | capacity: 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.
| Field | Type | Description |
|---|---|---|
idRequired | DevId | length 1..256 |
space_idRequired | DevId | length 1..256 |
entry_idRequired | DevId | length 1..256 |
path | DevPath | Where the file is now. Absent while it is in the trash. |
statusRequired | DevProposalStatus | open until a reviewer approves or rejects it, or its author withdraws it. |
base_version_idRequired | DevId | length 1..256 |
proposed_version_idRequired | DevId | length 1..256 |
approved_version_id | DevId | The version approval wrote. |
author_principal_id | DevId | length 1..256 |
reviewed_by_principal_id | DevId | Who approved or rejected it. |
size_bytesRequired | integer | Size of the proposed content in bytes. |
media_typeRequired | string | Media type of the proposed content. |
sha256 | string | Hex SHA-256 of the proposed bytes. |
created_atRequired | string (date-time) | When the proposal was made. |
reviewed_at | string (date-time) | When it was approved or rejected. |
closed_at | string (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.
| Field | Type | Description |
|---|---|---|
appliedRequired | false | Always false: the write became a proposal and the file did not change. |
proposal_idRequired | DevId | length 1..256 |
entry_idRequired | DevId | length 1..256 |
base_version_idRequired | DevId | The file's latest version when the proposal was made. Approval needs it to still be the latest. |
proposed_version_idRequired | DevId | The 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
| Field | Type | Description |
|---|---|---|
purgedRequired | DevPurgedEntry[] | The Entries erased by this call, at most 100. |
has_moreRequired | boolean | True when the trash still holds more: call again. |
DevPurgeTrashRequest
| Field | Type | Description |
|---|---|---|
delete_batch_id | DevId | Erase 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.
DevQueueEstimate
How many items a bulk write put on the processing queue, and roughly how long the queue needs.
| Field | Type | Description |
|---|---|---|
queued_itemsRequired | integer | Items that wrote a new version and so were queued for processing. |
eta_seconds | integer | Estimated 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. |
paused | boolean | Present 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.
DevReplacingMemory
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.
| Field | Type | Description |
|---|---|---|
idRequired | DevId | length 1..256 |
created_atRequired | string (date-time) | When the request arrived. |
methodRequired | GET | HEAD | POST | PUT | PATCH | DELETE | OPTIONS | |
routeRequired | string | The method and route template, such as GET /v2/spaces/:space_id/files. Ids and paths in the URL are not kept. |
statusRequired | integer | |
error_code | string | The 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_msRequired | integer | From arrival to the response; for a streamed answer, to the end of the stream. |
authRequired | api_key | console | token | How the request authenticated: an API key, the console session, or a sign-in token. |
principal_idRequired | DevId | length 1..256 |
key_id | DevId | The key that made the request. |
key_name | string | The key's name and prefix as they are now. Absent once the key is deleted. |
key_prefix | string | |
space_id | DevId | The Space in the path, when there is one. |
request_idRequired | string | The same as the X-Request-Id response header. |
trace_id | string | On 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}. |
clientRequired | DevRequestClient | |
client_version | string | The client's version, when its User-Agent has one. |
DevRequestLogPage
| Field | Type | Description |
|---|---|---|
dataRequired | DevRequestLog[] | The items on this page. |
next_cursor | DevCursor | Pass it as cursor to get the next page. Absent on the last page. |
retention_daysRequired | integer | How 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.
| Field | Type | Description |
|---|---|---|
reference_time | string (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. |
timezone | string | IANA 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.
| Field | Type | Description |
|---|---|---|
explain | boolean | True 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.
| Field | Type | Description |
|---|---|---|
metadata | object | Exact 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_types | DevSourceType[] | 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_from | string (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_to | string (date-time) | Keep Entries that happened at or before this instant. A value earlier than occurred_from returns 422. |
where | DevFilterCondition | A 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.
| Field | Type | Description |
|---|---|---|
profile | string | A 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. |
rerank | boolean | false 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_score | number | The 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_entry | integer | At 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.
| Field | Type | Description |
|---|---|---|
idRequired | DevId | length 1..256 |
kindRequired | search | context | answer | |
created_atRequired | string (date-time) | |
principal_id | DevId | length 1..256 |
query | string | Search only: the query as it was sent. |
citationsRequired | DevTraceCitation[] | The Entries and versions the call returned or gave the model. |
summaryRequired | DevTraceSummary |
DevRevertRequest
| Field | Type | Description |
|---|---|---|
version_idRequired | DevId | The id of the version to revert to; its content becomes the new latest version. |
DevReviewMemoryRequest
| Field | Type | Description |
|---|---|---|
decisionRequired | confirm | reject | confirm makes the candidate a memory; reject turns it down. |
DevRollbackRequest
| Field | Type | Description |
|---|---|---|
checkpoint_idRequired | DevId | The id of the checkpoint to roll back to. |
DevRotatedWebhookSecret
| Field | Type | Description |
|---|---|---|
webhook_idRequired | DevId | length 1..256 |
secret | string | The 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.
| Field | Type | Description |
|---|---|---|
idRequired | DevId | Contains :. Percent-encode it in a path. |
kindRequired | string | The kind of memory, such as preference or event. |
textRequired | string | The memory's statement. |
valid_from | string (date-time) | When this value took effect, when that is known. |
valid_to | string (date-time) | When this stopped being the current value: the moment the next value took effect. Absent while current. |
replaced_by | DevReplacingMemory | The 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.
| Field | Type | Description |
|---|---|---|
entry_idRequired | DevId | The Entry the passage is from. |
version_idRequired | DevId | The version the passage was read from. |
space_id | DevId | Absent on account memory, which belongs to no Space you can address. |
titleRequired | string | The Entry's title; for a file, its name. |
textRequired | string | The matching passage. |
scoreRequired | number | Comparable inside one response only. |
citation_idRequired | string | c1, c2, ... in the order of this response. |
source_typeRequired | string | What kind of source it is: file, note, web, agent-conversation, or a memory type. |
path | DevPath | The file's path. Absent for an Entry without one. |
url | string | On an Entry ingested from a URL: that URL, to link back to the page. A file has path instead. |
occurred_at | string (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_at | string (date-time) | When the version the passage was read from was written. With occurred_at it tells old from new. |
stated_date | string (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_from | text | heading | document | Where stated_date was read: the passage text, a section heading above it, or the document head. On search only text and document occur. |
freshness | pending_index | pending_index means the match came from the freshness buffer, lexically only. |
memory | DevRoutedMemory | Only 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. |
explain | DevHitExplain | Only 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
| Field | Type | Description |
|---|---|---|
queryRequired | string | What to look for, in natural language or keywords.length 1..1000 |
space_ids | DevSpaceRef[] | 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 |
path | DevPath | Restrict results to this subtree, or to this one file. Resolved in each Space searched. Empty when it exists in none of them. |
include | memory[] | ["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 |
limit | integer | How many hits to return at most. This is a total, unlike a list's page size.1..50, default: 20 |
filter | DevRetrievalFilter | Narrow what is searched before ranking. Combines with path and space_ids: all of them must hold. |
tier | DevContextTier | As 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" |
fields | DevSearchHitField[] | 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 |
profile | string | A 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. |
rerank | boolean | false 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_score | number | The 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_entry | integer | At 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_time | string (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. |
timezone | string | IANA 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. |
explain | boolean | True 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
| Field | Type | Description |
|---|---|---|
dataRequired | DevSearchHit[] | The hits, best first. |
trace_idRequired | DevId | length 1..256 |
partialRequired | boolean | True when a retrieval branch degraded or the scores are not calibrated relevance. |
explain | DevExplainSummary | Only when the request set explain. |
pending_processing | DevPendingProcessing | Only 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
| Field | Type | Description |
|---|---|---|
roleRequired | editor | viewer | editor can write; viewer can only read. Ownership cannot be granted here. |
write_mode | DevWriteMode | Defaults to proposal for a new member; otherwise the current value stays. |
write_root | string | null | Limit 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_root | string | null | Limit 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).
| Field | Type | Description |
|---|---|---|
idRequired | DevId | length 1..256 |
space_idRequired | DevId | length 1..256 |
nameRequired | string | The snapshot's name. snapshot= takes it in place of the id. |
file_countRequired | integer | Files 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_cursorRequired | DevCursor | The 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_idRequired | DevId | length 1..256 |
created_atRequired | string (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.
| Field | Type | Description |
|---|---|---|
idRequired | DevId | Starts 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. |
nameRequired | string | The Space's name. |
description | string | A note about what the Space is for. |
external_id | string | Your 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_defaultRequired | boolean | True on the Space that default resolves to for you. |
access_roleRequired | DevSpaceRole | Your role in this Space: owner, editor, or viewer. |
read_root | DevPath | Your 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_root | DevPath | Your own write root in this Space, as its path at the moment of reading. Absent when your writes are not limited. |
created_atRequired | string (date-time) | When the Space was created. |
updated_atRequired | string (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.
| Field | Type | Description |
|---|---|---|
sinceRequired | string (date-time) | The start of the period. |
truncatedRequired | boolean | True when the period held more than the 1000 changes this looks back over: older ones are not counted. |
dataRequired | DevActivityActor[] | One item per principal that changed something. |
DevSpaceDeletion
The receipt of a deleted Space. Its content is erased in the background.
DevSpaceMember
| Field | Type | Description |
|---|---|---|
principal_idRequired | DevId | length 1..256 |
roleRequired | DevSpaceRole | owner, editor, or viewer. |
write_modeRequired | DevWriteMode | |
write_root | DevPath | The 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_root | DevPath | The 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.
| Field | Type | Description |
|---|---|---|
pendingRequired | integer | Entries whose memory extraction is queued or running. They are already counted as searchable or processing. |
eta_seconds | integer | Upper bound in seconds for the pending extractions, from the account's hourly memory-extraction rate. Absent when nothing is pending. |
filesRequired | index_only | distill | Whether 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.
| Field | Type | Description |
|---|---|---|
space_idRequired | DevId | length 1..256 |
countsRequired | DevSpaceProcessingCounts | |
stagesRequired | DevSpaceProcessingStages | |
searchable_per_minute | number | Entries per minute that became searchable over the last five minutes. Absent when none did. |
eta_seconds | integer | Estimated seconds until every queued and processing Entry is searchable, from that rate. Absent without a rate or when nothing is pending. |
oldest_queued_seconds | integer | Seconds the longest-waiting due step in this Space has been queued. Absent when nothing waits. |
waiting_for_capacityRequired | boolean | True when steps of this Space are due and wait for a free worker. Work from different Spaces and accounts takes turns. |
queue_position | integer | Due 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. |
memoryRequired | DevSpaceMemoryProgress | Memory extraction, reported apart: an Entry waiting only for it is searchable, not processing. |
as_ofRequired | string (date-time) | When the numbers were read. |
DevSpaceProcessingCounts
Entries of a Space by where their latest version is. Each Entry is counted once.
| Field | Type | Description |
|---|---|---|
queuedRequired | integer | Stored; no step has started. |
processingRequired | integer | Text extraction or indexing has started. |
searchableRequired | integer | Search finds them; enrichment (relations, classification, summary, memories) is still running. |
readyRequired | integer | Every step has finished. |
failedRequired | integer | Processing gave up. GET /v2/entries/{id}/processing says why. |
DevSpaceProcessingStages
Entries that are not ready yet, by step. enriching equals counts.searchable.
| Field | Type | Description |
|---|---|---|
queuedRequired | integer | |
extractingRequired | integer | |
indexingRequired | integer | |
enrichingRequired | integer |
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
| Field | Type | Description |
|---|---|---|
metricRequired | writes | storage_bytes | model_tokens | model_spend_micro_usd | writes (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_startRequired | string (date-time) | The start of the window used counts from. The Unix epoch for a cumulative metric. |
usedRequired | integer | How much of the metric has been used in the window. |
limit | integer | The quota. Absent when the metric is not limited. |
space_idRequired | DevId | length 1..256 |
DevStartDreamRequest
| Field | Type | Description |
|---|---|---|
scope | DevDreamScope | Default: 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.
DevTraceCandidates
| Field | Type | Description |
|---|---|---|
lexical | integer | |
dense | integer | |
dense_document | integer | |
memory | integer | |
relation | integer |
DevTraceCitation
| Field | Type | Description |
|---|---|---|
entry_idRequired | DevId | length 1..256 |
version_idRequired | DevId | length 1..256 |
citation_id | string | |
source | string |
DevTraceSource
DevTraceStage
| Field | Type | Description |
|---|---|---|
stageRequired | string | The stage, such as embed, lexical, dense, rerank or authorize. |
statusRequired | succeeded | failed | cancelled | skipped | |
duration_ms | integer | Only for a tenant_admin with knowledge:manage. |
DevTraceSummary
Counts and decisions recorded for the retrieval. Which fields are present depends on kind.
| Field | Type | Description |
|---|---|---|
candidates | DevTraceCandidates | Search: 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_count | integer | |
ranked_count | integer | |
final_count | integer | |
rerank_applied | boolean | |
partial | boolean | |
duration_ms | integer | |
stages | DevTraceStage[] | Search: time spent in each stage. |
purpose | string | Context and answer: the routing decision, as route on the response. |
tier | string | |
rules_fired | string[] | |
sources | DevTraceSource[] | |
tokens_used | integer | |
budget_tokens | integer |
DevTreeChmod
Valid only with branch; returns 422 without it. On a merge 755 becomes the metadata key mirabase.mode.
DevTreeCopied
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.
DevTreeDelete
DevTreeJobResult
What a tree job did. Only counts and ids, apart from a failed merge's first 100 conflicts.
| Field | Type | Description |
|---|---|---|
delete_batch_id | DevId | A recursive delete: the id to pass to restore, which brings back everything the job deleted, including the part done before a failure. |
copies | integer | Files copied so far. |
restored | integer | Nodes restored. |
merged | integer | A merge: paths written to main. |
proposed | integer | A merge: files proposed instead of written. |
skipped | integer | A merge, an export, or an import: items left out. |
conflicts | DevMergeConflict[] | A merge that failed with merge_conflict: the first 100 conflicting paths.max items 100 |
files | integer | An export: files in the archive. skipped counts files with no bytes to export. |
bytes | integer | An export: total bytes of the files in the archive. |
archive | DevArchive | An export that succeeded: the archive. Download it with GET /v2/jobs/{job_id}/content-url. |
created | integer | An import: new files created. skipped counts members left alone (on_conflict: "skip", the same bytes, or outside files/ in an exported archive). |
updated | integer | An import: files that already existed and got a new version. |
failed | integer | An import: members that could not be written. |
failures | DevImportFailure[] | 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.
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.
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.
| Field | Type | Description |
|---|---|---|
pathRequired | DevPath | length 1..4096 |
nameRequired | string | The last segment of path, as it was written. |
kindRequired | DevTreeNodeKind | dir or file; a branch listing also has symlink. |
entry_id | DevId | length 1..256 |
version_id | DevId | On files: the latest version. Through a snapshot, the version the snapshot pinned. Not on a branch listing. |
size_bytes | integer | On files. On a branch listing, only on the paths the branch changed. |
etag | string | On 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. |
sha256 | string | On files a branch changed, and on files listed through a snapshot when known. |
media_type | string | On files. On a branch listing, only on the files the branch changed. |
modified_at | string (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. |
mode | 644 | 755 | 644 or 755. On paths a branch changed. |
link_target | string | On a symlink. |
updated_atRequired | string (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).
| Field | Type | Description |
|---|---|---|
operationsRequired | DevTreeOperation[] | 1 to 200 operations, applied in order.items 1..200 |
DevTreeOperationsResponse
| Field | Type | Description |
|---|---|---|
delete_batch_id | DevId | Present when the request deleted anything; restores the batch as one unit. |
copies | DevTreeCopied[] | 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.
| Field | Type | Description |
|---|---|---|
dataRequired | DevTreeNode[] | The items on this page. |
next_cursor | DevCursor | Pass it as cursor to get the next page. Absent on the last page. |
changes_cursorRequired | DevCursor | Pass 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.
| Field | Type | Description |
|---|---|---|
opRequired | restore | Always restore. |
path | DevPath | length 1..4096 |
delete_batch_id | DevId | length 1..256 |
DevTreeSymlink
Valid only with branch, and returns 422 without it: main has no symlinks. Merging skips them.
DevUpdateBranchRequest
Setting ttl_days also renews: expires_at becomes now plus that many days.
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.
| Field | Type | Description |
|---|---|---|
title | string | A new title, 1 to 512 characters. Not supported on a file: rename it with tree/operations.length 1..512 |
metadata | DevMetadata | Replaces 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_patch | object | Changes 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_exclude | boolean | true 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_at | string (date-time) | null | When 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.
DevUpdateMemorySettingsRequest
Give at least one field; a field left out keeps its value.
| Field | Type | Description |
|---|---|---|
memory_dreaming | DevMemoryDreamingMode | auto returns 422 until it is available. |
dormancy | DevMemoryDormancyMode | What a dream does with unused memories: report (the default) or apply. |
d4 | DevMemoryD4Mode | Whether a dream asks a model to compare memories: off (the default), shadow, or propose. |
DevUpdatePrincipalRequest
| Field | Type | Description |
|---|---|---|
grant_capabilitiesRequired | DevCapability[] | 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.
| Field | Type | Description |
|---|---|---|
name | string | A new name, 1 to 512 characters.length 1..512 |
description | string | null | A new description, or null to clear it.length 1..4096 |
external_id | string | null | A 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
| Field | Type | Description |
|---|---|---|
messageRequired | string | The version's new message, at most 120 characters.max length 120 |
DevUpdateWebhookRequest
| Field | Type | Description |
|---|---|---|
url | string | A new receiver URL, under the same rules as on create.max length 2048 |
ops | DevChangeOp[] | The event kinds to send from now on. No repeats.items 1..5 |
description | string | null | null clears it.max length 256 |
status | DevWebhookStatus | disabled 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_cursor | true | Skip everything not yet delivered and continue from now. Required to reopen a webhook disabled with cursor_expired. |
DevUpload
DevUploadPartHeaders
Send these on every part.
| Field | Type | Description |
|---|---|---|
content-typeRequired | string | The Content-Type every part's PUT must carry. |
DevUploadPartTarget
| Field | Type | Description |
|---|---|---|
part_numberRequired | integer | The part this URL is for, numbered from 1. |
urlRequired | string (uri) | PUT the part here. |
DevUploadParts
Parts already received are left out of data, so asking again resumes an upload.
| Field | Type | Description |
|---|---|---|
dataRequired | DevUploadPartTarget[] | One upload target per part that is still to be uploaded. |
receivedRequired | DevCompletedPart[] | 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_atRequired | string (date-time) | At most five minutes away. |
required_headersRequired | DevUploadPartHeaders |
DevUploadPartsRequest
| Field | Type | Description |
|---|---|---|
part_numbersRequired | integer[] | Numbered from 1.items 1..128 |
DevUsageFigure
| Field | Type | Description |
|---|---|---|
metricRequired | writes | storage_bytes | model_tokens | model_spend_micro_usd | writes (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_startRequired | string (date-time) | The start of the window used counts from. The Unix epoch for a cumulative metric. |
usedRequired | integer | How much of the metric has been used in the window. |
limit | integer | The quota. Absent when the metric is not limited. |
DevUsagePage
Paginated like every list, with tenant-wide totals beside the page rather than inside it.
| Field | Type | Description |
|---|---|---|
dataRequired | DevSpaceUsageFigure[] | One figure per Space and metric, ordered by Space id, then metric. |
next_cursor | DevCursor | length 1..1024 |
tenant_totals | DevUsageFigure[] | On the first page only, for a tenant_admin key without Space restrictions. |
plan | DevPlan | The 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.
| Field | Type | Description |
|---|---|---|
idRequired | DevId | Starts with ver_. |
entry_idRequired | DevId | The Entry this is a version of. |
statusRequired | DevVersionStatus | How far processing has progressed. |
updated_from | DevId | The version this one replaced. Absent on the first version. |
message | string | The note its author attached, like a commit message. |
author_principal_id | DevId | Who wrote it. |
created_atRequired | string (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.
| Field | Type | Description |
|---|---|---|
entry_idRequired | DevId | length 1..256 |
from_version_idRequired | DevId | length 1..256 |
to_version_idRequired | DevId | length 1..256 |
identicalRequired | boolean | True when both versions hold the same bytes. |
basisRequired | DevDiffBasis | |
unified_diff | string | The differences in unified diff format. Empty when identical; absent when diff_omitted is set. |
diff_omitted | DevDiffOmitted |
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.
| Field | Type | Description |
|---|---|---|
idRequired | DevId | length 1..256 |
space_idRequired | DevId | length 1..256 |
urlRequired | string (uri) | https on port 443. |
opsRequired | DevChangeOp[] | Event kinds to send. Events of other kinds are skipped, not queued. |
description | string | A note for people. |
statusRequired | DevWebhookStatus | active, or disabled when deliveries have stopped; disabled_reason says why. |
disabled_reason | DevWebhookDisabledReason | Present when status is disabled. |
cursorRequired | DevCursor | The change-feed position after the last batch delivered or skipped. |
consecutive_failuresRequired | integer | Failed attempts since the last success. |
last_success_at | string (date-time) | When a batch was last delivered. |
last_failure_at | string (date-time) | When an attempt last failed. |
next_attempt_at | string (date-time) | When the next attempt may start. Absent when disabled. |
created_by_principal_idRequired | DevId | length 1..256 |
created_atRequired | string (date-time) | When the webhook was created. |
updated_atRequired | string (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.
| Field | Type | Description |
|---|---|---|
idRequired | DevId | length 1..256 |
delivery_idRequired | DevId | The batch, the same as Mirabase-Delivery-Id. Attempts at one batch share it. |
first_seqRequired | integer | The first change sequence number of the batch, before filtering. |
last_seqRequired | integer | The last change sequence number of the batch, before filtering. |
event_countRequired | integer | Events sent after filtering. |
attemptRequired | integer | 1 for the first attempt at this batch. |
outcomeRequired | DevWebhookOutcome | delivered on any 2xx answer, otherwise failed. |
http_status | integer | The receiver's HTTP status, when it answered. |
error_code | DevWebhookErrorCode | |
duration_msRequired | integer | How long the attempt took, in milliseconds. |
created_atRequired | string (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.
DevWebhookStatus
Values: active | disabled
DevWhoami
| Field | Type | Description |
|---|---|---|
tenant_idRequired | DevId | The account this key belongs to. |
principalRequired | DevPrincipal | Who the request acts as. |
key | DevWhoamiKey | Absent when the request was not authenticated with an API key. |
effective_capabilitiesRequired | DevCapability[] | Principal capabilities intersected with key capabilities. |
DevWhoamiKey
| Field | Type | Description |
|---|---|---|
idRequired | DevId | length 1..256 |
prefixRequired | string | The first characters of the key: safe to show, enough to tell keys apart. |
capabilitiesRequired | DevCapability[] | What the key itself allows. A request acts with effective_capabilities, the part the principal also has. |
allowed_space_ids | DevId[] | The Spaces the key is narrowed to. Absent means not narrowed to specific Spaces. |
metadata_scope | DevMetadataScope | The metadata scope the key is limited to. Absent means not limited by metadata. |
expires_at | string (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.
| Field | Type | Description |
|---|---|---|
callsRequired | integer | |
errorsRequired | integer | |
input_tokensRequired | integer | |
output_tokensRequired | integer | |
total_tokensRequired | integer | |
audio_secondsRequired | number | |
imagesRequired | integer | |
model_usdRequired | number | |
unpriced_callsRequired | integer | Calls whose model has no price; their spend is not in model_usd. |
