# Schemas

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

## DevAccountQueue

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `queued` | `integer` | Required | Jobs waiting: `due` ones plus `delayed` ones. |
| `due` | `integer` | Required | Jobs that can run now and wait for a worker. |
| `delayed` | `integer` | Required | Jobs waiting for a retry backoff or a scheduled time. |
| `running` | `integer` | Required |  |
| `paused` | `boolean` | Required | True when the service operator paused processing for this account; nothing runs until it is resumed. |
| `paused_at` | `string (date-time)` | Optional |  |
| `oldest_queued_seconds` | `integer` | Optional | How long the oldest due job has been waiting. Absent with nothing due. |
| `eta_seconds` | `integer` | Optional | 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. |
| `limit` | `integer` | Required | `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_of` | `string (date-time)` | Required |  |

## DevActivityActor

What one principal changed in the period.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `principal_id` | `DevId` | Optional | Who made the changes. Absent for changes the service made itself. |
| `last_changed_at` | `string (date-time)` | Required | When this principal last changed something. |
| `change_count` | `integer` | Required | How many changes this principal made in the period. |
| `files` | `DevActivityFile[]` | Required | The Entries changed, most recently changed first, at most 50. |
| `files_truncated` | `true` | Optional | 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 | Required | Description |
| --- | --- | --- | --- |
| `entry_id` | `DevId` | Required | The Entry that changed. |
| `path` | `DevPath` | Optional | Where it was at its latest change. Absent for an Entry without a path. |
| `op` | `DevChangeOp` | Required | The latest change: `create`, `update`, `move`, `delete`, or `restore`. |
| `version_id` | `DevId` | Optional | The version the latest change wrote, when it wrote one. |
| `changed_at` | `string (date-time)` | Required | When the latest change was committed. |
| `change_count` | `integer` | Required | How many times this principal changed the Entry in the period. |

## DevAnswer

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | `DevAnswerStatus` | Required | `answered`, or `abstained` when the evidence did not support an answer. |
| `answer` | `string` | Required | Empty when abstained. Cites evidence as `[cN]`. |
| `reason` | `DevAnswerAbstainReason` | Optional | Present when abstained. |
| `citations` | `DevAnswerCitation[]` | Required | Only the evidence `answer` cites, in order of first citation. |
| `evidence` | `DevAnswerEvidence[]` | Optional | Only when the request has `include: ["evidence"]`: every item the model read, in the order it read them. |
| `evidence_count` | `integer` | Required | Items the model was given. |
| `pack_id` | `DevId` | Required | Report what you used with [`POST /v2/retrieval/context/{pack_id}/feedback`](https://mirabase.io/developers/api/retrieval.md#retrieval-contextfeedback). |
| `partial` | `boolean` | Required | True when a retrieval branch degraded, so evidence may be missing. |
| `pending_processing` | `DevPendingProcessing` | Optional | Only when Entries in the searched Spaces are still being processed: the answer may lack them. |
| `route` | `DevContextRoute` | Required | How the evidence was chosen, as on a context pack. |
| `explain` | `DevAnswerExplain` | Optional | 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 | Required | Description |
| --- | --- | --- | --- |
| `citation_id` | `string` | Required | Appears as `[cN]` in `answer`. |
| `entry_id` | `DevId` | Required | The Entry the passage is from. |
| `version_id` | `DevId` | Required | The version the passage was read from. |
| `space_id` | `DevId` | Optional | The Space of that Entry. Absent on account memory. |
| `path` | `DevPath` | Optional | The file's path. Absent for an Entry without one. |
| `url` | `string` | Optional | 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)` | Optional | 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)` | Optional | When the version the passage was read from was written. With `occurred_at` it tells old from new. |
| `stated_date` | `string (date)` | Optional | 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` | Optional | Where `stated_date` was read: the passage `text`, a section `heading` above it, or the `document` head. |
| `title` | `string` | Required | The Entry's title; for a file, its name. |
| `source` | `DevContextSource` | Required | Which context source supplied the passage. |
| `text` | `string` | Required | The passage the model read. |
| `explain` | `DevHitExplain` | Optional | Only when the request set `explain`. |

## DevAnswerEvidence

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `citation_id` | `string` | Required | The id the model could cite it by. |
| `entry_id` | `DevId` | Required | The Entry the passage is from. |
| `version_id` | `DevId` | Required | The version the passage was read from. |
| `space_id` | `DevId` | Optional | The Space of that Entry. Absent on account memory. |
| `path` | `DevPath` | Optional | The file's path. Absent for an Entry without one. |
| `url` | `string` | Optional | On an Entry ingested from a URL: that URL. |
| `occurred_at` | `string (date-time)` | Optional | As on a citation. |
| `modified_at` | `string (date-time)` | Optional | As on a citation. |
| `stated_date` | `string (date)` | Optional | As on a citation. |
| `stated_date_from` | `text \| heading \| document` | Optional | As on a citation. |
| `title` | `string` | Required | The Entry's title; for a file, its name. |
| `source` | `DevContextSource` | Required | Which context source supplied the passage. |
| `explain` | `DevHitExplain` | Optional | Only when the request set `explain`. |

## DevAnswerExplain

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `terms` | `string[]` | Required | The terms the lexical branch searched for. |
| `candidates` | `DevExplainCandidateCount[]` | Required | Candidates per branch, counting only those you can read. Branches that returned nothing you can read are left out. |
| `fused_count` | `integer` | Required | Candidates you can read after the branches were merged. |
| `rerank` | `DevExplainRerankSummary` | Required |  |
| `clauses` | `string[]` | Optional | For a task that states several things: the clauses that were searched for separately. |
| `sentences` | `DevAnswerSentence[]` | Required | The answer split into sentences. Empty when the answer abstained. |

## DevAnswerRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `question` | `string` | Required | The question to answer, 1 to 4000 characters. length 1..4000 |
| `space_ids` | `DevSpaceRef[]` | Optional | 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` | Optional | What the answer is for, as on `context`: `task`, `coding`, `research`, or `audit`. |
| `weights` | `DevContextWeights` | Optional | 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` | Optional | How much retrieval work goes into finding the evidence, as on `context`: `fast`, `standard`, or `deep`. default: "standard" |
| `budget_tokens` | `integer` | Optional | Budget for the evidence the model reads. 500..16000, default: 4000 |
| `history` | `DevAnswerTurn[]` | Optional | 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` | Optional | A BCP 47 tag such as `en` or `zh-CN`. Only changes the language of `answer`. max length 35 |
| `filter` | `DevRetrievalFilter` | Optional | Narrow the evidence the answer may draw on, as on `context`. |
| `include` | `evidence[]` | Optional | `["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` | Optional | 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` | Optional | 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` | Optional | `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` | Optional | 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` | Optional | 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)` | Optional | 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` | Optional | 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` | Optional | 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 | Required | Description |
| --- | --- | --- | --- |
| `text` | `string` | Required | One sentence of `answer`, with its `[cN]` marks. |
| `citation_ids` | `string[]` | Required | 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 | Required | Description |
| --- | --- | --- | --- |
| `text` | `string` | Required | 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 | Required | Description |
| --- | --- | --- | --- |
| `request_id` | `string` | Required | The request's id, the same as the `X-Request-Id` response header. Quote it when you report a problem. |
| `pack_id` | `DevId` | Required | The same `pack_id` the `final` event carries. |
| `evidence_count` | `integer` | Required | Items the model is given. 0 means the answer will be an abstention with reason `no_evidence`. |
| `partial` | `boolean` | Required | True when a retrieval branch degraded, so evidence may be missing. |
| `evidence` | `DevAnswerEvidence[]` | Optional | Only when the request has `include: ["evidence"]`: every item the model reads, the same list `final` carries. |

## DevAnswerTurn

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `role` | `user \| assistant` | Required | Who said it: `user` or `assistant`. |
| `content` | `string` | Required | What was said, 1 to 4000 characters. length 1..4000 |

## DevApiKey

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `DevId` | Required | Starts with `key_`. Not the secret: the token is shown once, when the key is created or rotated. |
| `principal_id` | `DevId` | Required | The principal the key acts as. |
| `name` | `string` | Required | Your label for the key. |
| `prefix` | `string` | Required | Non-secret token prefix, for recognizing a key in a list. |
| `capabilities` | `DevCapability[]` | Required | What the key may do. Never more than its principal's capabilities. |
| `allowed_space_ids` | `DevId[]` | Optional | Absent means not narrowed to specific Spaces. |
| `metadata_scope` | `DevMetadataScope` | Optional | The metadata scope the key is limited to. Absent means not limited by metadata. |
| `expires_at` | `string (date-time)` | Optional | After this time the key stops working. Absent when it does not expire. |
| `revoked_at` | `string (date-time)` | Optional | When the key was revoked. Absent while it is live. |
| `last_used_at` | `string (date-time)` | Optional | When the key last called the API, to within a minute. Absent until its first call. |
| `created_by` | `DevId` | Required | The principal that issued it. |
| `issued_by_key_id` | `DevId` | Optional | The key that issued or rotated this one. Absent when no key was used. |
| `created_at` | `string (date-time)` | Required | When it was issued. |

## DevApproveProposalRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `message` | `string` | Optional | 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 | Required | Description |
| --- | --- | --- | --- |
| `size_bytes` | `integer` | Required | Size of the archive in bytes. |
| `sha256` | `string` | Required | Hex SHA-256 of the archive. |
| `media_type` | `string` | Required | `application/x-tar`. |
| `expires_at` | `string (date-time)` | Required | 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 | Required | Description |
| --- | --- | --- | --- |
| `url` | `string (uri)` | Required | The signed URL. Fetch it with a plain `GET`. |
| `method` | `GET` | Required | Always `GET`. |
| `expires_at` | `string (date-time)` | Required | UTC. At most 5 minutes after the request. |
| `job_id` | `DevId` | Required | length 1..256 |
| `size_bytes` | `integer` | Required | Size of the archive in bytes. |
| `media_type` | `string` | Required | `application/x-tar`. The response carries it with `Content-Disposition: attachment` and `Cache-Control: private, no-store`. |
| `sha256` | `string` | Required | Hex SHA-256 of the archive. |

## DevAuditEvent

Identifiers only. Audit events never contain user content.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `DevId` | Required | length 1..256 |
| `action` | `string` | Required | Stable action name, such as `entry.read`, `acl.set`, or `api_key.revoke`. |
| `outcome` | `DevAuditOutcome` | Required | How the action ended: `allowed`, `denied`, or `failed`. |
| `principal_id` | `DevId` | Required | The principal that acted. |
| `key_id` | `DevId` | Optional | Absent when the request was not authenticated with an API key. |
| `space_id` | `DevId` | Optional | Absent when the action has no single Space. |
| `resource_kind` | `string` | Required | 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` | Optional | For `entry` and `version` this is the Entry id; `version_id` names the version. |
| `version_id` | `DevId` | Optional | length 1..256 |
| `request_id` | `string` | Optional | The request that caused the event, the same id error bodies carry as `request_id`. |
| `created_at` | `string (date-time)` | Required | When the event was recorded. |

## DevAuditOutcome

Values: `allowed | denied | failed`

## DevBacklog

The account's processing queue when it is full.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `queued` | `integer` | Required | Jobs of the kind that reached its limit queued for the account. For a key limited to some Spaces or to metadata, the limit. |
| `limit` | `integer` | Required | `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. |
| `paused` | `boolean` | Required | 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` | Optional | 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 | Required | Description |
| --- | --- | --- | --- |
| `id` | `DevId` | Required | length 1..256 |
| `space_id` | `DevId` | Required | length 1..256 |
| `name` | `string` | Required | The branch's name. While the branch is active, paths and `?branch=` take it in place of the id. |
| `state` | `DevBranchState` | Required | `abandoned` also covers a branch past `expires_at` that the sweep has not reached yet. |
| `parent_branch_id` | `DevId` | Optional | Absent when the branch started from main. Nodes were copied: there is no parent chain. |
| `base_change_seq` | `integer` | Required | Main's change sequence when the branch opened. |
| `main_changed_paths` | `integer` | Required | 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_by` | `DevId` | Required | length 1..256 |
| `ttl_days` | `integer` | Required | How many days each write pushes `expires_at` out by. |
| `expires_at` | `string (date-time)` | Required | When the branch expires. Past this time the branch is abandoned, then reclaimed. |
| `created_at` | `string (date-time)` | Required | When the branch was opened. |
| `updated_at` | `string (date-time)` | Required | 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 | Required | Description |
| --- | --- | --- | --- |
| `source` | `branch \| main` | Required | `branch`: a change made on this branch. `main`: a change on main that this branch reads through. |
| `seq` | `integer` | Required | Sequence number within its `source`. |
| `op` | `DevChangeOp` | Required | The kind of change: `create`, `update`, `move`, `delete` or `restore`. |
| `path` | `DevPath` | Optional | length 1..4096 |
| `kind` | `DevBranchNodeKind` | Optional | On a `branch` change: whether the path is a directory, a file, or a symlink. |
| `entry_id` | `DevId` | Optional | length 1..256 |
| `version_id` | `DevId` | Optional | length 1..256 |
| `actor_principal_id` | `DevId` | Optional | length 1..256 |
| `created_at` | `string (date-time)` | Required | When the change was made. |

## DevBranchChangeFeed

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | `DevBranchChange[]` | Required | The events of this page. |
| `cursor` | `DevCursor` | Required | Pass back to continue. |
| `has_more` | `boolean` | Required | 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 | Required | Description |
| --- | --- | --- | --- |
| `path` | `DevPath` | Required | length 1..4096 |
| `change` | `DevBranchDiffOp` | Required | Whether the branch added, modified, or deleted the path. |
| `kind` | `DevBranchNodeKind` | Required | What the path is on the branch: a directory, a file, or a symlink. |
| `size` | `integer` | Optional | For a file: the size of the branch's content in bytes. |
| `mode` | `644 \| 755` | Optional | For a file: `644` or `755`. |
| `sha256` | `string` | Optional | For a file: hex SHA-256 of the branch's content. |
| `base_version_id` | `DevId` | Optional | length 1..256 |
| `unified_diff` | `string` | Optional | Text files only. Empty when the bytes differ only in a way line comparison cannot see. |
| `diff_omitted` | `too_large` | Optional | Set when a text file's diff was too large to compute. |

## DevBranchDiffOp

Values: `added | modified | deleted`

## DevBranchFileDeletion

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `branch_id` | `DevId` | Required | length 1..256 |
| `path` | `DevPath` | Required | length 1..4096 |
| `deleted` | `true` | Required | Always true: the path is now hidden on the branch. |

## DevBranchFileMeta

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `branch_id` | `DevId` | Required | length 1..256 |
| `path` | `DevPath` | Required | length 1..4096 |
| `kind` | `file \| symlink` | Required | Whether the path is a file or a symlink on the branch. |
| `size` | `integer` | Optional | Files only: size in bytes. |
| `media_type` | `string` | Optional | Files only: the media type the file was written with. |
| `mode` | `644 \| 755` | Optional | Files only: `644` or `755`. |
| `sha256` | `string` | Optional | Files only: hex SHA-256 of the content. |
| `etag` | `string` | Optional | Files only: send it in `If-Match` on the next write. It is a content hash, not a version. |
| `link_target` | `string` | Optional | Symlinks only: where the link points. |
| `updated_at` | `string (date-time)` | Required | 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.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `branch_id` | `DevId` | Required | length 1..256 |
| `path` | `DevPath` | Required | length 1..4096 |
| `view` | `text` | Required | Always `text`. |
| `text` | `string` | Required | The file's content as UTF-8 text. |

## DevBranchFileWrite

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `branch_id` | `DevId` | Required | length 1..256 |
| `path` | `DevPath` | Required | length 1..4096 |
| `sha256` | `string` | Required | Hex SHA-256 of the bytes written. |
| `size` | `integer` | Required | Size in bytes. |
| `media_type` | `string` | Required | The media type stored with the file. |
| `mode` | `644 \| 755` | Required | `644` or `755`. |
| `etag` | `string` | Required | The file's ETag on the branch, with quotes. Send it in `If-Match` on the next write. |
| `version_id` | `string` | Required | The `etag` without quotes. `changes?branch=` reports this write under the same `version_id`. |
| `created` | `boolean` | Required | True when nothing was at the path before this write, false when it replaced a file. |
| `changed` | `boolean` | Required | False when the bytes, media type, and mode are unchanged. |

## DevBranchNodeKind

Values: `dir | file | symlink`

## DevBranchObject

An object stored in a branch.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `branch_id` | `DevId` | Required | length 1..256 |
| `sha256` | `string` | Required | Hex SHA-256 of the object, which is also the name it is stored under. |
| `size` | `integer` | Required | Size in bytes. |
| `created` | `boolean` | Required | False when this branch already held the object. |

## DevBranchRef

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

Values: `string`

## DevBranchState

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

Values: `active | merged | abandoned`

## DevCapability

What a key may do. A request acts with the capabilities its key and its principal both hold (`effective_capabilities` on [`GET /v2/whoami`](https://mirabase.io/developers/api/identity.md#identity-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`](https://mirabase.io/developers/api/retrieval.md#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 | Required | Description |
| --- | --- | --- | --- |
| `seq` | `integer` | Required | The event's position in the Space's change feed. Numbers follow commit order with no gaps. |
| `op` | `DevChangeOp` | Required | The kind of change: `create`, `update`, `move`, `delete` or `restore`. |
| `entry_id` | `DevId` | Required | length 1..256 |
| `path` | `DevPath` | Optional | length 1..4096 |
| `version_id` | `DevId` | Optional | length 1..256 |
| `actor_principal_id` | `DevId` | Optional | length 1..256 |
| `created_at` | `string (date-time)` | Required | When the change was committed. |

## DevChangeFeed

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | `DevChange[]` | Required | The events of this page, in commit order. |
| `cursor` | `DevCursor` | Required | Pass back to continue. Sequence numbers follow commit order with no gaps. |
| `has_more` | `boolean` | Required | True when more events are ready: call again with `cursor` right away. |

## DevChangeOp

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

Values: `create | update | move | delete | restore`

## DevCheckpoint

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `DevId` | Required | length 1..256 |
| `branch_id` | `DevId` | Required | length 1..256 |
| `name` | `string` | Required | The name it was given when it was created. |
| `git` | `DevCheckpointGit` | Optional |  |
| `node_count` | `integer` | Required | Changed paths this checkpoint holds. |
| `created_by` | `DevId` | Required | length 1..256 |
| `created_at` | `string (date-time)` | Required | 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 | Required | Description |
| --- | --- | --- | --- |
| `parts` | `DevCompletedPart[]` | Required | Every part of the file, each with the `ETag` its `PUT` returned. min items 1 |
| `session_id` | `string` | Optional | 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)` | Optional | 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` | Optional | Replaces the Entry's metadata as a whole, as `metadata` does on [`PATCH /v2/entries/{id}`](https://mirabase.io/developers/api/entries.md#entries-update). Retrieval's `filter.metadata` matches it. |
| `memory_exclude` | `boolean` | Optional | `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}`](https://mirabase.io/developers/api/entries.md#entries-update). |

## DevCompletedPart

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `part_number` | `integer` | Required | The part's number, from 1. >= 1 |
| `etag` | `string` | Required | 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 | Required | Description |
| --- | --- | --- | --- |
| `url` | `string (uri)` | Required | The signed URL. Fetch it with a plain `GET`. |
| `method` | `GET` | Required | Always `GET`. |
| `expires_at` | `string (date-time)` | Required | UTC. At most 5 minutes after the request. |
| `entry_id` | `DevId` | Required | length 1..256 |
| `version_id` | `DevId` | Required | length 1..256 |
| `size_bytes` | `integer` | Required | Size of the original in bytes. |
| `media_type` | `string` | Required | The response carries this `Content-Type`, `Content-Disposition: attachment`, and `Cache-Control: private, no-store`. |
| `sha256` | `string` | Optional | Hex SHA-256 of the original bytes, when known. |

## DevContentView

Values: `text | table | recognized`

## DevContextChange

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `op` | `create \| update \| move \| restore` | Required | `create`, `update`, `move`, or `restore`. |
| `at` | `string (date-time)` | Required | UTC, microsecond precision. |

## DevContextFeedbackRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `used_citation_ids` | `string[]` | Required | `citation_id`s 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 | Required | Description |
| --- | --- | --- | --- |
| `type` | `stale \| superseded \| conflict \| agent_written` | Required | `stale`, `superseded`, `conflict`, or `agent_written`. |
| `citation_id` | `string` | Optional | On `conflict`: the item that disagrees with this one. |
| `grant_id` | `string` | Optional | On `agent_written`. |

## DevContextItem

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `entry_id` | `DevId` | Required | length 1..256 |
| `version_id` | `DevId` | Required | length 1..256 |
| `space_id` | `DevId` | Optional | length 1..256 |
| `title` | `string` | Required | Title of the Entry the passage is from. |
| `text` | `string` | Required | A passage. For `skills`, the one-line description: read the body at `path`. |
| `citation_id` | `string` | Required | Identifies this item within the pack, such as `c1`. Report the items you used by it in `feedback`. |
| `source` | `DevContextSource` | Required |  |
| `path` | `DevPath` | Optional | length 1..4096 |
| `url` | `string` | Optional | 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)` | Optional | 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)` | Optional | When the version the passage was read from was written. With `occurred_at` it tells old from new. |
| `stated_date` | `string (date)` | Optional | 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` | Optional | Where `stated_date` was read: the passage `text`, a section `heading` above it, or the `document` head. |
| `is_current_version` | `false` | Optional | Present and false when a newer version than this one is live. |
| `flags` | `DevContextFlag[]` | Optional | Absent when there are none. |
| `freshness` | `pending_index` | Optional | `pending_index` means the item came from the freshness buffer, lexically only. |
| `memory_kind` | `string` | Optional | On `memory` items. |
| `change` | `DevContextChange` | Optional | On `changes` items. |
| `memory` | `DevRoutedMemory` | Optional | 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` | Optional | Only when the request set `explain`. Not counted in `tokens_used`. |

## DevContextOmitted

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `count` | `integer` | Required | How many qualifying passages were left out. |
| `max_score` | `number \| null` | Required | The best score among them, or null when there is none to report. |

## DevContextPurpose

Values: `task | coding | research | audit`

## DevContextRendered

The pack as text, when the request set `render`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `text` | `string` | Required | 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. |
| `tokens` | `integer` | Required | `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 | Required | Description |
| --- | --- | --- | --- |
| `task` | `string` | Required | 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[]` | Optional | 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` | Optional | What the context is for (`task`, `coding`, `research`, or `audit`). Set this to skip intent inference. |
| `weights` | `DevContextWeights` | Optional | Shift the budget between sources. Omit to use the shares that go with the purpose. |
| `tier` | `DevContextTier` | Optional | `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` | Optional | 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` | Optional | Omits `memory_view` when it still matches `memory_view_etag`. length 1..128 |
| `filter` | `DevRetrievalFilter` | Optional | Narrow what is searched before ranking. Applies to every source that reads Entries; `memory_view` is not filtered. |
| `render` | `text \| compact` | Optional | `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` | Optional | 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` | Optional | `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` | Optional | 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` | Optional | 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)` | Optional | 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` | Optional | 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` | Optional | 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 | Required | Description |
| --- | --- | --- | --- |
| `pack_id` | `DevId` | Required | Names this pack. Report what you used with [`POST /v2/retrieval/context/{pack_id}/feedback`](https://mirabase.io/developers/api/retrieval.md#retrieval-contextfeedback). |
| `memory_view_etag` | `string` | Optional | Send it back as `have_memory_etag`. Absent when the memory source was off or the view did not fit. |
| `memory_view` | `DevMemoryView` | Optional | Absent when `have_memory_etag` matched. |
| `items` | `DevContextItem[]` | Required | The passages picked for the task, each citable by its `citation_id`. |
| `route` | `DevContextRoute` | Required | Which sources were used, with what budget, and why. |
| `tokens_used` | `integer` | Required | Measured over this whole response; with `render: "compact"`, over `rendered.text`. Never more than `budget_tokens`. |
| `budget_tokens` | `integer` | Required | The budget the pack was built for. |
| `tokenizer` | `cl100k_base` | Required | The tokenizer `tokens_used` and `budget_tokens` are counted with. |
| `omitted` | `DevContextOmitted` | Required | What qualified but did not fit or fell below the relevance floor. |
| `scope_used` | `DevContextScopeUsed` | Required | The Spaces the pack was drawn from. |
| `partial` | `boolean` | Required | True when a retrieval branch degraded or the scores are not calibrated relevance. |
| `pending_processing` | `DevPendingProcessing` | Optional | 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`](https://mirabase.io/developers/api/spaces.md#spaces-processing) reports when they become searchable. |
| `rendered` | `DevContextRendered` | Optional | Only when the request set `render`. |
| `explain` | `DevExplainSummary` | Optional | Only when the request set `explain`. |

## DevContextRoute

Explains the deterministic routing decision, generated after authorization.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `purpose` | `DevContextPurpose` | Required | The purpose used, inferred from the task unless you set it. |
| `tier` | `DevContextTier` | Required |  |
| `rules_fired` | `string[]` | Required | 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. |
| `sources` | `DevContextRouteSource[]` | Required | Sources that were on. A source that was off is named in `rules_fired`. |
| `unused_tokens` | `integer` | Required | Budget left empty: nothing above the relevance floor wanted it. |

## DevContextRouteSource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `source` | `DevContextSource` | Required |  |
| `budget` | `integer` | Required | Tokens this source could use, after unused budget flowed in from other sources. |
| `used` | `integer` | Required | Tokens this source actually used. |
| `picked` | `integer` | Required | Items from this source that made it into the pack. |
| `omitted` | `integer` | Required | Candidates from this source that were left out. |
| `why` | `string` | Required | Stable code, such as `filled`, `below_relevance_floor`, or `no_file_named_in_task`. |

## DevContextScopeUsed

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `space_ids` | `DevId[]` | Required | The Spaces that were searched. |

## DevContextSource

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

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

## DevContextTier

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

Values: `fast | standard | deep`

## DevContextWeights

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `memory` | `number` | Optional | Weight of `memory`: memories relevant to the task. 0..1 |
| `agent_profile` | `number` | Optional | Weight of `agent_profile`: the Agent's own profile. 0..1 |
| `skills` | `number` | Optional | Weight of `skills`: the Agent's own skills. 0..1 |
| `files` | `number` | Optional | Weight of `files`: the files the task names. 0..1 |
| `changes` | `number` | Optional | Weight of `changes`: what was written recently. 0..1 |
| `knowledge` | `number` | Optional | 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.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | `string` | Optional | The segment's type the way chat APIs write it, such as `text` or `image_url`. |
| `text` | `string` | Optional | The segment's text. A segment without it is skipped. |

## DevConversationMessage

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `role` | `string` | Required | Free text such as `user` or `assistant`, without line breaks. length 1..128 |
| `content` | `string \| DevConversationContentPart[] \| null` | Optional | The text, or a list of segments of which the text ones are joined. `null` or absent on a message without text. |
| `name` | `object` | Optional | Accepted and ignored. |
| `tool_calls` | `object` | Optional | Accepted and ignored. |
| `tool_call_id` | `object` | Optional | Accepted and ignored. |
| `function_call` | `object` | Optional | Accepted and ignored. |
| `timestamp` | `string (date-time) \| integer` | Optional | 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 | Required | Description |
| --- | --- | --- | --- |
| `text` | `string` | Required | 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 | Required | Description |
| --- | --- | --- | --- |
| `actor_id` | `DevId` | Required | 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. |
| `name` | `string` | Required | A name for the key, 1 to 256 characters, to tell keys apart in listings. length 1..256 |
| `grant_capabilities` | `DevCapability[]` | Required | Must not exceed the capabilities of the principal or of the caller. min items 1 |
| `allowed_space_ids` | `DevId[]` | Optional | Omit to leave Spaces unrestricted; an empty list is rejected. items 1..100 |
| `metadata_scope` | `DevMetadataScope` | Optional | 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`](https://mirabase.io/developers/api/entries.md#entries-list) and an Entry's content and processing, [`GET /v2/jobs/{id}`](https://mirabase.io/developers/api/jobs.md#jobs-read), 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)` | Optional | 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`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | Required | The branch's name, 1 to 255 characters. length 1..255 |
| `from` | `DevId` | Optional | The id of an active branch to copy. |
| `checkpoint_id` | `DevId` | Optional | The id of a checkpoint to copy. |
| `ttl_days` | `integer` | Optional | How many days each write pushes `expires_at` out by, 1 to 365. Omit it for the service default. 1..365 |

## DevCreateCheckpointRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | Required | A name for the checkpoint, 1 to 255 characters. length 1..255 |
| `git` | `DevCheckpointGit` | Optional |  |

## DevCreateExportRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `snapshot` | `DevSnapshotRef` | Optional | 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` | Optional | Only this directory (or file) and what is under it. |
| `format` | `tar` | Optional | The only format. |

## DevCreateForkRequest

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | Required | The new Space's name. |
| `snapshot` | `DevSnapshotRef` | Optional | Fork the files as a snapshot pinned them. Without it, the live tree. |

## DevCreateImportRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `source_entry_id` | `DevId` | Required | 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` | Optional | The directory to import into, created as needed. Default `/`. |
| `on_conflict` | `DevImportConflict` | Optional | What to do when a file is already at a member's path: `skip` (the default) or `overwrite`. default: "skip" |

## DevCreateMemoryRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `scope` | `DevMemoryScope` | Required | Whose memory to write: `project`, `agent`, or `account`. |
| `space_id` | `DevSpaceRef` | Optional | Required for `project` and `agent`; `default` names your default Space, as it does in a path. Account memory takes none. |
| `kind` | `string` | Required | `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 |
| `text` | `string` | Required | The memory itself, 1 to 2000 characters. length 1..2000 |
| `pinned` | `boolean` | Optional | Not on account memory. default: false |

## DevCreatePrincipalRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `kind` | `DevPrincipalKind` | Required | What the principal is: a person or an Agent. |
| `grant_capabilities` | `DevCapability[]` | Optional | Capabilities to grant; they must not exceed yours. Omitted means `knowledge:read` for an Agent and none for a human. |

## DevCreateSnapshotRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | Required | 1 to 255 bytes, unique in the Space, no control characters, not starting with `snp_`. length 1..255 |

## DevCreateSpaceRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | Required | The Space's name, 1 to 512 characters. length 1..512 |
| `description` | `string` | Optional | What the Space is for, 1 to 4096 characters. length 1..4096 |
| `external_id` | `string` | Optional | 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=`](https://mirabase.io/developers/api/spaces.md#spaces-list) 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 | Required | Description |
| --- | --- | --- | --- |
| `path` | `DevPath` | Required | Resolved when the upload completes, so the file may appear or change in between. |
| `size` | `integer` | Required | Size of the whole file in bytes. >= 1 |
| `media_type` | `string` | Required | The file's media type, such as `application/pdf`. |
| `checksum_sha256` | `string` | Required | Base64 SHA-256 of the whole file, checked on completion. |

## DevCreateWebhookRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | `string` | Required | `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[]` | Optional | The event kinds to deliver; defaults to all five. No repeats. items 1..5 |
| `description` | `string` | Optional | A note for people, at most 256 characters. max length 256 |
| `cursor` | `DevCursor` | Optional | 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 | Required | Description |
| --- | --- | --- | --- |
| `id` | `DevId` | Required | length 1..256 |
| `space_id` | `DevId` | Required | length 1..256 |
| `url` | `string (uri)` | Required | `https` on port 443. |
| `ops` | `DevChangeOp[]` | Required | Event kinds to send. Events of other kinds are skipped, not queued. |
| `description` | `string` | Optional | A note for people. |
| `status` | `DevWebhookStatus` | Required | `active`, or `disabled` when deliveries have stopped; `disabled_reason` says why. |
| `disabled_reason` | `DevWebhookDisabledReason` | Optional | Present when `status` is `disabled`. |
| `cursor` | `DevCursor` | Required | The change-feed position after the last batch delivered or skipped. |
| `consecutive_failures` | `integer` | Required | Failed attempts since the last success. |
| `last_success_at` | `string (date-time)` | Optional | When a batch was last delivered. |
| `last_failure_at` | `string (date-time)` | Optional | When an attempt last failed. |
| `next_attempt_at` | `string (date-time)` | Optional | When the next attempt may start. Absent when disabled. |
| `created_by_principal_id` | `DevId` | Required | length 1..256 |
| `created_at` | `string (date-time)` | Required | When the webhook was created. |
| `updated_at` | `string (date-time)` | Required | When the webhook's settings or state last changed. |
| `secret` | `string` | Optional | `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 | Required | Description |
| --- | --- | --- | --- |
| `id` | `DevId` | Required | length 1..256 |
| `space_id` | `DevId` | Required | length 1..256 |
| `scope` | `DevDreamScope` | Required |  |
| `agent_principal_id` | `DevId` | Optional | For an `agent` dream: whose private memory. |
| `status` | `DevDreamStatus` | Required | `queued`, `running`, then `succeeded` or `failed`. |
| `trigger` | `DevDreamTrigger` | Required | `manual`: someone started it. `schedule`: the Space's dreaming schedule did. |
| `started_by_principal_id` | `DevId` | Optional | For a `manual` dream. |
| `created_at` | `string (date-time)` | Required | When the dream was queued. |
| `started_at` | `string (date-time)` | Optional | When it began to run. Absent while it is queued. |
| `finished_at` | `string (date-time)` | Optional | When it ended, whether it succeeded or failed. |
| `undone_at` | `string (date-time)` | Optional | When it was undone. Absent if it never was. |
| `undone_by_principal_id` | `DevId` | Optional | length 1..256 |
| `undo_expires_at` | `string (date-time)` | Optional | 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. |
| `undoable` | `boolean` | Required | Whether an undo would be accepted right now. |
| `counts` | `DevDreamCounts` | Required |  |
| `view` | `DevDreamView` | Optional |  |
| `d4` | `DevDreamD4Report` | Optional | Present once the dream reached its comparison step. |
| `model_tokens` | `integer` | Required | Estimated model tokens spent on this dream; 0 for a member with a `read_root` in the Space. |
| `error` | `DevJobFailure` | Optional |  |

## DevDreamAction

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `seq` | `integer` | Required | Order within the dream; actions are listed by it. |
| `memory_id` | `DevId` | Required | length 1..256 |
| `entry_id` | `DevId` | Required | length 1..256 |
| `action` | `DevDreamActionKind` | Required |  |
| `reason` | `DevDreamActionReason` | Required |  |
| `state` | `DevDreamActionState` | Required |  |
| `proposal_id` | `DevId` | Optional | For `supersede` and `merge`: the approved proposal. |
| `target_memory_id` | `DevId` | Optional | For `supersede` and `merge`: the memory that stayed. Absent when you cannot see its source. |
| `created_at` | `string (date-time)` | Required | 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 | Required | Description |
| --- | --- | --- | --- |
| `dormant_marked` | `integer` | Required | Memories set aside as dormant because their quotes are gone (`quote_missing`). |
| `dormancy_candidates` | `integer` | Optional | 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` | Optional | Present with `dormancy_candidates`: those marked `dormant` with reason `unused` (Space setting `dormancy: "apply"`). |
| `superseded` | `integer` | Optional | Memories replaced by a newer one when a `supersede` proposal of this dream was approved. Present once there are any. |
| `merged` | `integer` | Optional | Memories folded into another when a `merge` proposal of this dream was approved. Present once there are any. |
| `undone` | `integer` | Optional | After an undo: actions taken back. |
| `conflict_skipped` | `integer` | Optional | After an undo: actions left alone because the memory changed since (forgotten, confirmed, re-distilled, or taken over by a later dream). |
| `checked` | `integer` | Optional | Distilled memories checked. |
| `skipped_confirmed` | `integer` | Optional | 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` | Optional | Memories whose source has a newer version still processing. |
| `skipped_no_quote` | `integer` | Optional | Memories without a quote to check. |
| `stale_skipped` | `integer` | Optional | Memories that changed between the check and the write and were left for the next dream. |
| `vetoed` | `integer` | Optional | Memories an earlier undo said not to touch again. |
| `already_dormant` | `integer` | Optional | Memories already dormant from an earlier dream. |
| `groups` | `integer` | Optional | Groups of two or more memories that say the same thing. |
| `grouped_facts` | `integer` | Optional | Distilled memories that share their statement with at least one other. |
| `remaining` | `integer` | Optional | 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 | Required | Description |
| --- | --- | --- | --- |
| `status` | `ran \| skipped` | Required | `skipped`: it asked the model nothing this run; `skipped` then says why. |
| `skipped` | `DevDreamD4SkipReason` | Optional | Set whenever D4 was skipped or stopped before running out of pairs. `remaining` counts what it left. |
| `nominated` | `integer` | Required | Pairs of memories it found worth comparing. |
| `judged` | `integer` | Required | Pairs it asked the model about. |
| `cached` | `integer` | Required | Pairs answered from a judgment already made within 30 days. |
| `proposed` | `integer` | Required | Judgments written as `open` proposals. |
| `shadow` | `integer` | Required | Judgments recorded only (the `shadow` setting). |
| `discarded` | `integer` | Required | Judgments that failed validation or that the model could not answer; they keep no text. |
| `stale_skipped` | `integer` | Required | Pairs whose memories changed before the judgment could be written. |
| `failed` | `integer` | Required | Pairs where the model call failed. |
| `remaining` | `integer` | Required | 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 | Required | Description |
| --- | --- | --- | --- |
| `id` | `DevId` | Required | length 1..256 |
| `dream_id` | `DevId` | Required | length 1..256 |
| `outcome` | `DevDreamJudgmentOutcome` | Required |  |
| `kind` | `DevMemoryProposalKind` | Optional | What it concluded. Absent for a `discarded` judgment. |
| `member_ids` | `DevId[]` | Required | The memories that were compared. |
| `layer` | `DevMemoryLayer` | Required | The memory layer of the pair: `rule`, `decision`, `event`, or `knowledge`. |
| `signals` | `string[]` | Required | Why this pair was compared: `entity`, `predicate`, `kind`. |
| `discard_reason` | `DevDreamJudgmentDiscardReason` | Optional | On a `discarded` judgment: why it was thrown out. |
| `plan` | `DevMemoryProposalPlan` | Optional |  |
| `evidence` | `DevMemoryProposalEvidence[]` | Optional | The verbatim quotes the judgment rests on. Absent on a `discarded` judgment, which keeps no quote. |
| `times` | `DevMemoryProposalTime[]` | Optional | Dates that decided which memory is newer. |
| `model` | `string` | Optional | The model that was asked. |
| `prompt_version` | `integer` | Required | Version of the prompt the judgment was made with. A new version stops older judgments from being reused. |
| `cached` | `boolean` | Required | True when this judgment reused an earlier one instead of asking the model. |
| `created_at` | `string (date-time)` | Required | 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 | Required | Description |
| --- | --- | --- | --- |
| `live_before` | `integer` | Required | Active memories in the scope before the dream. |
| `tokens_before` | `integer` | Required | Their size in tokens before the dream. |
| `live_after` | `integer` | Optional | Active memories in the scope after the dream. Present once it has finished. |
| `tokens_after` | `integer` | Optional | 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 | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | Optional | Name for a new Space. Defaults to the `external_id`. length 1..512 |
| `description` | `string` | Optional | 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 | Required | Description |
| --- | --- | --- | --- |
| `id` | `DevId` | Required | Starts with `ent_`. Stable across versions, renames, and moves. |
| `space_id` | `DevId` | Required | The Space the Entry is in. |
| `title` | `string` | Required | For a file, its name. Otherwise the title you gave, or one derived from the content. |
| `latest_version_id` | `DevId` | Required | The newest version written. Reads by path or id return it by default. |
| `current_version_id` | `DevId` | Optional | 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. |
| `metadata` | `DevMetadata` | Required | 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)` | Optional | 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` | Optional | 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` | Optional | On an Entry ingested from a URL: that URL. Use it to link a search hit or a citation back to the page. |
| `created_at` | `string (date-time)` | Required | When the Entry was first written. |
| `updated_at` | `string (date-time)` | Required | 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. |
| `file` | `DevEntryFile \| null` | Required | Null for an Entry without a path, such as a URL or a conversation. |
| `knowledge` | `DevEntryKnowledge` | Required | How far processing has progressed, and which version search is serving. |
| `memory` | `DevEntryMemory \| null` | Required | Null unless the Entry was written as a memory. |
| `memory_exclude` | `boolean` | Required | True when this Entry is kept out of memory distillation. Any Entry can have it, so it is not under `memory`. |
| `access` | `DevEntryAccess` | Required | Your role in the Entry's Space and the capabilities of the key you are using. |
| `trash` | `DevEntryTrash` | Optional | Only in the trash listing ([`GET /v2/entries?trashed=true`](https://mirabase.io/developers/api/entries.md#entries-list)). |

## DevEntryAccess

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `role` | `DevSpaceRole` | Required | Your role in the Entry's Space. |
| `capabilities` | `DevCapability[]` | Required | The capabilities this request acts with. |

## DevEntryContent

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `entry_id` | `DevId` | Required | length 1..256 |
| `version_id` | `DevId` | Required | length 1..256 |
| `view` | `DevContentView` | Required | The view this is: `text`, `table`, or `recognized`. |
| `text` | `string` | Optional | The content as text. Absent on the `table` view. |
| `table` | `DevTableContent` | Optional | The content as a table. Only on the `table` view. |

## DevEntryCopy

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `entry_id` | `DevId` | Required | length 1..256 |
| `source_version_id` | `DevId` | Required | The source version the copy started from. |
| `space_id` | `DevId` | Required | length 1..256 |
| `created_at` | `string (date-time)` | Required | When the copy was made. |

## DevEntryFile

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `path` | `DevPath` | Required | length 1..4096 |
| `size` | `integer` | Required | Size of the latest version in bytes. |
| `media_type` | `string` | Required | Media type of the latest version. |
| `etag` | `string` | Required | The latest version's ETag. Send it in `If-Match` to change the file only if nobody else has. |
| `modified_at` | `string (date-time)` | Optional | When the content last changed: when the latest version was written. The same value a `tree` listing reports. |

## DevEntryKnowledge

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `state` | `DevKnowledgeState` | Required |  |
| `indexed_version_id` | `DevId` | Optional | length 1..256 |
| `parsed` | `DevParsedSummary` | Optional | What the indexed version was parsed into. Present on [`GET /v2/entries`](https://mirabase.io/developers/api/entries.md#entries-list) and [`GET /v2/entries/{entry_id}`](https://mirabase.io/developers/api/entries.md#entries-read) once the Entry has an indexed version; absent before that, when parsing failed, and on write receipts. |
| `error` | `DevProcessingFailure` | Optional | Why processing failed: the same `error` that [`GET /v2/entries/{entry_id}/processing`](https://mirabase.io/developers/api/entries.md#entries-processing) returns. Present on [`GET /v2/entries`](https://mirabase.io/developers/api/entries.md#entries-list) and [`GET /v2/entries/{entry_id}`](https://mirabase.io/developers/api/entries.md#entries-read) when `state` is `failed`; absent otherwise and on write receipts. |

## DevEntryMemory

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `scope` | `DevMemoryScope` | Required | Whose memory it is: `project`, `agent`, or `account`. |
| `kind` | `string` | Required | The kind of memory, such as `preference` or `decision`. |
| `pinned` | `boolean` | Required | Pinned memories come first in the memory context. |
| `exclude` | `boolean` | Required | 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 | Required | Description |
| --- | --- | --- | --- |
| `entry_id` | `DevId` | Required | length 1..256 |
| `version_id` | `DevId` | Required | The latest version, which is the one being reported. |
| `status` | `DevVersionStatus` | Required | Terminal when `published`, `no_recallable_content`, `failed`, or `discarded`. |
| `knowledge_state` | `DevKnowledgeState` | Required | The same value as `knowledge.state` on the Entry. |
| `error` | `DevProcessingFailure` | Optional | Only when `status` is `failed`. |
| `stage` | `DevProcessingStage` | Required | Where the latest version is now. Search finds it from `enriching` on. |
| `progress` | `DevProcessingProgress` | Required | The main steps done so far. |
| `queue` | `DevProcessingQueue` | Optional | Only while the current step waits to start. |
| `enrichments` | `DevEnrichment[]` | Optional | Only while `stage` is `enriching`: what still runs. |
| `memory` | `DevMemoryProcessing` | Optional | 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 | Required | Description |
| --- | --- | --- | --- |
| `deleted_at` | `string (date-time)` | Required | When it went to the trash. For an Entry without a path, when its cleanup finished, moments later. |
| `path` | `DevPath` | Optional | The path a file had. [`POST /v2/entries/{id}/restore`](https://mirabase.io/developers/api/entries.md#entries-restore) puts it back there. Absent for an Entry without a path. |
| `delete_batch_id` | `DevId` | Optional | The delete that trashed a file. `restore` in `tree/operations` takes it and brings back everything that delete removed. |
| `deleted_by` | `DevId` | Optional | Who moved a file to the trash: a principal id. Absent for an Entry without a path. |
| `size` | `integer` | Optional | 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 | Required | Description |
| --- | --- | --- | --- |
| `code` | `string` | Required | 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` | Optional | 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. |
| `status` | `integer` | Required | The HTTP status, repeated in the body. |
| `message` | `string` | Required | English text for people. It may change: branch on `code`. |
| `request_id` | `string` | Required | Identifies this request in the service's logs. Quote it when you report a problem. |
| `retryable` | `boolean` | Required | False on `quota_exceeded`: retrying does not help until the quota changes. |
| `field` | `string` | Optional | First offending field on a 422. An unknown field in a request body is reported here by its name. |
| `errors` | `DevFieldError[]` | Optional | 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` | Optional | 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` | Optional | 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`](https://mirabase.io/developers/api/usage.md#usage-usage) shows how much is left. |
| `queue` | `DevBacklog` | Optional | Present on 429 `ingest_backlog`: the account's queue. [`GET /v2/queue`](https://mirabase.io/developers/api/usage.md#usage-queue) shows it at any time. |
| `current_version_id` | `DevId` | Optional | Present on 412 `precondition_failed` and 409 `proposal_conflict`: the file's latest version now. |
| `job_id` | `DevId` | Optional | Present on 409 `job_in_flight`: the work to wait for. |
| `conflicts` | `DevMergeConflict[]` | Optional | Present on 409 `merge_conflict`: every path that blocked the merge. |
| `remediation` | `DevRemediation` | Optional |  |

Every error code's status, meaning, `remediation.action`, and `Retry-After` are in [Error codes](https://mirabase.io/developers/errors.md#codes).

## DevErrorResponse

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | `DevErrorBody` | Required | 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 | Required | Description |
| --- | --- | --- | --- |
| `branch` | `DevExplainBranch` | Required |  |
| `rank` | `integer` | Required | 1-based position in that branch's own results, counting only results you can read. |

## DevExplainCandidateCount

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `branch` | `DevExplainBranch` | Required |  |
| `count` | `integer` | Required | How many candidates that branch returned that you can read. |

## DevExplainRank

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `rank` | `integer` | Required | 1-based position. |
| `score` | `number` | Required | Comparable inside one response only. |

## DevExplainRerank

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `rank` | `integer` | Required | 1-based position. |
| `score` | `number` | Required | Comparable inside one response only. |
| `pass` | `string` | Optional | Present when the score came from one clause of the task rather than the whole task: `clause_1`, `clause_2`, ... |

## DevExplainRerankSummary

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `applied` | `boolean` | Required | False when the reranker was skipped, failed or gave no scores; `score` is then not calibrated relevance. |
| `pool` | `integer` | Required | How many candidates were sent to the reranker. |
| `below_floor` | `integer` | Required | How many reranked candidates fell below the relevance floor. |

## DevExplainSummary

How the retrieval ran, when the request set `explain`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `terms` | `string[]` | Required | The terms the lexical branch searched for. |
| `candidates` | `DevExplainCandidateCount[]` | Required | Candidates per branch, counting only those you can read. Branches that returned nothing you can read are left out. |
| `fused_count` | `integer` | Required | Candidates you can read after the branches were merged. |
| `rerank` | `DevExplainRerankSummary` | Required |  |
| `clauses` | `string[]` | Optional | For a task that states several things: the clauses that were searched for separately. |

## DevFieldError

One problem in a request body.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `field` | `string` | Optional | The field, as a dotted path such as `messages.0.role`. Absent when the problem is the body as a whole. |
| `code` | `string` | Required | `validation_error`, or a more specific code where one exists. |
| `message` | `string` | Required | English text for people. |

## DevFileAttributes

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `occurred_at` | `string (date-time)` | Optional | 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` | Optional | Replaces the Entry's metadata as a whole, as `metadata` does on [`PATCH /v2/entries/{id}`](https://mirabase.io/developers/api/entries.md#entries-update). Retrieval's `filter.metadata` matches it. |
| `memory_exclude` | `boolean` | Optional | `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}`](https://mirabase.io/developers/api/entries.md#entries-update). |

## DevFileBatchDelete

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `op` | `delete` | Required | Always `delete`. |
| `path` | `DevPath` | Required | length 1..4096 |
| `if_match` | `string` | Optional | The file's `etag`: delete only if it is still current; otherwise this item returns 412 `precondition_failed`. |

## DevFileBatchItem

Values: `DevFileBatchPut | DevFileBatchDelete`

## DevFileBatchPut

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `op` | `put` | Required | Always `put`. |
| `path` | `DevPath` | Required | length 1..4096 |
| `content` | `string` | Required | UTF-8 text, at most 64 KiB. |
| `media_type` | `string` | Optional | Defaults to `text/plain`. |
| `if_match` | `string` | Optional | The file's `etag`. |
| `if_none_match` | `*` | Optional | 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)` | Optional | 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` | Optional | Replaces the Entry's metadata as a whole, as `metadata` does on [`PATCH /v2/entries/{id}`](https://mirabase.io/developers/api/entries.md#entries-update). Retrieval's `filter.metadata` matches it. |
| `memory_exclude` | `boolean` | Optional | `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}`](https://mirabase.io/developers/api/entries.md#entries-update). |

## 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 | Required | Description |
| --- | --- | --- | --- |
| `items` | `DevFileBatchItem[]` | Required | 1 to 50 writes and deletes, applied in order. items 1..50 |
| `session_id` | `string` | Optional | 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 | Required | Description |
| --- | --- | --- | --- |
| `data` | `DevFileBatchResult[]` | Required | One result per item, in the order the items were sent. |
| `queue` | `DevQueueEstimate` | Optional | How many items went on the processing queue, and roughly how long the account's queue needs. |

## DevFileBatchResult

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `path` | `DevPath` | Required | length 1..4096 |
| `status` | `integer` | Required | The HTTP status this item would have had as a request of its own, such as 200, 201, 404, or 412. |
| `write` | `DevFileWrite` | Optional |  |
| `proposal` | `DevProposalReceipt` | Optional | Instead of `write`, with status 202, when `Prefer: handling=proposal` turned this item into a proposal. |
| `deletion` | `DevFileDeletion` | Optional | On a `delete` that succeeded. |
| `branch_write` | `DevBranchFileWrite` | Optional | Instead of `write` when the request named a `branch`. |
| `branch_deletion` | `DevBranchFileDeletion` | Optional | Instead of `deletion` when the request named a `branch`. |
| `error` | `DevErrorBody` | Optional | On an item that failed: the error body a single request would have returned. |

## DevFileDeletion

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `entry_id` | `DevId` | Required | length 1..256 |
| `deleted` | `true` | Required | Always true: the file is in the trash. |

## DevFileEdit

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `old_text` | `string` | Required | Must appear exactly once, unless `replace_all` is set. min length 1 |
| `new_text` | `string` | Required | What replaces `old_text`. An empty string deletes it. |
| `replace_all` | `boolean` | Optional | 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 | Required | Description |
| --- | --- | --- | --- |
| `edits` | `DevFileEdit[]` | Required | 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 | Required | Description |
| --- | --- | --- | --- |
| `entry` | `DevEntry` | Required | The Entry as it is after the write. |
| `version_id` | `DevId` | Required | The version that now holds the content. It is the `ETag`, without the quotes. |
| `previous_version_id` | `DevId` | Optional | The version this write replaced. Absent on a new file and when no version was created. |
| `version_created` | `boolean` | Required | 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 | Required | Description |
| --- | --- | --- | --- |
| `and` | `DevFilterCondition[]` | Optional | All of these hold. 1 to 16. items 1..16 |
| `or` | `DevFilterCondition[]` | Optional | At least one of these holds. 1 to 16. items 1..16 |
| `not` | `DevFilterCondition` | Optional | This does not hold. An Entry without the key satisfies `{"not": {"key": k, "eq": v}}`. |
| `key` | `string` | Optional | The metadata key of a key condition: 1 to 64 of a-z, 0-9, `_`, `.`, `-`. |
| `eq` | `DevMetadataValue` | Optional | The Entry holds this value under the key. min length 1 |
| `in` | `DevMetadataValue[]` | Optional | The Entry holds one of these values under the key, 1 to 32 of them. items 1..32 |
| `exists` | `boolean` | Optional | `true`: the Entry has the key; `false`: it does not. |
| `gt` | `DevFilterRangeBound` | Optional | Greater than. Not together with `gte`. |
| `gte` | `DevFilterRangeBound` | Optional | Greater than or equal. Not together with `gt`. |
| `lt` | `DevFilterRangeBound` | Optional | Less than. Not together with `lte`. |
| `lte` | `DevFilterRangeBound` | Optional | 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 | Required | Description |
| --- | --- | --- | --- |
| `entry_id` | `DevId` | Required | length 1..256 |
| `version_id` | `DevId` | Required | length 1..256 |

## DevHitExplain

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `found_by` | `DevExplainBranchRank[]` | Required | The branches that returned it, with its position in each. Empty for a computed table. |
| `fused` | `DevExplainRank` | Optional | Its position and score after the branches were merged, before reranking, both computed over the candidates you can read. |
| `rerank` | `DevExplainRerank` | Optional | Its position and score from the reranker. Absent when reranking did not run or gave no score. |
| `matched_terms` | `string[]` | Optional | The query terms its text matched. Chinese is matched in two-character terms. |
| `lexical` | `strong \| covered \| partial` | Optional | How well its words covered the query: `strong` skips the relevance floor, `covered` and `partial` do not. |
| `admitted_by` | `DevExplainAdmission` | Optional | What let it past the relevance floor. Absent when no floor applied. |
| `boosts` | `DevExplainBoost[]` | Optional | Rules that moved it up. |
| `reordered_by_date` | `string` | Optional | With `newest_first`: the date it was ordered by (`occurred_at`, else `stated_date`), `YYYY-MM-DD`. |
| `computed_table` | `true` | Optional | 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.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `index` | `integer` | Required | The member's position in the archive, from 0, counting every member (`manifest.json` too). |
| `code` | `string` | Required | Why, as an error code: `invalid_path`, `reserved_path`, `path_conflict`, `unsupported_member`, `payload_too_large`, `proposal_required`… |

## DevIngestConversation

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `kind` | `conversation` | Required | Always `conversation`. |
| `session_id` | `string` | Required | 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":"…"}`](https://mirabase.io/developers/api/entries.md#entries-list) and searched together with `filter.metadata`. It names the Entry when `title` is omitted. length 1..256 |
| `messages` | `DevConversationMessage[]` | Required | The messages of this batch, in the order they were said: 1 to 1000. items 1..1000 |
| `title` | `string` | Optional | Defaults to `Conversation <session_id>`. length 1..512 |
| `metadata` | `DevMetadata` | Optional | On the Entry, like any other source. A conversation's time comes from its messages' `timestamp`. |
| `memory_exclude` | `boolean` | Optional | 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}`](https://mirabase.io/developers/api/entries.md#entries-update), which can turn it back. |
| `redact_secrets` | `boolean` | Optional | 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` | Optional | 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 | Required | Description |
| --- | --- | --- | --- |
| `entry_id` | `DevId` | Required | The Entry that was created. |
| `version_id` | `DevId` | Required | Its first version. |
| `job_id` | `DevId` | Required | The processing job. [`GET /v2/jobs/{job_id}`](https://mirabase.io/developers/api/jobs.md#jobs-read) is `succeeded` once this version is indexed; the same progress is at [`GET /v2/entries/{entry_id}/processing`](https://mirabase.io/developers/api/entries.md#entries-processing). A conversation is distilled after that: both report it as `memory.state`. |
| `knowledge` | `DevEntryKnowledge` | Required | Usually `searchable` for text of up to 64 KiB, otherwise `readable` until processing finishes. |
| `memory_status` | `candidate \| confirmed` | Optional | Only on a conversation: whether what is distilled from it takes effect or waits for review. |
| `memory` | `DevMemoryProcessing` | Optional | 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`](https://mirabase.io/developers/api/entries.md#entries-processing) for what follows. |
| `secrets_redacted` | `integer` | Optional | 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 | Required | Description |
| --- | --- | --- | --- |
| `kind` | `text` | Required | Always `text`. |
| `text` | `string` | Required | The text to store, 1 to 2,000,000 characters. length 1..2000000 |
| `title` | `string` | Optional | Defaults to the first line. length 1..512 |
| `occurred_at` | `string (date-time)` | Optional | 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` | Optional |  |
| `memory_exclude` | `boolean` | Optional | 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}`](https://mirabase.io/developers/api/entries.md#entries-update), which can turn it back. |
| `redact_secrets` | `boolean` | Optional | 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 | Required | Description |
| --- | --- | --- | --- |
| `kind` | `url` | Required | Always `url`. |
| `url` | `string (uri)` | Required | The page to fetch, `http` or `https`, at most 8192 characters. max length 8192 |
| `title` | `string` | Optional | A title for the Entry, 1 to 512 characters. length 1..512 |
| `occurred_at` | `string (date-time)` | Optional | When the page's content happened, if you know it. Retrieval's `occurred_from` / `occurred_to` go by it. |
| `metadata` | `DevMetadata` | Optional |  |
| `memory_exclude` | `boolean` | Optional | 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}`](https://mirabase.io/developers/api/entries.md#entries-update), which can turn it back. |

## DevIssuedApiKey

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `DevId` | Required | Starts with `key_`. Not the secret: the token is shown once, when the key is created or rotated. |
| `principal_id` | `DevId` | Required | The principal the key acts as. |
| `name` | `string` | Required | Your label for the key. |
| `prefix` | `string` | Required | Non-secret token prefix, for recognizing a key in a list. |
| `capabilities` | `DevCapability[]` | Required | What the key may do. Never more than its principal's capabilities. |
| `allowed_space_ids` | `DevId[]` | Optional | Absent means not narrowed to specific Spaces. |
| `metadata_scope` | `DevMetadataScope` | Optional | The metadata scope the key is limited to. Absent means not limited by metadata. |
| `expires_at` | `string (date-time)` | Optional | After this time the key stops working. Absent when it does not expire. |
| `revoked_at` | `string (date-time)` | Optional | When the key was revoked. Absent while it is live. |
| `last_used_at` | `string (date-time)` | Optional | When the key last called the API, to within a minute. Absent until its first call. |
| `created_by` | `DevId` | Required | The principal that issued it. |
| `issued_by_key_id` | `DevId` | Optional | The key that issued or rotated this one. Absent when no key was used. |
| `created_at` | `string (date-time)` | Required | When it was issued. |
| `token` | `string` | Optional | 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 | Required | Description |
| --- | --- | --- | --- |
| `id` | `DevId` | Required | length 1..256 |
| `kind` | `DevJobKind` | Required | 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. |
| `status` | `DevJobStatus` | Required | `queued`, `running`, then `succeeded`, `failed`, or `cancelled`. |
| `stage` | `string` | Required | What the job is doing, as described above. |
| `entry_id` | `DevId` | Optional | Processing jobs: the Entry being processed. |
| `version_id` | `DevId` | Optional | Processing jobs: the version being processed. |
| `error` | `DevJobFailure` | Optional | Only when `status` is `failed`. |
| `memory` | `DevMemoryProcessing` | Optional | Processing jobs of a conversation batch: where memory distillation is. `status` does not wait for it. |
| `space_id` | `DevId` | Optional | Tree jobs. |
| `progress` | `DevJobProgress` | Optional |  |
| `result` | `DevTreeJobResult` | Optional |  |
| `queue` | `DevQueueEstimate` | Optional | Imports: how many imported files went on the processing queue, and roughly how long the account's queue needs. |
| `created_at` | `string (date-time)` | Required | When the job was created. |
| `updated_at` | `string (date-time)` | Required | 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`](https://mirabase.io/developers/api/entries.md#entries-processing).

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | `string` | Required | Stable failure code. Branch on this. |
| `message` | `string` | Required | English text for people. It may change. |
| `field` | `string` | Optional | For a tree job: the request field the error is about, the same as the synchronous error would name. |

## DevJobKind

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

Values: `processing | tree | dream`

## DevJobProgress

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `done` | `integer` | Required | Units of work handled so far. |
| `total` | `integer` | Optional | Known once the job has counted its work. |

## DevJobReceipt

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `job_id` | `DevId` | Required | Poll [`GET /v2/jobs/{job_id}`](https://mirabase.io/developers/api/jobs.md#jobs-read) 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 | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | Required | 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. |
| `value` | `integer` | Required | 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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | `DevLimit[]` | Required | Every limit that applies to this account. |
| `plan` | `DevPlan` | Optional | The account's plan. On `free`, `data` already shows the plan's figures, and `tenant_model_tokens_per_month` and `tenant_model_spend_micro_usd_per_month` are listed. |

## DevLineage

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `entry_id` | `DevId` | Required | length 1..256 |
| `origin` | `DevLineageOrigin` | Required | How the Entry came to exist. |
| `data` | `DevLineageVersion[]` | Required | One page of its versions, newest first. |
| `next_cursor` | `DevCursor` | Optional | length 1..1024 |

## DevLineageOrigin

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `kind` | `DevLineageOriginKind` | Required | `created`: written directly. `copy`: copied from another Entry. `branch_merge`: first written by a branch merge. |
| `source` | `DevLineageRef` | Optional | For `copy`: the Entry and version it was copied from. |
| `branch_id` | `DevId` | Optional | For `branch_merge`: the branch, by id only. Branches are reclaimed after they close. |
| `chain` | `DevLineageRef[]` | Optional | For `copy`, when the source was itself a copy: further up, nearest first, at most 16. |
| `chain_truncated` | `true` | Optional | 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`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `visible` | `boolean` | Required | False when you cannot see the source: it has no ids and the chain stops there. |
| `entry_id` | `DevId` | Optional | length 1..256 |
| `version_id` | `DevId` | Optional | length 1..256 |
| `purged` | `true` | Optional | True when the source has been purged. Its ids are still given. |

## DevLineageVersion

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `version_id` | `DevId` | Required | length 1..256 |
| `parent_version_ids` | `DevId[]` | Required | The versions this one was written on top of. Empty on the Entry's first version. |
| `created_at` | `string (date-time)` | Required | When the version was written. |
| `author_principal_id` | `DevId` | Optional | length 1..256 |
| `kind` | `DevVersionKind` | Required |  |
| `restored_from` | `DevId` | Optional | For `revert`. |
| `proposal_id` | `DevId` | Optional | For `proposal_accept`. |
| `branch_id` | `DevId` | Optional | For `branch_merge`. |
| `message` | `string` | Optional | The version's message, when it has one. |
| `session_id` | `string` | Optional | The conversation this version came from: the `session_id` the file write carried. Look the conversation up with [`GET /v2/entries?metadata={"session_id":"…"}`](https://mirabase.io/developers/api/entries.md#entries-list). 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.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | Required | The MCP server's name. |
| `version` | `string` | Required | The service version. |
| `protocol` | `string` | Required | The MCP protocol version the server speaks. |
| `transport` | `streamable-http` | Required | Always `streamable-http`. |
| `tools` | `DevMcpTool[]` | Required | The tools this key can call on this deployment. |

## DevMcpRequest

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

Values: `object`

## DevMcpResponse

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

Values: `object`

## DevMcpTool

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `DevMcpToolName` | Required |  |
| `description` | `string` | Required | What the tool does, as it is shown to the model. |
| `inputSchema` | `object` | Required | 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`](https://mirabase.io/developers/api/memories.md#memories-list) 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 | Required | Description |
| --- | --- | --- | --- |
| `id` | `DevId` | Required | Pass it to the other memory endpoints. A distilled fact's id contains colons, so percent-encode it in a path. |
| `entry_id` | `DevId` | Optional | The Entry this memory is, or the Entry it was distilled from. Absent on account memory. |
| `space_id` | `DevId` | Optional | Absent on account memory, which belongs to no Space you can address. |
| `scope` | `DevMemoryScope` | Required | Whose memory it is: `account` (the person, across Spaces), `project` (the Space), or `agent` (one Agent's own). |
| `kind` | `string` | Required | What sort of memory, such as `preference`, `decision`, or `progress`; distilled facts have others, such as `experience`. [`GET /v2/memories?kind=`](https://mirabase.io/developers/api/memories.md#memories-list) filters on it. |
| `status` | `DevMemoryStatus` | Required | `confirmed` memories take effect in retrieval and `MEMORY.md`; a `candidate` waits for review; `rejected` and `superseded` are history. |
| `text` | `string` | Required | The memory itself, as one statement. |
| `pinned` | `boolean` | Required | Whether the memory is pinned. Only memories written as Entries can be pinned. |
| `supersedes` | `DevId` | Optional | On a correction: the memory it replaced. |
| `valid_from` | `string (date-time)` | Optional | When the fact became true, if the source said so. |
| `valid_to` | `string (date-time)` | Optional | When this stopped being the current value. With `replaced_by`, it is when the newer value took over. |
| `created_at` | `string (date-time)` | Required | When the memory was first written or distilled. |
| `updated_at` | `string (date-time)` | Required | When it last changed: a review, a correction, a pin, or a new validity. |
| `replaced_by` | `DevReplacingMemory` | Optional | Only on distilled memories from [`GET /v2/memories`](https://mirabase.io/developers/api/memories.md#memories-list) and [`GET /v2/memories/{memory_id}`](https://mirabase.io/developers/api/memories.md#memories-read), 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` | Optional | Only on deployments with memory dreaming enabled, and only on [`GET /v2/memories`](https://mirabase.io/developers/api/memories.md#memories-list) and [`GET /v2/memories/{memory_id}`](https://mirabase.io/developers/api/memories.md#memories-read): 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` | Optional | Only on deployments with memory dreaming enabled, and only on distilled memories from [`GET /v2/memories`](https://mirabase.io/developers/api/memories.md#memories-list) and [`GET /v2/memories/{memory_id}`](https://mirabase.io/developers/api/memories.md#memories-read): 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[]` | Optional | With `group_id`: the members of the group you can see, smallest id first, this one included. |
| `pending_proposals` | `DevId[]` | Optional | Only on deployments with memory dreaming enabled, on [`GET /v2/memories`](https://mirabase.io/developers/api/memories.md#memories-list) and [`GET /v2/memories/{memory_id}`](https://mirabase.io/developers/api/memories.md#memories-read): 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 | Required | Description |
| --- | --- | --- | --- |
| `reason` | `DevMemoryDormancyReason` | Required |  |
| `dream_id` | `DevId` | Required | 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}`](https://mirabase.io/developers/api/memories.md#memories-read), 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}`](https://mirabase.io/developers/api/memories.md#memories-read), 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 | Required | Description |
| --- | --- | --- | --- |
| `memory_id` | `DevId` | Required | length 1..256 |
| `status` | `forgotten` | Required | Always `forgotten`. |
| `remaining_sources` | `DevForgottenSource[]` | Optional | 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 | Required | Description |
| --- | --- | --- | --- |
| `state` | `pending \| ready \| skipped \| failed` | Required | `pending` until distillation has finished. Then `ready`: what it wrote is in [`GET /v2/memories`](https://mirabase.io/developers/api/memories.md#memories-list). `failed` when distillation gives up. `skipped` when it does not run for this version; `reason` says why. |
| `count` | `integer` | Optional | Only when `state` is `ready`: how many memories the batch wrote, candidates included. 0 means it found nothing to keep. |
| `reason` | `DevMemoryProcessingReason` | Optional | 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` | Optional | 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}`](https://mirabase.io/developers/api/entries.md#entries-update). `write_memories_directly`: this deployment does not distill, so write the memories yourself with [`POST /v2/memories`](https://mirabase.io/developers/api/memories.md#memories-create). `review_usage`: see [`GET /v2/usage`](https://mirabase.io/developers/api/usage.md#usage-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 | Required | Description |
| --- | --- | --- | --- |
| `id` | `DevId` | Required | length 1..256 |
| `space_id` | `DevId` | Required | length 1..256 |
| `scope` | `DevDreamScope` | Required |  |
| `agent_principal_id` | `DevId` | Optional | For an `agent` proposal: whose private memory. |
| `dream_id` | `DevId` | Required | The dream that proposed it. |
| `kind` | `DevMemoryProposalKind` | Required | What it suggests: `merge`, `supersede`, `conflict`, or `promote`. |
| `member_ids` | `DevId[]` | Required | The memories it is about, sorted. |
| `proposed_text` | `string` | Optional | The statement it proposes. Absent for now; always absent for `conflict`. |
| `evidence` | `DevMemoryProposalEvidence[]` | Optional | The verbatim quotes that back the proposal. |
| `plan` | `DevMemoryProposalPlan` | Optional | What `approve` would do. Absent for `conflict`, which has nothing to apply. |
| `layer` | `DevMemoryLayer` | Optional | The memory layer of its members: `rule`, `decision`, `event`, or `knowledge`. |
| `times` | `DevMemoryProposalTime[]` | Optional | Dates that decided which memory is newer. |
| `status` | `DevMemoryProposalStatus` | Required | `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` | Optional | Who approved or rejected it. |
| `reviewed_at` | `string (date-time)` | Optional | When it was approved or rejected. |
| `closed_at` | `string (date-time)` | Optional | When it stopped being open, for any reason. |
| `created_at` | `string (date-time)` | Required | When the dream wrote the proposal. |

## DevMemoryProposalEvidence

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `memory_id` | `DevId` | Required | length 1..256 |
| `entry_id` | `DevId` | Required | length 1..256 |
| `version_id` | `DevId` | Required | length 1..256 |
| `quote` | `string` | Required | The quote, word for word. |

## DevMemoryProposalKind

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

Values: `merge | supersede | conflict | promote`

## DevMemoryProposalPlan

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `keep` | `DevId` | Required | The memory that stays. |
| `close` | `DevId[]` | Required | The memories that approving closes: the ones `keep` replaces or absorbs. |

## DevMemoryProposalStatus

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

Values: `open | approved | rejected | stale | withdrawn`

## DevMemoryProposalTime

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `memory_id` | `DevId` | Required | length 1..256 |
| `entry_id` | `DevId` | Required | length 1..256 |
| `date` | `string` | Required | The date, as the source states it or as the source itself is dated. |
| `quote` | `string` | Required | The words in the source that the date was read from. |

## DevMemoryProvenance

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `memory_id` | `DevId` | Required | length 1..256 |
| `sources` | `DevMemoryProvenanceSource[]` | Required | The Entry versions this memory rests on. All of them come back in one response: the list is not paginated. |

## DevMemoryProvenanceSource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `entry_id` | `DevId` | Required | length 1..256 |
| `version_id` | `DevId` | Required | length 1..256 |
| `quote` | `string` | Optional | The words in that version this memory rests on. |
| `merged_from` | `DevId` | Optional | 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 | Required | Description |
| --- | --- | --- | --- |
| `source` | `account \| agent \| project \| usage` | Required | `account`, `agent`, `project`, or `usage`. |
| `kind` | `string` | Required | The kind of memory, such as `preference` or `decision`. |
| `text` | `string` | Required | The memory itself. |
| `confidence` | `number` | Required | From 0 to 1: the confidence recorded with this memory. 0..1 |
| `valid_until` | `string (date-time)` | Optional | After this moment the memory is no longer served. Absent when it does not expire. |
| `source_ref` | `DevMemorySourceRef` | Required | 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 | Required | Description |
| --- | --- | --- | --- |
| `space_id` | `DevId` | Required | length 1..256 |
| `memory_dreaming` | `DevMemoryDreamingMode` | Required | Whether dreams run: `propose` (the default) or `off`. |
| `dormancy` | `DevMemoryDormancyMode` | Required | What a dream does with unused memories: `report` (the default) or `apply`. |
| `d4` | `DevMemoryD4Mode` | Required | Whether a dream asks a model to compare memories: `off` (the default), `shadow`, or `propose`. |
| `d4_available` | `boolean` | Optional | 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)` | Optional | When the settings were last changed. Absent while nobody has configured the Space. |
| `updated_by_principal_id` | `DevId` | Optional | length 1..256 |

## DevMemorySource

One member of a group of distilled memories.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `memory_id` | `DevId` | Required | length 1..256 |
| `entry_id` | `DevId` | Required | length 1..256 |

## DevMemorySourceRef

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `memory_id` | `DevId` | Optional | length 1..256 |
| `candidate_id` | `DevId` | Optional | length 1..256 |
| `claim_id` | `DevId` | Optional | length 1..256 |
| `entry_id` | `DevId` | Optional | length 1..256 |
| `version_id` | `DevId` | Optional | length 1..256 |
| `space_id` | `DevId` | Optional | length 1..256 |
| `recorded_at` | `string (date-time)` | Required | When the memory was recorded. |
| `valid_from` | `string (date-time)` | Required | 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.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `memory_id` | `DevId` | Required | length 1..256 |
| `status` | `undone` | Required | Always `undone`. |
| `restored` | `DevMemory[]` | Required | The memories that came back: what the undone memory had replaced. Empty when it replaced nothing. |

## DevMemoryView

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `sections` | `DevMemorySection[]` | Required | 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 | Required | Description |
| --- | --- | --- | --- |
| `path` | `DevPath` | Required | length 1..4096 |
| `base_version_id` | `DevId \| null` | Required | The main version the branch started from at this path. Null when the file did not exist then. |
| `main_version_id` | `DevId \| null` | Required | Main's latest version at this path now. Null when the file no longer exists. |
| `branch_version_id` | `string \| null` | Required | 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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `path` | `DevPath` | Required | length 1..4096 |
| `entry_id` | `DevId` | Required | length 1..256 |
| `proposal_id` | `DevId` | Required | length 1..256 |

## DevMergeRequest

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `message` | `string` | Required | 1 to 1000 characters. Recorded as the message of every version the merge writes to main. length 1..1000 |
| `paths` | `DevPath[]` | Optional | 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` | Optional | 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 | Required | Description |
| --- | --- | --- | --- |
| `branch_id` | `DevId` | Required | length 1..256 |
| `state` | `active \| merged` | Required | The branch's state after the merge: `merged`, or still `active` when only `paths` were merged. |
| `merged` | `DevPath[]` | Required | Paths written to main. `merged_items` has the versions. |
| `skipped` | `DevPath[]` | Required | Paths left out. `skipped_items` has the reasons. |
| `merged_items` | `DevMergedPath[]` | Required | One item per path written to main: what was done and the resulting version. |
| `skipped_items` | `DevMergeSkipped[]` | Required | One item per path left out, with the reason. |
| `proposed_items` | `DevMergeProposed[]` | Optional | 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 | Required | Description |
| --- | --- | --- | --- |
| `path` | `DevPath` | Required | length 1..4096 |
| `reason` | `DevMergeSkipReason` | Required | `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 | Required | Description |
| --- | --- | --- | --- |
| `path` | `DevPath` | Required | length 1..4096 |
| `op` | `DevMergedOp` | Required | What the merge did on main: `create`, `update`, `delete`, or `mkdir`. |
| `entry_id` | `DevId` | Optional | length 1..256 |
| `version_id` | `DevId` | Optional | 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 | Required | Description |
| --- | --- | --- | --- |
| `any` | `DevMetadataValue[]` | Required | 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 | Required | Description |
| --- | --- | --- | --- |
| `passages` | `integer` | Required | Passages the content was split into for retrieval. |
| `characters` | `integer` | Required | Characters of text extracted, including text read from images and transcribed from audio. |
| `duration_ms` | `integer` | Optional | Audio and video: length of the recording in milliseconds. |
| `speakers` | `integer` | Optional | Audio and video: the number of distinct speakers the transcript tells apart. Absent when it does not tell them apart. |
| `sheets` | `integer` | Optional | Spreadsheets and CSV: number of sheets. |
| `rows` | `integer` | Optional | Spreadsheets and CSV: rows across all sheets. |
| `columns` | `integer` | Optional | 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 | Required | Description |
| --- | --- | --- | --- |
| `entries` | `integer` | Required | 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`](https://mirabase.io/developers/api/usage.md#usage-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 | Required | Description |
| --- | --- | --- | --- |
| `id` | `DevId` | Required | Starts with `prn_` for principals created through the API. |
| `kind` | `DevPrincipalKind` | Required | `human` for a person, `agent` for an Agent. |
| `roles` | `string[]` | Required | Directory roles, such as `tenant_admin`. |
| `capabilities` | `DevCapability[]` | Required | What keys issued to this principal can be granted at most. |
| `created_at` | `string (date-time)` | Required | 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`](https://mirabase.io/developers/api/uploads.md#uploads-complete) returns when the stored object's media type differs from the one the upload declared.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | `string` | Required | Stable failure code. Branch on this. |
| `message` | `string` | Required | English text for people. It may change. |

## DevProcessingProgress

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `done` | `integer` | Required |  |
| `total` | `integer` | Required |  |

## DevProcessingQueue

Why the current step has not started yet.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `position` | `integer` | Required | 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_seconds` | `integer` | Required | Seconds since the step was queued. |
| `waiting_for` | `capacity \| retry \| paused` | Required | `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 | Required | Description |
| --- | --- | --- | --- |
| `id` | `DevId` | Required | length 1..256 |
| `space_id` | `DevId` | Required | length 1..256 |
| `entry_id` | `DevId` | Required | length 1..256 |
| `path` | `DevPath` | Optional | Where the file is now. Absent while it is in the trash. |
| `status` | `DevProposalStatus` | Required | `open` until a reviewer approves or rejects it, or its author withdraws it. |
| `base_version_id` | `DevId` | Required | length 1..256 |
| `proposed_version_id` | `DevId` | Required | length 1..256 |
| `approved_version_id` | `DevId` | Optional | The version approval wrote. |
| `author_principal_id` | `DevId` | Optional | length 1..256 |
| `reviewed_by_principal_id` | `DevId` | Optional | Who approved or rejected it. |
| `size_bytes` | `integer` | Required | Size of the proposed content in bytes. |
| `media_type` | `string` | Required | Media type of the proposed content. |
| `sha256` | `string` | Optional | Hex SHA-256 of the proposed bytes. |
| `created_at` | `string (date-time)` | Required | When the proposal was made. |
| `reviewed_at` | `string (date-time)` | Optional | When it was approved or rejected. |
| `closed_at` | `string (date-time)` | Optional | 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}`](https://mirabase.io/developers/api/proposals.md#proposals-read) to learn the outcome.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `applied` | `false` | Required | Always false: the write became a proposal and the file did not change. |
| `proposal_id` | `DevId` | Required | length 1..256 |
| `entry_id` | `DevId` | Required | length 1..256 |
| `base_version_id` | `DevId` | Required | The file's latest version when the proposal was made. Approval needs it to still be the latest. |
| `proposed_version_id` | `DevId` | Required | 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 | Required | Description |
| --- | --- | --- | --- |
| `purged` | `DevPurgedEntry[]` | Required | The Entries erased by this call, at most 100. |
| `has_more` | `boolean` | Required | True when the trash still holds more: call again. |

## DevPurgeTrashRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `delete_batch_id` | `DevId` | Optional | 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.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `entry_id` | `DevId` | Required | length 1..256 |
| `job_id` | `DevId` | Required | length 1..256 |

## DevQueueEstimate

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `queued_items` | `integer` | Required | Items that wrote a new version and so were queued for processing. |
| `eta_seconds` | `integer` | Optional | Estimated seconds until your account's due jobs are done (see [`GET /v2/queue`](https://mirabase.io/developers/api/usage.md#usage-queue)). Absent when it cannot be estimated, and for a key limited to some Spaces or to metadata. |
| `paused` | `boolean` | Optional | 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.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `action` | `string` | Required | Stable action name, such as `check_api_key` after `unauthorized`. |
| `doc_url` | `string (uri)` | Optional | Where the action is documented. |

## DevReplacingMemory

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `DevId` | Required | Contains `:`. Percent-encode it in a path. |
| `text` | `string` | Required | The statement of the current value. |

## DevRequestClient

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

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

## DevRequestLog

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `DevId` | Required | length 1..256 |
| `created_at` | `string (date-time)` | Required | When the request arrived. |
| `method` | `GET \| HEAD \| POST \| PUT \| PATCH \| DELETE \| OPTIONS` | Required |  |
| `route` | `string` | Required | The method and route template, such as `GET /v2/spaces/:space_id/files`. Ids and paths in the URL are not kept. |
| `status` | `integer` | Required |  |
| `error_code` | `string` | Optional | 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_ms` | `integer` | Required | From arrival to the response; for a streamed answer, to the end of the stream. |
| `auth` | `api_key \| console \| token` | Required | How the request authenticated: an API key, the console session, or a sign-in token. |
| `principal_id` | `DevId` | Required | length 1..256 |
| `key_id` | `DevId` | Optional | The key that made the request. |
| `key_name` | `string` | Optional | The key's name and prefix as they are now. Absent once the key is deleted. |
| `key_prefix` | `string` | Optional |  |
| `space_id` | `DevId` | Optional | The Space in the path, when there is one. |
| `request_id` | `string` | Required | The same as the `X-Request-Id` response header. |
| `trace_id` | `string` | Optional | 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}`](https://mirabase.io/developers/api/request-logs.md#requestlogs-trace). |
| `client` | `DevRequestClient` | Required |  |
| `client_version` | `string` | Optional | The client's version, when its `User-Agent` has one. |

## DevRequestLogPage

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | `DevRequestLog[]` | Required | The items on this page. |
| `next_cursor` | `DevCursor` | Optional | Pass it as `cursor` to get the next page. Absent on the last page. |
| `retention_days` | `integer` | Required | 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 | Required | Description |
| --- | --- | --- | --- |
| `reference_time` | `string (date-time)` | Optional | 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` | Optional | 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 | Required | Description |
| --- | --- | --- | --- |
| `explain` | `boolean` | Optional | 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 | Required | Description |
| --- | --- | --- | --- |
| `metadata` | `object` | Optional | 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[]` | Optional | 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)` | Optional | 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)` | Optional | Keep Entries that happened at or before this instant. A value earlier than `occurred_from` returns 422. |
| `where` | `DevFilterCondition` | Optional | 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 | Required | Description |
| --- | --- | --- | --- |
| `profile` | `string` | Optional | 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` | Optional | `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` | Optional | 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` | Optional | 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 | Required | Description |
| --- | --- | --- | --- |
| `id` | `DevId` | Required | length 1..256 |
| `kind` | `search \| context \| answer` | Required |  |
| `created_at` | `string (date-time)` | Required |  |
| `principal_id` | `DevId` | Optional | length 1..256 |
| `query` | `string` | Optional | Search only: the query as it was sent. |
| `citations` | `DevTraceCitation[]` | Required | The Entries and versions the call returned or gave the model. |
| `summary` | `DevTraceSummary` | Required |  |

## DevRevertRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `version_id` | `DevId` | Required | The id of the version to revert to; its content becomes the new latest version. |

## DevReviewMemoryRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `decision` | `confirm \| reject` | Required | `confirm` makes the candidate a memory; `reject` turns it down. |

## DevRollbackRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `checkpoint_id` | `DevId` | Required | The id of the checkpoint to roll back to. |

## DevRotatedWebhookSecret

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `webhook_id` | `DevId` | Required | length 1..256 |
| `secret` | `string` | Optional | 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}`](https://mirabase.io/developers/api/memories.md#memories-read), 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 | Required | Description |
| --- | --- | --- | --- |
| `id` | `DevId` | Required | Contains `:`. Percent-encode it in a path. |
| `kind` | `string` | Required | The kind of memory, such as `preference` or `event`. |
| `text` | `string` | Required | The memory's statement. |
| `valid_from` | `string (date-time)` | Optional | When this value took effect, when that is known. |
| `valid_to` | `string (date-time)` | Optional | When this stopped being the current value: the moment the next value took effect. Absent while current. |
| `replaced_by` | `DevReplacingMemory` | Optional | 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 | Required | Description |
| --- | --- | --- | --- |
| `entry_id` | `DevId` | Required | The Entry the passage is from. |
| `version_id` | `DevId` | Required | The version the passage was read from. |
| `space_id` | `DevId` | Optional | Absent on account memory, which belongs to no Space you can address. |
| `title` | `string` | Required | The Entry's title; for a file, its name. |
| `text` | `string` | Required | The matching passage. |
| `score` | `number` | Required | Comparable inside one response only. |
| `citation_id` | `string` | Required | `c1`, `c2`, ... in the order of this response. |
| `source_type` | `string` | Required | What kind of source it is: `file`, `note`, `web`, `agent-conversation`, or a memory type. |
| `path` | `DevPath` | Optional | The file's path. Absent for an Entry without one. |
| `url` | `string` | Optional | 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)` | Optional | 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)` | Optional | When the version the passage was read from was written. With `occurred_at` it tells old from new. |
| `stated_date` | `string (date)` | Optional | 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` | Optional | 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` | Optional | `pending_index` means the match came from the freshness buffer, lexically only. |
| `memory` | `DevRoutedMemory` | Optional | 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` | Optional | 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 | Required | Description |
| --- | --- | --- | --- |
| `query` | `string` | Required | What to look for, in natural language or keywords. length 1..1000 |
| `space_ids` | `DevSpaceRef[]` | Optional | 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` | Optional | 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[]` | Optional | `["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` | Optional | How many hits to return at most. This is a total, unlike a list's page size. 1..50, default: 20 |
| `filter` | `DevRetrievalFilter` | Optional | Narrow what is searched before ranking. Combines with `path` and `space_ids`: all of them must hold. |
| `tier` | `DevContextTier` | Optional | 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[]` | Optional | 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` | Optional | 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` | Optional | `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` | Optional | 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` | Optional | 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)` | Optional | 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` | Optional | 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` | Optional | 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 | Required | Description |
| --- | --- | --- | --- |
| `data` | `DevSearchHit[]` | Required | The hits, best first. |
| `trace_id` | `DevId` | Required | length 1..256 |
| `partial` | `boolean` | Required | True when a retrieval branch degraded or the scores are not calibrated relevance. |
| `explain` | `DevExplainSummary` | Optional | Only when the request set `explain`. |
| `pending_processing` | `DevPendingProcessing` | Optional | 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`](https://mirabase.io/developers/api/spaces.md#spaces-processing) reports when they become searchable. |

## DevSetSpaceMemberRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `role` | `editor \| viewer` | Required | `editor` can write; `viewer` can only read. Ownership cannot be granted here. |
| `write_mode` | `DevWriteMode` | Optional | Defaults to `proposal` for a new member; otherwise the current value stays. |
| `write_root` | `string \| null` | Optional | 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` | Optional | 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 | Required | Description |
| --- | --- | --- | --- |
| `id` | `DevId` | Required | length 1..256 |
| `space_id` | `DevId` | Required | length 1..256 |
| `name` | `string` | Required | The snapshot's name. `snapshot=` takes it in place of the id. |
| `file_count` | `integer` | Required | 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_cursor` | `DevCursor` | Required | 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_id` | `DevId` | Required | length 1..256 |
| `created_at` | `string (date-time)` | Required | 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 | Required | Description |
| --- | --- | --- | --- |
| `id` | `DevId` | Required | 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. |
| `name` | `string` | Required | The Space's name. |
| `description` | `string` | Optional | A note about what the Space is for. |
| `external_id` | `string` | Optional | 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=`](https://mirabase.io/developers/api/spaces.md#spaces-list) finds the Space by it. |
| `is_default` | `boolean` | Required | True on the Space that `default` resolves to for you. |
| `access_role` | `DevSpaceRole` | Required | Your role in this Space: `owner`, `editor`, or `viewer`. |
| `read_root` | `DevPath` | Optional | 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` | Optional | Your own write root in this Space, as its path at the moment of reading. Absent when your writes are not limited. |
| `created_at` | `string (date-time)` | Required | When the Space was created. |
| `updated_at` | `string (date-time)` | Required | 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 | Required | Description |
| --- | --- | --- | --- |
| `since` | `string (date-time)` | Required | The start of the period. |
| `truncated` | `boolean` | Required | True when the period held more than the 1000 changes this looks back over: older ones are not counted. |
| `data` | `DevActivityActor[]` | Required | One item per principal that changed something. |

## DevSpaceDeletion

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `space_id` | `DevId` | Required | The Space that was deleted. |
| `deleted` | `true` | Required | Always true: the Space is gone from every read. |
| `entries` | `integer` | Required | How many Entries the Space held, trashed ones included. They are being erased. |

## DevSpaceMember

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `principal_id` | `DevId` | Required | length 1..256 |
| `role` | `DevSpaceRole` | Required | `owner`, `editor`, or `viewer`. |
| `write_mode` | `DevWriteMode` | Required |  |
| `write_root` | `DevPath` | Optional | 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` | Optional | 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 | Required | Description |
| --- | --- | --- | --- |
| `pending` | `integer` | Required | Entries whose memory extraction is queued or running. They are already counted as searchable or processing. |
| `eta_seconds` | `integer` | Optional | Upper bound in seconds for the pending extractions, from the account's hourly memory-extraction rate. Absent when nothing is pending. |
| `files` | `index_only \| distill` | Required | 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 | Required | Description |
| --- | --- | --- | --- |
| `space_id` | `DevId` | Required | length 1..256 |
| `counts` | `DevSpaceProcessingCounts` | Required |  |
| `stages` | `DevSpaceProcessingStages` | Required |  |
| `searchable_per_minute` | `number` | Optional | Entries per minute that became searchable over the last five minutes. Absent when none did. |
| `eta_seconds` | `integer` | Optional | 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` | Optional | Seconds the longest-waiting due step in this Space has been queued. Absent when nothing waits. |
| `waiting_for_capacity` | `boolean` | Required | 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` | Optional | 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. |
| `memory` | `DevSpaceMemoryProgress` | Required | Memory extraction, reported apart: an Entry waiting only for it is searchable, not processing. |
| `as_of` | `string (date-time)` | Required | When the numbers were read. |

## DevSpaceProcessingCounts

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `queued` | `integer` | Required | Stored; no step has started. |
| `processing` | `integer` | Required | Text extraction or indexing has started. |
| `searchable` | `integer` | Required | Search finds them; enrichment (relations, classification, summary, memories) is still running. |
| `ready` | `integer` | Required | Every step has finished. |
| `failed` | `integer` | Required | Processing gave up. [`GET /v2/entries/{id}/processing`](https://mirabase.io/developers/api/entries.md#entries-processing) says why. |

## DevSpaceProcessingStages

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `queued` | `integer` | Required |  |
| `extracting` | `integer` | Required |  |
| `indexing` | `integer` | Required |  |
| `enriching` | `integer` | Required |  |

## 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 | Required | Description |
| --- | --- | --- | --- |
| `metric` | `writes \| storage_bytes \| model_tokens \| model_spend_micro_usd` | Required | `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_start` | `string (date-time)` | Required | The start of the window `used` counts from. The Unix epoch for a cumulative metric. |
| `used` | `integer` | Required | How much of the metric has been used in the window. |
| `limit` | `integer` | Optional | The quota. Absent when the metric is not limited. |
| `space_id` | `DevId` | Required | length 1..256 |

## DevStartDreamRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `scope` | `DevDreamScope` | Optional | 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.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `columns` | `string[]` | Required | Column headers, in order. |
| `rows` | `string[][]` | Required | At most the first 200 rows, each a list of cell texts in column order. |
| `row_count` | `integer` | Required | Rows in the whole sheet, which can be more than `rows` holds. |

## DevTraceCandidates

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `lexical` | `integer` | Optional |  |
| `dense` | `integer` | Optional |  |
| `dense_document` | `integer` | Optional |  |
| `memory` | `integer` | Optional |  |
| `relation` | `integer` | Optional |  |

## DevTraceCitation

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `entry_id` | `DevId` | Required | length 1..256 |
| `version_id` | `DevId` | Required | length 1..256 |
| `citation_id` | `string` | Optional |  |
| `source` | `string` | Optional |  |

## DevTraceSource

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `source` | `string` | Required |  |
| `budget` | `integer` | Optional |  |
| `used` | `integer` | Optional |  |
| `picked` | `integer` | Optional |  |
| `omitted` | `integer` | Optional |  |
| `why` | `string` | Optional |  |

## DevTraceStage

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `stage` | `string` | Required | The stage, such as `embed`, `lexical`, `dense`, `rerank` or `authorize`. |
| `status` | `succeeded \| failed \| cancelled \| skipped` | Required |  |
| `duration_ms` | `integer` | Optional | 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 | Required | Description |
| --- | --- | --- | --- |
| `candidates` | `DevTraceCandidates` | Optional | 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` | Optional |  |
| `ranked_count` | `integer` | Optional |  |
| `final_count` | `integer` | Optional |  |
| `rerank_applied` | `boolean` | Optional |  |
| `partial` | `boolean` | Optional |  |
| `duration_ms` | `integer` | Optional |  |
| `stages` | `DevTraceStage[]` | Optional | Search: time spent in each stage. |
| `purpose` | `string` | Optional | Context and answer: the routing decision, as `route` on the response. |
| `tier` | `string` | Optional |  |
| `rules_fired` | `string[]` | Optional |  |
| `sources` | `DevTraceSource[]` | Optional |  |
| `tokens_used` | `integer` | Optional |  |
| `budget_tokens` | `integer` | Optional |  |

## DevTreeChmod

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `op` | `chmod` | Required | Always `chmod`. |
| `path` | `DevPath` | Required | length 1..4096 |
| `mode` | `644 \| 755` | Required | `644`, or `755` for an executable file. |

## DevTreeCopied

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `path` | `DevPath` | Required | Where the copy is. |
| `entry_id` | `DevId` | Required | length 1..256 |
| `source_entry_id` | `DevId` | Required | length 1..256 |

## DevTreeCopy

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `op` | `copy` | Required | Always `copy`. |
| `from` | `DevPath` | Required | length 1..4096 |
| `to` | `DevPath` | Required | length 1..4096 |

## DevTreeDelete

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `op` | `delete` | Required | Always `delete`. |
| `path` | `DevPath` | Required | length 1..4096 |
| `recursive` | `boolean` | Optional | Required for a non-empty directory; otherwise returns 409 `directory_not_empty`. default: false |

## DevTreeJobResult

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `delete_batch_id` | `DevId` | Optional | 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` | Optional | Files copied so far. |
| `restored` | `integer` | Optional | Nodes restored. |
| `merged` | `integer` | Optional | A merge: paths written to main. |
| `proposed` | `integer` | Optional | A merge: files proposed instead of written. |
| `skipped` | `integer` | Optional | A merge, an export, or an import: items left out. |
| `conflicts` | `DevMergeConflict[]` | Optional | A merge that failed with `merge_conflict`: the first 100 conflicting paths. max items 100 |
| `files` | `integer` | Optional | An export: files in the archive. `skipped` counts files with no bytes to export. |
| `bytes` | `integer` | Optional | An export: total bytes of the files in the archive. |
| `archive` | `DevArchive` | Optional | An export that succeeded: the archive. Download it with [`GET /v2/jobs/{job_id}/content-url`](https://mirabase.io/developers/api/transfers.md#transfers-archiveurl). |
| `created` | `integer` | Optional | 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` | Optional | An import: files that already existed and got a new version. |
| `failed` | `integer` | Optional | An import: members that could not be written. |
| `failures` | `DevImportFailure[]` | Optional | 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.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `op` | `mkdir` | Required | Always `mkdir`. |
| `path` | `DevPath` | Required | length 1..4096 |

## DevTreeMove

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `op` | `move` | Required | Always `move`. |
| `from` | `DevPath` | Required | length 1..4096 |
| `to` | `DevPath` | Required | length 1..4096 |

## DevTreeNode

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `path` | `DevPath` | Required | length 1..4096 |
| `name` | `string` | Required | The last segment of `path`, as it was written. |
| `kind` | `DevTreeNodeKind` | Required | `dir` or `file`; a branch listing also has `symlink`. |
| `entry_id` | `DevId` | Optional | length 1..256 |
| `version_id` | `DevId` | Optional | On files: the latest version. Through a `snapshot`, the version the snapshot pinned. Not on a branch listing. |
| `size_bytes` | `integer` | Optional | On files. On a branch listing, only on the paths the branch changed. |
| `etag` | `string` | Optional | 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` | Optional | On files a branch changed, and on files listed through a `snapshot` when known. |
| `media_type` | `string` | Optional | On files. On a branch listing, only on the files the branch changed. |
| `modified_at` | `string (date-time)` | Optional | 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` | Optional | `644` or `755`. On paths a branch changed. |
| `link_target` | `string` | Optional | On a symlink. |
| `updated_at` | `string (date-time)` | Required | 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 | Required | Description |
| --- | --- | --- | --- |
| `operations` | `DevTreeOperation[]` | Required | 1 to 200 operations, applied in order. items 1..200 |

## DevTreeOperationsResponse

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `delete_batch_id` | `DevId` | Optional | Present when the request deleted anything; restores the batch as one unit. |
| `copies` | `DevTreeCopied[]` | Optional | 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 | Required | Description |
| --- | --- | --- | --- |
| `data` | `DevTreeNode[]` | Required | The items on this page. |
| `next_cursor` | `DevCursor` | Optional | Pass it as `cursor` to get the next page. Absent on the last page. |
| `changes_cursor` | `DevCursor` | Required | 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 | Required | Description |
| --- | --- | --- | --- |
| `op` | `restore` | Required | Always `restore`. |
| `path` | `DevPath` | Optional | length 1..4096 |
| `delete_batch_id` | `DevId` | Optional | length 1..256 |

## DevTreeSymlink

Valid only with `branch`, and returns 422 without it: main has no symlinks. Merging skips them.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `op` | `symlink` | Required | Always `symlink`. |
| `path` | `DevPath` | Required | length 1..4096 |
| `target` | `string` | Required | Where the link points, 1 to 4096 characters. length 1..4096 |

## DevUpdateBranchRequest

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | Optional | A new name, 1 to 255 characters. length 1..255 |
| `ttl_days` | `integer` | Optional | 1 to 365. Setting it also renews the branch: `expires_at` becomes now plus that many days. 1..365 |

## DevUpdateEntryRequest

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `title` | `string` | Optional | A new title, 1 to 512 characters. Not supported on a file: rename it with `tree/operations`. length 1..512 |
| `metadata` | `DevMetadata` | Optional | 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` | Optional | 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` | Optional | `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` | Optional | 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.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `pinned` | `boolean` | Optional | Only on a memory written as an Entry. Pinning changes what a Space starts with, so a person must own the Space. |
| `valid_to` | `string (date-time)` | Optional | Closes a distilled fact or an account memory. A memory written as an Entry has no validity window: forget or correct it. |

## DevUpdateMemorySettingsRequest

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `memory_dreaming` | `DevMemoryDreamingMode` | Optional | `auto` returns 422 until it is available. |
| `dormancy` | `DevMemoryDormancyMode` | Optional | What a dream does with unused memories: `report` (the default) or `apply`. |
| `d4` | `DevMemoryD4Mode` | Optional | Whether a dream asks a model to compare memories: `off` (the default), `shadow`, or `propose`. |

## DevUpdatePrincipalRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `grant_capabilities` | `DevCapability[]` | Required | 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 | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | Optional | A new name, 1 to 512 characters. length 1..512 |
| `description` | `string \| null` | Optional | A new description, or `null` to clear it. length 1..4096 |
| `external_id` | `string \| null` | Optional | 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 | Required | Description |
| --- | --- | --- | --- |
| `message` | `string` | Required | The version's new message, at most 120 characters. max length 120 |

## DevUpdateWebhookRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | `string` | Optional | A new receiver URL, under the same rules as on create. max length 2048 |
| `ops` | `DevChangeOp[]` | Optional | The event kinds to send from now on. No repeats. items 1..5 |
| `description` | `string \| null` | Optional | `null` clears it. max length 256 |
| `status` | `DevWebhookStatus` | Optional | `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` | Optional | Skip everything not yet delivered and continue from now. Required to reopen a webhook disabled with `cursor_expired`. |

## DevUpload

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `DevId` | Required | length 1..256 |
| `path` | `DevPath` | Required | length 1..4096 |
| `part_size` | `integer` | Required | Every part is exactly this long except the last. |
| `expires_at` | `string (date-time)` | Required | When the session ends. It is not extended. |

## DevUploadPartHeaders

Send these on every part.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `content-type` | `string` | Required | The `Content-Type` every part's `PUT` must carry. |

## DevUploadPartTarget

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `part_number` | `integer` | Required | The part this URL is for, numbered from 1. |
| `url` | `string (uri)` | Required | `PUT` the part here. |

## DevUploadParts

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | `DevUploadPartTarget[]` | Required | One upload target per part that is still to be uploaded. |
| `received` | `DevCompletedPart[]` | Required | 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_at` | `string (date-time)` | Required | At most five minutes away. |
| `required_headers` | `DevUploadPartHeaders` | Required |  |

## DevUploadPartsRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `part_numbers` | `integer[]` | Required | Numbered from 1. items 1..128 |

## DevUsageFigure

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `metric` | `writes \| storage_bytes \| model_tokens \| model_spend_micro_usd` | Required | `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_start` | `string (date-time)` | Required | The start of the window `used` counts from. The Unix epoch for a cumulative metric. |
| `used` | `integer` | Required | How much of the metric has been used in the window. |
| `limit` | `integer` | Optional | 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 | Required | Description |
| --- | --- | --- | --- |
| `data` | `DevSpaceUsageFigure[]` | Required | One figure per Space and metric, ordered by Space id, then metric. |
| `next_cursor` | `DevCursor` | Optional | length 1..1024 |
| `tenant_totals` | `DevUsageFigure[]` | Optional | On the first page only, for a `tenant_admin` key without Space restrictions. |
| `plan` | `DevPlan` | Optional | 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 | Required | Description |
| --- | --- | --- | --- |
| `id` | `DevId` | Required | Starts with `ver_`. |
| `entry_id` | `DevId` | Required | The Entry this is a version of. |
| `status` | `DevVersionStatus` | Required | How far processing has progressed. |
| `updated_from` | `DevId` | Optional | The version this one replaced. Absent on the first version. |
| `message` | `string` | Optional | The note its author attached, like a commit message. |
| `author_principal_id` | `DevId` | Optional | Who wrote it. |
| `created_at` | `string (date-time)` | Required | 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 | Required | Description |
| --- | --- | --- | --- |
| `entry_id` | `DevId` | Required | length 1..256 |
| `from_version_id` | `DevId` | Required | length 1..256 |
| `to_version_id` | `DevId` | Required | length 1..256 |
| `identical` | `boolean` | Required | True when both versions hold the same bytes. |
| `basis` | `DevDiffBasis` | Required |  |
| `unified_diff` | `string` | Optional | The differences in unified diff format. Empty when `identical`; absent when `diff_omitted` is set. |
| `diff_omitted` | `DevDiffOmitted` | Optional |  |

## 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 | Required | Description |
| --- | --- | --- | --- |
| `id` | `DevId` | Required | length 1..256 |
| `space_id` | `DevId` | Required | length 1..256 |
| `url` | `string (uri)` | Required | `https` on port 443. |
| `ops` | `DevChangeOp[]` | Required | Event kinds to send. Events of other kinds are skipped, not queued. |
| `description` | `string` | Optional | A note for people. |
| `status` | `DevWebhookStatus` | Required | `active`, or `disabled` when deliveries have stopped; `disabled_reason` says why. |
| `disabled_reason` | `DevWebhookDisabledReason` | Optional | Present when `status` is `disabled`. |
| `cursor` | `DevCursor` | Required | The change-feed position after the last batch delivered or skipped. |
| `consecutive_failures` | `integer` | Required | Failed attempts since the last success. |
| `last_success_at` | `string (date-time)` | Optional | When a batch was last delivered. |
| `last_failure_at` | `string (date-time)` | Optional | When an attempt last failed. |
| `next_attempt_at` | `string (date-time)` | Optional | When the next attempt may start. Absent when disabled. |
| `created_by_principal_id` | `DevId` | Required | length 1..256 |
| `created_at` | `string (date-time)` | Required | When the webhook was created. |
| `updated_at` | `string (date-time)` | Required | 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 | Required | Description |
| --- | --- | --- | --- |
| `id` | `DevId` | Required | length 1..256 |
| `delivery_id` | `DevId` | Required | The batch, the same as `Mirabase-Delivery-Id`. Attempts at one batch share it. |
| `first_seq` | `integer` | Required | The first change sequence number of the batch, before filtering. |
| `last_seq` | `integer` | Required | The last change sequence number of the batch, before filtering. |
| `event_count` | `integer` | Required | Events sent after filtering. |
| `attempt` | `integer` | Required | 1 for the first attempt at this batch. |
| `outcome` | `DevWebhookOutcome` | Required | `delivered` on any 2xx answer, otherwise `failed`. |
| `http_status` | `integer` | Optional | The receiver's HTTP status, when it answered. |
| `error_code` | `DevWebhookErrorCode` | Optional |  |
| `duration_ms` | `integer` | Required | How long the attempt took, in milliseconds. |
| `created_at` | `string (date-time)` | Required | 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.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | `space.changes` | Required | Always `space.changes`. |
| `webhook_id` | `DevId` | Required | length 1..256 |
| `delivery_id` | `DevId` | Required | length 1..256 |
| `space_id` | `DevId` | Required | length 1..256 |
| `events` | `DevChange[]` | Required |  |
| `cursor` | `DevCursor` | Required | length 1..1024 |

## DevWebhookStatus

Values: `active | disabled`

## DevWhoami

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `tenant_id` | `DevId` | Required | The account this key belongs to. |
| `principal` | `DevPrincipal` | Required | Who the request acts as. |
| `key` | `DevWhoamiKey` | Optional | Absent when the request was not authenticated with an API key. |
| `effective_capabilities` | `DevCapability[]` | Required | Principal capabilities intersected with key capabilities. |

## DevWhoamiKey

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `DevId` | Required | length 1..256 |
| `prefix` | `string` | Required | The first characters of the key: safe to show, enough to tell keys apart. |
| `capabilities` | `DevCapability[]` | Required | What the key itself allows. A request acts with `effective_capabilities`, the part the principal also has. |
| `allowed_space_ids` | `DevId[]` | Optional | The Spaces the key is narrowed to. Absent means not narrowed to specific Spaces. |
| `metadata_scope` | `DevMetadataScope` | Optional | The metadata scope the key is limited to. Absent means not limited by metadata. |
| `expires_at` | `string (date-time)` | Optional | 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 | Required | Description |
| --- | --- | --- | --- |
| `calls` | `integer` | Required |  |
| `errors` | `integer` | Required |  |
| `input_tokens` | `integer` | Required |  |
| `output_tokens` | `integer` | Required |  |
| `total_tokens` | `integer` | Required |  |
| `audio_seconds` | `number` | Required |  |
| `images` | `integer` | Required |  |
| `model_usd` | `number` | Required |  |
| `unpriced_calls` | `integer` | Required | Calls whose model has no price; their spend is not in `model_usd`. |
