# Mirabase Developer API > One data model for files, knowledge and memory, reached by path, by id or by meaning. Base URL: https://api.mirabase.dev OpenAPI: https://api.mirabase.dev/v2/openapi.yaml (the operations an API key can call, with examples) Docs and SDKs (TypeScript, Python): https://mirabase.dev/developers Console (sign up, create keys): https://console.mirabase.dev ## Start here With a key and nothing else, five calls cover files, memory and answers: PUT /v2/spaces/default/files?path=/notes/plan.md the file, as the request body POST /v2/memories {"scope": "project", "space_id": "default", "kind": "preference", "text": "..."} POST /v2/spaces/default/ingest {"kind": "conversation", "session_id": "...", "messages": [{"role", "content"}]} POST /v2/retrieval/search {"query": "..."} finds the file on the next request POST /v2/retrieval/answer {"question": "..."} an answer that cites what it used, or `abstained` The second call stores one lasting statement as a memory. The third stores a conversation and the service distills memories from it in the background (202 with a `job_id`; list them with `GET /v2/memories`). Which call to use: - To store: something with a path (a document, notes, a table as CSV) goes to `PUT .../files?path=`. Text or a URL without a path goes to `POST .../ingest` (`kind: "text"` or `"url"`). A conversation goes to `ingest` with `kind: "conversation"`. One sentence that stays true goes to `POST /v2/memories`. - To read: `search` when you pick the passages yourself; `context` when the service should pick them within a token budget for your own model; `answer` when you want the finished answer with citations. - To fix a memory: `POST /v2/memories/{id}/correct` replaces it and keeps the old one as history. `DELETE /v2/memories/{id}` erases it for good; use it only when asked to forget. `default` works anywhere a `{space_id}` does, in a path, as `?space_id=default` or in `space_ids`. It is your own default Space, or the only Space you can see; otherwise it is 404, so pass a Space id. To keep one end user's data apart, give that user a Space: memory is kept per Space, and metadata does not separate it. `PUT /v2/spaces/ext:` returns the Space that carries your own id for a user, creating it when there is none, and `ext:` then works wherever a Space id does. Retrieval (`search`, `context`, `answer`) without `space_ids` reads every Space the key can read, not the default Space: name the Space when a call is about one user. The SDKs (0.3.0) wrap these: `mb.spaceFor("user-42")` (`mb.space_for` in Python) returns a client pinned to that user's Space, `mb.conversations.add(messages, ...)` stores a conversation and `mb.answer.stream(question)` reads an answer as it is written. ## Authentication Send `Authorization: Bearer mb_live_...`. A key belongs to one principal and can only narrow it: effective capabilities are the principal's intersected with the key's, and a key may be limited to specific Spaces. Check what a key can do with `GET /v2/whoami`. ## Conventions - Lists return `{data, next_cursor}`; `next_cursor` is absent on the last page. - Writes that create something accept `Idempotency-Key`; the OpenAPI document declares the header where it is read, and a branch merge requires it. The same key and input replay the result for 24 hours; the same key with different input is 409. A replayed key issue or rotation has no `token`. Calls that are safe to repeat as they are (retrieval, upload parts, a memory's review) ignore the header. - A query parameter the operation does not know is 422, so a misspelt `branch` never writes to main. - Request fields are `actor_id` and `grant_capabilities`, never `principal_id` or `capabilities`: those names are server-controlled, and sending them anywhere in a body is 403 `identity_override`. The same goes for `user_id`, `tenant_id`, `roles` and `entitlements`, as a `metadata` key too. - Every authenticated response carries `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`. An account also has a total across all its keys, and a cap on live keys, principals and Spaces (409 `tenant_limit_reached`): `GET /v2/limits` has the figures. A 429 `rate_limited` says which limit was hit in `limit`: `request_rate` (the per-minute budget those headers describe) or `concurrency` (too many searches, answers or writes to one Space in flight; the call already waited for a slot, so run fewer at once). - Writes are processed in the background, and an account holds at most `tenant_queued_jobs` queued jobs. Past that, writes get 429 `ingest_backlog` with `queue` (how many are queued, whether processing is paused, an estimate of how long the queue needs) and a `Retry-After` of 30 to 600 seconds. `GET /v2/queue` shows the account's queue at any time; `files/batch` and finished imports report `queue.queued_items` and `queue.eta_seconds`. - A used-up stored quota is 429 `quota_exceeded` with `quota`: `writes`, `model_tokens` or `model_spend_micro_usd` (all reset at the start of the month, UTC) or `storage_bytes`. Retrying does not help. On the `free` plan every billable model call (answers, processing, recognition, search) is checked against the two model quotas before it runs; a processing step that does not fit fails with `quota_exceeded`. `GET /v2/usage` shows what is left, and `GET /v2/limits` the account's `plan` and its figures. - A Space is the unit of isolation: one per end user or per project keeps their files, knowledge and memories apart. `POST /v2/spaces` creates one and `DELETE /v2/spaces/{id}` removes it with everything in it (owner only, not the default Space, not undoable; the content is erased in the background and the place is free at once). A key that can read more than 200 Spaces must name the Spaces to search in `space_ids`. ## Errors `{error: {code, type, status, message, request_id, retryable, field?, errors?, remediation?: {action, doc_url?}}}`. `type` is the broad class, from the HTTP status: `invalid_request`, `authentication`, `permission`, `not_found`, `conflict`, `rate_limit` or `server`. On a 422 from a request body, `errors` lists every problem as `{field, code, message}` and `field` is the first. A body field the operation does not know is 422, not ignored. Branch on `code` and `remediation.action`; the OpenAPI lists which action each code carries, as `x-mirabase-remediation-actions` on the error's `code`. A resource you cannot see and one that does not exist get the same 404. After a 403, read `GET /v2/whoami`: when `effective_capabilities` is narrower than `principal.capabilities`, or `key.allowed_space_ids` is set, the key is the limit, not the principal. Permission by metadata: `POST /v2/api-keys` takes `metadata_scope`, such as `{"customer": ["acme", "shared"]}`. That key only sees Entries holding one of the listed values under every scope key, in search, context, answers, reads by id and memories; an Entry without those labels does not exist for it. What it ingests is stored with the first value of each key. A scoped key can read, search, answer and ingest; other operations are 403 `scoped_key_route_unavailable`. The server enforces it on every request, so it cannot be forgotten like a filter. It also holds in the background: near-duplicate detection and memory revision only relate Entries that carry the same values under the scope keys, so one customer's writes never hide or outdate another's. Account memories have no labels and are not visible to a scoped key. The scope does not hide Spaces themselves (names and `external_id`); for a hard wall between end users still give each user a Space (`external_id` finds it). ## Paths Paths are absolute: at most 64 levels, 4096 bytes, 255 bytes per name. Names compare by NFKC and case folding but keep the spelling you wrote, so `/Docs` and `/docs` are one directory. `/.mirabase/` is reserved, except that `/.mirabase/skills//` holds your skills and `/.mirabase/memory/MEMORY.md` can be read. `POST .../tree/operations` is atomic. `move` takes the complete new path and creates missing parents; an occupied target is 409 `path_conflict`, nothing is overwritten. Deleting a non-empty directory needs `recursive: true`. The response's `delete_batch_id` restores everything that request deleted; `restore` with `path` brings back one file. `{op: "copy", from, to}` copies a file or a directory inside the same Space. `to` is the complete new path, an occupied one is 409 `path_conflict`, and copying a directory into itself is 409 `copy_into_descendant`. Each copied file is a new Entry, listed in the response's `copies` with its `source_entry_id`: its first version shares the source's latest bytes, its history starts there, and it is processed like a new file. Every copied file counts one `writes` and its full size in `storage_bytes`, so purging either side gives back its own share. Copying counts toward the 200-node limit, and an Agent in `proposal` mode may copy files it does not own. Over the limit is 409 `subtree_too_large`. Send `Prefer: respond-async` with a single `move`, `copy`, recursive `delete` or `restore` by `delete_batch_id` and, when it is over the limit, it runs as a job of up to 10000 nodes: 202 with `{job_id}`, `Location: /v2/jobs/{id}` and `Preference-Applied: respond-async`. Under the limit it runs as usual. Several operations over the limit are 422 with `field: "Prefer"`. Poll `GET /v2/jobs/{id}`: `progress`, `result` and, on failure, `error.code`. A job `move` is one transaction; `delete`, `restore` and `copy` run 200 nodes at a time and are not atomic, so a failed delete leaves a half-deleted tree that `result.delete_batch_id` restores. Each chunk checks permissions again: a revoked key, a removed membership or a changed `write_root` stops the job. A Space runs at most 4 jobs that change the tree at a time and 4 exports on top of those, the next is 429 `too_many_jobs`. Finished jobs stay readable for 7 days. Cancelling a job is not available yet. ## Files `PUT .../files?path=` writes the request body as a file, at most 16 MiB, and `Content-Type` is kept. It is committed and readable when it returns: 201 on create, 200 on update, `knowledge.state` is the indexing progress. Without `If-Match` the last write wins and the version chain stays intact. Send the `ETag` in `If-Match` to fail with 412 `precondition_failed` if the file moved on: the error's `current_version_id` is what it is now. `If-None-Match: *` creates only. The same bytes return 200 with `version_created: false` and no new version. Two paths with the same bytes are two files. Text up to 64 KiB is `searchable` as soon as the write returns, lexically; anything else is `readable` until it is `indexed`. Send `Prefer: wait=N`, at most 10, on `PUT`, `PATCH` or `ingest` to hold the response until processing finishes. The write is committed either way, so running out of time is not an error. `GET .../files?path=` returns bytes; `view=meta` the Entry; `view=text`, `table`, `recognized` a content view, and `version=` picks an older version. `view=text` works on a text file right after the write; other views are 404 `content_not_ready` until processing finishes, and 422 `view_not_available` when it has finished and the file has no such view (a zip has no text). `HEAD` returns the headers. With `view=raw`, `If-None-Match` and the `ETag` you hold answer 304 when the bytes have not changed. `PATCH .../files?path=` takes `{edits: [{old_text, new_text, replace_all}]}`, on UTF-8 text files. `edit_no_match` and `edit_ambiguous` are 422 and change nothing. A file over 1 MiB is 413 `patch_base_too_large`: replace it with `PUT`. `DELETE` moves a file to the trash; `restore` in `tree/operations` brings it back, and a second `DELETE` is 404. `POST .../files/batch` takes up to 50 items of at most 64 KiB, 1 MiB in total, each in its own transaction: the response is 200 and every result has its own `status`. Sending the same `Idempotency-Key` again finishes a batch that was cut short or had an item with `retryable: true`: committed items replay, failed ones run again. That also makes it the delete to use when a retry must tell "done" from "never existed". An item whose Entry was purged since replays as 410 `gone`: the write happened and its receipt was erased. 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, so a `200` does not promise the path keeps those bytes. The failed version stays in `versions` as `discarded`: read it with `version=`, bring it back with `revert`. Check `knowledge.state` when you need to know the new version took. An Agent changing a file it does not own gets 403 `proposal_required` unless the Space owner set its `write_mode` to `direct` with `PUT .../members/{principal_id}`. A Space that is busy for 2 seconds is 409 `space_busy` with `Retry-After`. The Space owner can limit a member to one subtree with `write_root` on `PUT .../members/{principal_id}` (`null` or `/` removes it). The member then writes only below that directory, not to the directory itself: anything else is 403 `outside_write_root`, and so is every Entry without a path (`ingest`, project memories, distilled facts), except the member's own Agent memories. Reads do not change. The limit follows the directory through renames and moves, and deleting a directory that holds any member's `write_root` is 409 `directory_is_write_root`, for the owner too. Branches are not limited; a merge writes main and is checked path by path, all or nothing. `read_root` on the same request limits what a member can read. Everything outside that directory looks like it does not exist: 404 for files, tree paths, Entries, versions and jobs; search, context and memories leave it out; `changes` drops those events, and a file moved in or out shows up as `create` or as `delete` without a path. Entries without a path are outside it too, except the member's own Agent memories. Without a `write_root` the member writes under its `read_root`; a `write_root` must be the `read_root` or below it, otherwise 422 `write_root_outside_read_root`. A member with a `read_root` gets 403 `outside_read_root` from branches in that Space. `GET /v2/spaces` and `GET /v2/spaces/{space_id}` show your own `read_root` and `write_root`; start the tree there. Deleting a directory that holds a member's `read_root` is 409 `directory_is_read_root`. `GET .../files` with `view=raw` honours `Range` (one range) and `If-Range`: 206 with `Content-Range`, or 416 `range_not_satisfiable` when the range is outside the file. Several ranges, or a `Range` that cannot be parsed, are ignored: 200 with the whole file. ## Proposals An Agent that would get 403 `proposal_required` can send `Prefer: handling=proposal` on `PUT` or `PATCH .../files`, `files/batch`, `uploads/{id}/complete` or a branch `merge`: the change becomes a proposal and the file stays as it is. The answer is 202 with `Preference-Applied: handling=proposal` and `{applied: false, proposal_id, entry_id, base_version_id, proposed_version_id}` (in `files/batch`, an item with status 202 and `proposal`; in a merge, `proposed_items`). The preference only acts when the write would otherwise be 403: on your own files and new files it writes directly, with no `Preference-Applied`. `If-Match` still applies, and identical content is still 200 with no proposal. Moving, deleting and restoring other people's files, `revert` and memory writes cannot be proposed and stay 403. An Agent can have at most 100 open proposals in a Space: the next is 409 `too_many_open_proposals`. A proposal is not a version: `GET .../versions` shows the proposed content only to its author and the Space owner, and it is never searched. Its author and reviewers (the Space owner, and editors who can change the file directly, inside their `write_root`) see it with `GET .../spaces/{space_id}/proposals` (`status` defaults to `open`, and takes `entry_id` and `author_id`), `GET /v2/proposals/{id}`, and `GET /v2/proposals/{id}/diff?against=base|latest`; anyone else gets 404. A reviewer `POST`s `.../approve` with an optional `{message}` or `.../reject`; the author can `.../withdraw`. Approval writes the proposed content as a new version by the Agent. If the file changed since the proposal was made, or is in the trash, approval is 409 `proposal_conflict` with `current_version_id`: nothing is rebased, so submit a new proposal. Acting on a proposal that is no longer open is 409 `proposal_closed`. To wait for a review, poll `GET /v2/proposals/{id}` until `status` is not `open`. ## Branches A branch is a copy-on-write layer over a Space, for work you may throw away. Open one with `POST .../branches` and pass `branch=` to `files`, `files/batch`, `tree`, `tree/operations`, `uploads` and `changes`. Without it those calls are unchanged. Reads check the branch, then fall through to main's latest, so untouched paths drift with main: `main_changed_paths` counts how far. Branch content is not parsed, indexed or searched, and uses `storage_bytes` but no `writes` until it is merged. `tree/operations` on a branch also takes `symlink` and `chmod`, and not `restore` or `copy`. `branch` and the `{branch_id}` in a URL accept an id or an active branch's name; send the id in anything that retries. `POST .../checkpoints` saves the branch's own changes; `POST .../rollback` returns to one, byte for byte on the paths the branch changed. `GET .../diff` lists changed paths with unified diffs. `POST .../merge` with `{message, paths?, on_conflict}` and an `Idempotency-Key` writes everything or nothing, as new versions. A path main changed in the meantime is 409 `merge_conflict` with `error.conflicts`; there is no content merge, so choose `keep_main` or `keep_branch`. Over 1000 paths is 409 `merge_too_large`; with `Prefer: respond-async` it runs as a job instead (202). The job plans every path first and fails with `merge_conflict` and `result.conflicts` before writing anything; it then merges 200 paths at a time, so a conflict that appears midway stops it with the merged paths already gone from the branch: merge again for the rest. While a merge job runs, any merge of that branch is 409 `merge_in_progress`. Branches expire 30 days after the last write and are reclaimed 7 days later. `DELETE` abandons one the same way. `PUT .../branches/{branch_id}/objects/{sha256}` stores opaque bytes, at most 16 MiB, named by their SHA-256. Objects are for Git bundles and overlays: not paths, not in `tree`, not merged, not indexed. A `POST .../checkpoints` can carry a `git` object, kept as sent, that refers to them. ## Snapshots `POST /v2/spaces/{space_id}/snapshots` with `{name}` records every file's path and current version at one moment (`knowledge:write`, editor). It copies no bytes and counts one write. Read it back with `snapshot=` on `tree`, `files` (every view but `meta`, which is 422 `view_not_available`) and `files/content-url`: you get the version the snapshot pinned, even after the file changed, moved or went to the trash. A purged file leaves the snapshot as soon as the purge is requested. `snapshot` with `branch` or `version` is 422. The snapshot's `changes_cursor` continues `changes` from that moment, so a snapshot plus the feed is a full sync with no gap. Directories come from file paths: an empty directory is not in a snapshot, and neither is content without a path. A member with a `read_root` sees only what was under it then, and `file_count` counts only that. A Space holds 100 snapshots (409 `too_many_snapshots`), a snapshot 10000 files (409 `snapshot_too_large`); names are unique per Space (409 `snapshot_name_taken`) and cannot start with `snp_`. `DELETE /v2/snapshots/{id}` is for its creator or the Space owner. ## Large files Files over 16 MiB go through uploads. `POST .../uploads` with `{path, size, media_type, checksum_sha256}` (base64 SHA-256 of the whole file) returns an `id`, a `part_size` and an `expires_at`. `POST /v2/uploads/{id}/parts` with `{part_numbers}`, at most 128 at a time, returns URLs good for five minutes: `PUT` each part to its URL with the returned `required_headers` and keep the `ETag` from the response. Parts already received are left out and come back under `received` with their `etag`, so a client that lost its own record can call it again and resume. Then `POST /v2/uploads/{id}/complete` with `{parts: [{part_number, etag}]}`. The path is resolved at that moment and the rest is the same as `PUT`, including `If-Match` and `If-None-Match: *`. `.../abort` drops the parts. Once an upload is completed or aborted, `parts`, `complete` and `abort` answer 409 `upload_not_open`: start a new one. A file over this deployment's size limit is 413. A file too large to process is still stored and readable, and its `knowledge.state` ends at `failed`. ## Sources without a path `POST .../ingest` takes `{kind: "url", url}`, `{kind: "text", text}` or a conversation (see Memory), with an optional `title`, and returns 202 with `entry_id`, `version_id` and `job_id`, and a `Location` header naming the job. One call makes one Entry; the same content twice is two Entries, so send `Idempotency-Key` when retrying. A URL is fetched after the response: a bad one shows up as a failed job, not as an error here. Every kind takes `metadata`: your own keys, each a string or a list of strings, such as `{"status": "draft", "tags": ["q3", "finance"]}`. Keys are 1 to 64 of `a-z`, `0-9`, `_`, `.`, `-`, and may not start with `mirabase.`; a value is at most 256 bytes, and an Entry holds 32 values in all. `url` and `text` also take `occurred_at`, the time the source is about; a conversation has that on each message. The Entry returns both. `PATCH /v2/entries/{id}` with `{metadata}` replaces the whole object; `{metadata_patch}` changes it key by key (a value sets the key, `null` removes it, the rest stay), so two writers changing different keys do not overwrite each other. Every kind also takes `memory_exclude: true`: the Entry is stored and searchable, and nothing is distilled from it. ## Entries Every file, URL and text is an Entry with immutable versions. Use `files` when you have a path and `/v2/entries/{id}` when you have an id: `GET .../content` takes the same `view` and `version`. A URL has no raw bytes: `view=raw` is 422 `view_not_available`, so read it with `view=text`. `GET .../versions` lists the chain, newest first. `GET .../diff?from=&to=` compares two versions (`to` defaults to the latest): text files up to 1 MiB compare their bytes (`basis: "original"`), anything else the text processing extracted (`basis: "text"`). `diff_omitted` says why there is no `unified_diff`: `too_large`, `not_text`, or `content_not_ready` until both are processed. `GET .../lineage` tells where the Entry came from (`created`, `copy` with its `source` and `chain`, or `branch_merge`) and the `kind` of each version; a source you cannot see is `visible: false`, with no ids. `GET .../files/diff?path=`, `.../files/lineage?path=` and `.../files/versions?path=` are the same by path, and `POST .../files/revert?path=` with `{version_id}` is the revert by path. `POST .../revert` with `{version_id}` writes that content as a new version, and takes `If-Match` like `PUT`. `PATCH /v2/entries/{id}` with `{title}` also makes a version; a file's title is its name, so rename it with `tree/operations`. `PATCH` with `{metadata}` replaces the Entry's metadata as a whole (`{}` clears it) and makes no version. A file can carry metadata from the first write (`?metadata=` on `PUT .../files`, a JSON object) or get it this way afterwards. `GET .../content-url` (and `GET .../files/content-url?path=`) returns `{url, expires_at, size_bytes, media_type}`: a signed URL for the original bytes of `version` (default the latest), good for `expires_in` seconds (60 to 300, default 300). Fetch it without your key. Anyone holding the URL can fetch the bytes until it expires, and revoking the key does not stop that, so treat it like the key. The URL never contains the file name. A small text file kept on the server has no URL to sign: 409 `content_url_unavailable`, read `GET .../content?view=raw`. `branch` is 422. `GET .../processing` and `GET /v2/jobs/{id}` report the same progress: the job is `succeeded` only once the version is indexed, and `failed` when processing gave up. A failure carries `error.code`: `url_fetch_failed` (the page could not be fetched), `url_no_readable_content` (fetched, but no article text: ingest the text itself), `unsupported_input`, `document_too_large`, `no_chunks`, `extraction_timeout` (reading the file ran out of its time budget: convert it to PDF or plain text, or split it), `quota_exceeded` (the free plan's monthly model quota cannot cover the step: reprocess next month or after upgrading), or `job_failed`. `POST .../reprocess` retries a failed version or processes the latest one again; work already in flight is 409 `job_in_flight`. `GET .../processing` also says where the version is: `stage` is `queued`, `extracting`, `indexing`, `enriching` (search finds it; relations, classification, a summary or memories are still being produced), `ready` or `failed`, with `progress` `{done, total}` over the three main steps. While a step waits, `queue` gives its `position` among this account's due jobs, `waited_seconds` and `waiting_for` (`capacity` or `retry`). For a bulk import, poll `GET /v2/spaces/{space_id}/processing` instead: `counts` (`queued`, `processing`, `searchable`, `ready`, `failed`), `searchable_per_minute`, `eta_seconds`, `oldest_queued_seconds` and `waiting_for_capacity`; `memory` (`pending`, `eta_seconds`, `files`) reports memory extraction apart, and an Entry waiting only for it counts as searchable. `memory.files` is `index_only` when files written by path are indexed but not distilled on this deployment (conversations and ingested text still are). Work from different Spaces and accounts takes turns, so a small upload starts within seconds while a large import runs elsewhere. Search, context and answer carry `pending_processing: {entries}` while Entries in the searched Spaces are still being processed and may be missing from the result. `DELETE /v2/entries/{id}` moves any Entry to the trash, with `knowledge:write` and editor, the same as `DELETE` on a file. `GET /v2/entries?trashed=true` lists the trash: each Entry has `trash.deleted_at` and, for a file, the `trash.path` it had; `?metadata=` takes a JSON object of values the Entries must have, `?q=` keeps the Entries whose title or path contains the text (ignoring case), and `?state=failed` lists what processing gave up on. `POST /v2/spaces/{id}/trash/purge` erases what is in a Space's trash, 100 Entries a call (`has_more` says to call again), or only what one delete removed with `{delete_batch_id}`; it needs what `purge` needs. `POST .../restore` brings a trashed Entry and its path back, and an occupied path is 409 `path_conflict`. `POST .../purge` erases an Entry, live or trashed, and needs `knowledge:manage` and the Space owner. It cannot be undone. Storage quota comes back when the request returns; the returned job finishes the erasure. It is not charged against quota: when the quota is used up, it still works. ## Memory "Memory" shows up in four places, and each is a different set. `GET /v2/memories` is the full governed list, candidates and history included. `memory_view` on a context pack and `MEMORY.md` are the index of what is confirmed and current. `include: ["memory"]` on search adds memories to the hits. `memory` on a hit or context item is one fact distilled from that passage. `GET /v2/memories` returns one shape for three sources: account memories, memories written as Entries, and facts distilled from Entries. Filter with `scope`, `space_id`, `status`, `kind` and `entry_id`: `entry_id` keeps what came from one Entry, such as the conversation you just ingested, and `q` keeps the ones whose text contains a phrase. Without `status` you get `candidate` and `confirmed`; `rejected` and `superseded` are history you ask for by name. Facts have their own ids, not Entry ids, and those ids contain colons, so URL-encode them. `GET .../provenance` names the Entry versions a memory rests on. `POST /v2/memories` writes a confirmed memory: `{scope, kind, text}`, plus `space_id` unless the scope is `account`. `account` and `project` need `memory:confirm`, and a person must own the Space for `project`. `agent` needs an Agent key and only reaches that Agent. `kind` is `preference`, `decision` or `progress`. A `project` or `agent` memory is not written twice: when the same `text` is already a current memory of that Space, scope and kind, the response is 200 with the existing memory instead of 201. `POST .../ingest` with `{kind: "conversation", session_id, messages: [{role, content, timestamp?}]}` stores one batch as one Entry and distills it. `timestamp` is an RFC 3339 string or Unix milliseconds; seconds are 422. Messages go in as chat APIs write them: `content` may be a list of segments (the text ones are kept) or `null`, `name`, `tool_calls`, `tool_call_id` and `function_call` are accepted and ignored, and a message without text is skipped. The receipt's `memory_status` says what follows: `confirmed` if you hold `memory:confirm`, otherwise `candidate`, and a candidate stays out of retrieval until someone with `memory:confirm` calls `POST /v2/memories/{id}/review` with `{decision: "confirm"}` or `"reject"`. Distillation runs after indexing, so the job can be `succeeded` before any memory exists: poll `GET /v2/entries/{entry_id}/processing` (or the job) until `memory.state` leaves `pending`, then read the memories. The receipt has the same `memory`. `skipped` comes with `memory.reason`: `model_not_configured` or `distill_disabled` means this deployment does not distill, so write the memories yourself with `POST /v2/memories`. Those two, and `distill_paused` (the account reached its usage limit), are shown only to an unrestricted key of a `tenant_admin` or one with `knowledge:manage`; other keys see `distill_unavailable` for the first two and a plain `pending` for the third. To record a conversation as it happens, send a batch per stretch with the same `session_id`: the id is also stored as the metadata key `session_id`, so `GET /v2/entries?metadata={"session_id":"…"}` lists the batches and `filter: {"metadata": {"session_id": "…"}}` searches within one conversation. `redact_secrets: true` on a `text` or `conversation` ingest replaces what looks like a credential (private keys, JWTs, bearer tokens, common API key formats, `password=…`) before anything is stored; the receipt's `secrets_redacted` counts them. `memory_instructions` on a `conversation` ingest (up to 2,000 characters) tells the distiller what matters in your app and what to ignore, for example "remember allergies, ignore small talk"; every memory still needs a quote from the messages. `DELETE /v2/memories/{id}` forgets a memory with `knowledge:write` and editor. It stays forgotten: the same sentence is not distilled again in that Space, and republishing, restoring, editing or moving the source does not bring it back. The source Entry and its search results do not change: when a distilled fact is forgotten the receipt lists them as `remaining_sources`, to trash or purge if the text itself has to go. A memory written as an Entry is erased, along with the ones it replaced. A second delete is 404. Forgetting cannot be undone. `POST /v2/memories/{id}/correct` with `{text}` replaces a memory and needs `memory:confirm`. For a fact or a memory written as an Entry, the replacement is a new memory Entry in the same Space, so the response has a new `id`, and `supersedes` names the old one. A person must own the Space to do this. An Agent in `proposal` mode gets 403 `proposal_required` on forgetting and correcting, because they reach sources it did not write. `POST /v2/memories/{id}/undo` takes back what you wrote within 30 minutes. Call it on the new memory: it is erased and `restored` lists what came back. Governance conflicts are 409 with their own codes: `memory_pending_review` (review it first), `memory_already_reviewed`, `memory_superseded` (read the current memory), `undo_window_expired` and `undo_not_applicable`. `PATCH /v2/memories/{id}` pins a memory written as an Entry, or closes a fact or an account memory with `valid_to`. `GET .../files?path=/.mirabase/memory/MEMORY.md` is a generated view of a Space's memory for an Agent starting work: the same memories give the same bytes, so it works as a prompt-cache prefix, and `If-None-Match` gets a 304. It holds what `POST /v2/retrieval/context` calls the memory view: account memories and memories written as Entries, not distilled facts. Writing to it is 405 `virtual_file`. `PATCH /v2/entries/{id}` with `{memory_exclude: true}` retires what was distilled from an Entry and stops distilling it. Search and reading are not affected. `false` distills it again, without what you forgot. ## Staying in sync `GET .../tree` lists a directory, and every file comes with its `version_id`, `etag`, `size_bytes`, `media_type` and `modified_at`: compare the `etag` with the one you hold to tell what changed, without a request per file. It also returns a `changes_cursor` taken before it read the tree; keep the one from the first page. `GET .../changes?cursor=` then returns what happened after it, oldest first, and a new `cursor` to pass back. Sequence numbers follow commit order with no gaps. An event can repeat what the tree already showed, so apply them by `entry_id`, keeping the path of each Entry from `tree`: a `move` carries only the new path. Directory moves produce one `move` per file; directories themselves produce no events. `wait=N` (at most 30 seconds) holds an empty response until something changes, and a key can hold 4 of these at once, then 429 `too_many_waiters`. Events are kept 90 days: an older cursor is 410 `cursor_expired`, so start again from `tree`. Without `cursor` the feed starts from now. `GET .../activity?days=7` sums the same feed up per principal: who changed which Entries lately, each with its latest path, operation and time. Read it before planning work in a Space others also write to, so two agents do not edit the same file. It looks back over at most the last 1000 changes. To record why a file changed, add `session_id` to a `PUT` or `PATCH .../files` (the id you ingest the conversation with): it is stored on the version, and `GET .../files/lineage?path=` then shows which conversation each version came from. `files/batch` and `uploads/{id}/complete` take it as `session_id` in the body. ## Webhooks Instead of polling `changes`, `POST /v2/spaces/{space_id}/webhooks` with `{url, ops?, description?, cursor?}` (`knowledge:manage` and `knowledge:read`, Space owner, at most 10 per Space, 409 `too_many_webhooks`). The URL must be `https` on port 443 with a public host; anything else is 422 `invalid_webhook_url`. The response carries `secret` once; a replay with the same `Idempotency-Key` does not, so call `POST /v2/webhooks/{id}/rotate-secret` if you lose it (the new secret applies at once). Mirabase POSTs `{type: "space.changes", webhook_id, delivery_id, space_id, events, cursor}` with up to 100 main-line events in order, one batch at a time, at least once. `events` are what the creator would see on `changes` now, filtered by `ops`; `cursor` continues `changes` after the batch. Verify every request: `Mirabase-Signature: t=,v1=` where `v1` is HMAC-SHA256 of `t + "." + raw body` keyed by the whole secret string. Compare in constant time and reject a `t` more than 5 minutes from your clock. `Mirabase-Delivery-Id` is the same on every retry of a batch: dedupe on it, and apply events by `entry_id`. Answer 2xx quickly; anything else, a redirect, or no answer within 10 seconds is a failure. Retries back off from 30 seconds, doubling, up to 1 hour. 20 failures in a row disable the webhook (`failing`), and 410 disables it at once (`receiver_gone`); it is also disabled when its cursor expires, the key that created it is revoked or expires (`credential_revoked`), or its creator stops owning the Space (`access_lost`). `PATCH` with `{status: "active"}` reopens it (needs `knowledge:read` too; add `reset_cursor: true` after `cursor_expired`). Every delivery resolves the host again and never connects to a private, loopback, link-local or metadata address (`blocked_address`). `GET /v2/webhooks/{id}/deliveries` lists attempts for 30 days. A deployment without a webhook encryption key answers 503 `webhooks_unavailable` on create, update and rotate; it is not retryable. ## Export and import `POST /v2/spaces/{space_id}/exports` with `{snapshot?, path?}` (`knowledge:read`) is always a job: 202 with `{job_id}` and `Location`. The file list is fixed when the job starts, so the archive is one moment of the Space (with `snapshot`, the snapshot's); a member with a `read_root` exports only what is under it. The archive is a tar: `manifest.json` (`format: "mirabase-export/1"`, every file's `path`, `entry_id`, `version_id`, `size_bytes`, `media_type`, `sha256`), then each file at `files/`. Only files: content without a path, memories and history are not in it. Over 10000 files or the deployment's byte limit is 409 `export_too_large`; export a `path` at a time. When the job succeeds, `result.archive` has its size and SHA-256 and `GET /v2/jobs/{job_id}/content-url` signs a 5-minute download (409 `artifact_not_ready` before that). The archive is kept 7 days; purging any file in the Space makes the Space's archives unavailable (410 `artifact_expired`, a running export fails with `export_invalidated`), and so does setting or changing the `read_root` of the member who started it: export again. `POST /v2/spaces/{space_id}/imports` with `{source_entry_id, path?, on_conflict?}` (`knowledge:write` and `knowledge:read`, editor) imports a tar or gzip-compressed tar you already put in any Space with `PUT .../files` or `uploads`. An exported archive round-trips: its `files/` come back at the same paths with the same media types; any other archive lands under `path` (default `/`). Each file is written like `PUT`: path rules, `write_root`, `write_mode`, quotas and change events are the same, and an import never becomes a proposal. `on_conflict` is `skip` (default) or `overwrite`. A member that cannot be written does not stop the job: `result.failed` counts it and `result.failures` lists the first 100 as `{index, code}`, the member's position in the archive, never its path. The job commits 200 members at a time and is not atomic; a quota running out stops it and keeps what was imported. Not a tar is 422 `unsupported_archive`; too big or over 10000 members is 413 `archive_too_large`. Zip is not supported yet. Forking a Space (`POST /v2/spaces/{space_id}/forks`) is planned; until then snapshot, export with `snapshot`, create a Space and import. ## Searching and building context `POST /v2/retrieval/search` is you choosing: `{query}`, with optional `space_ids`, a `path` to stay inside a subtree, `limit` up to 50 and `include: ["memory"]`. Without `space_ids` it covers every Space you can read, so you do not need one to start. A small text file is findable on the next request: those hits carry `freshness: "pending_index"` and matched by words only, until processing finishes. `score` compares hits inside one response and nothing else. `filter` narrows `search`, `context` and `answer` alike, and needs at least one condition: `{"metadata": {"status": "draft", "tags": {"any": ["q3", "finance"]}}, "source_types": ["file"], "occurred_from": "2026-01-01T00:00:00Z", "occurred_to": "2026-03-31T23:59:59Z"}`. Metadata matches exactly; keys combine with AND, and `any` matches one of its values. An Entry without the key does not match, so memory items, which have no metadata, drop out of a metadata filter. `source_types` takes the `source_type` values hits carry (`file`, `note`, `web`, `agent-conversation`); the ingest kinds `text`, `url` and `conversation` work too. The time range includes both ends and reads `occurred_at`, or the time of writing when there was none. `memory_view` is not filtered. For more than exact matches, `where` takes one condition built from `{"key": k, "eq" | "in" | "exists" | "gt" | "gte" | "lt" | "lte": …}`, `{"not": …}`, `{"and": […]}` and `{"or": […]}`: `{"where": {"and": [{"key": "status", "in": ["draft", "review"]}, {"not": {"key": "archived", "exists": true}}, {"key": "priority", "gte": 2}, {"key": "due", "lt": "2026-12-01"}]}}`. Ranges compare numbers or dates (`YYYY-MM-DD` or ISO 8601, UTC when there is no offset); at most 3 levels and 16 key conditions. All three also take `rerank: false` (no reranker; scores are then not relevance), `min_score` (the lowest rerank score kept, 0 to 1), `max_per_entry` (at most that many passages from one Entry) and `profile` (a named set of these settings the deployment declared; request fields override it). `search` also takes `tier` (`fast`, `standard`, `deep`, as on `context`) and `fields` (which optional hit fields to return). All three take `reference_time` and `timezone`: the moment and the IANA time zone (such as `Asia/Shanghai`) that "yesterday" or "last week" in the query are counted from. Without them it is now, in the deployment's time zone. Send them when you retrieve for a person somewhere else, or for an older message. Hits, context items and answer citations carry `occurred_at` (the source's own time, when it has one) and `modified_at` (when that version was written), so old can be told from new. They also carry `stated_date`, the date the passage is stated as of: a date it marks as its own ("as of", "updated", "截至"), else the date in its section heading, else a date that starts one of its lines or list items, else the date in the document's front matter or top heading (`stated_date_from` says which: `text`, `heading` or `document`). A date mentioned mid-sentence does not count, and when none of these has one there is no `stated_date`. It separates an older record from a newer one when files were uploaded together and have the same `modified_at`. Set `occurred_at` when you write and you know it: it takes precedence. `POST /v2/retrieval/context` is the service choosing: `{task}` returns `items` drawn from memory, your agent profile, the skill index, files the task names, recent changes and knowledge, with `budget_tokens` (default 4000) covering the whole response. `route` explains the result: the `purpose` used, `rules_fired`, and for each source its `budget`, `used`, `picked`, `omitted` and a stable `why`. Routing is rules, not a model, so the same inputs route the same way. Set `purpose` (`task`, `coding`, `research`, `audit`) to skip the inference, and `weights` (0 to 1 per source, 0 turns it off) to lean the split. `tier`: `fast` calls no model, `standard` makes one embedding and one rerank, `deep` looks further. Unused budget flows only to sources with candidates above the relevance floor; the rest stays empty, reported as `route.unused_tokens`. `memory_view` is deterministic and does not depend on the task, so it suits a prompt-cache prefix. Pass `memory_view_etag` back as `have_memory_etag` and it is left out while unchanged. The view also changes with the memory budget, so a different `budget_tokens`, `purpose` or `weights` can send it again. `render: "text"` adds `rendered: {text, tokens}`: the same pack laid out as text for a prompt, each source under its `[cN]` id with where it came from, its times and what to watch for. Same pack, same text. `render: "compact"` is the same idea in a shorter layout, and `budget_tokens` then counts that text instead of the JSON response, so the same budget holds more evidence. Use it when the text is what your model reads. `explain: true` on `search`, `context` or `answer` says why each result came back, without changing the results or their order. Every hit, item and citation gets `explain`: `found_by` (the branches that returned it, such as `lexical`, `dense`, `memory` or `fresh_buffer`, with its rank in each), `fused` (rank and score before reranking), `rerank` (rank and score from the reranker), `matched_terms`, `lexical` (`strong`, `covered` or `partial`), `admitted_by` (what let it past the relevance floor), `boosts` (`time_window`, `newest_on_topic`, `newest_first`, with `reordered_by_date`) and `computed_table`. The response gets a summary: the query terms, candidates per branch and the rerank pool; an answer adds `sentences`, its text split into sentences with the citations each one uses. Leave it out and nothing extra is computed. Skills live at `/.mirabase/skills//SKILL.md`, with `name` and `description` in the front matter. Context lists them as one line each; read the file for the body. 409 `evidence_changed` on either route means something changed while the response was built: send it again. Where the deployment distills conversations with evidence, a search hit or context item can carry `memory`: `{id, kind, text, valid_from?, valid_to?}`, the confirmed memory distilled from that passage. The passage is the evidence and `memory.text` is the statement; `id` is the one `GET /v2/memories/{id}` takes. At most one per file in a response, and never a candidate, rejected or superseded memory. `POST /v2/retrieval/answer` answers a `{question}` from the evidence `context` would pick, citing it as `[cN]`. It takes the same `space_ids`, `purpose`, `weights`, `tier` and `budget_tokens`, plus up to 10 `history` turns and an `output_language`. It needs `knowledge:answer` as well as `knowledge:read`. The response is JSON: `status` is `answered` or `abstained` (with `reason`: `no_evidence`, `model_abstained`, `insufficient_evidence`), and `citations` lists only the evidence the answer cites. Its `pack_id` takes feedback like a context pack. `include: ["evidence"]` adds `evidence`: every item the model read, without text. The model is told when each passage was written and the date its content is from; for a question about the present state ("now", "currently"), passages about the same subject are ordered newest first. The same subject means the same Entry, the same web page saved more than once, or Entries that share a `metadata.subject_key` value (give your weekly status files one key each); similar paths or titles do not count. Unless you send `weights`, an answer leaves out the `changes` and `skills` sources. `stream: true` returns `text/event-stream` instead of JSON. Events carry an `id` (1, 2, 3, ...), a name and one line of JSON: start {"request_id", "pack_id", "evidence_count", "partial", "evidence"?} once, before any text delta {"text"} the next piece: append in order replace {} at most once, right before final: discard the streamed text final the same JSON as the non-streaming response; authoritative error {"error": {...}} the error envelope; discard the streamed text Exactly one of `final` and `error` ends the stream. A stream that ends without either was cut off: ask again. Lines starting with `:` are keep-alive comments (on open, and after 15 idle seconds). A stream cannot be resumed; `Last-Event-ID` is ignored. Ignore event names you do not know. Closing the connection cancels the answer. Errors before the stream opens (authentication, validation, no free slot) are ordinary HTTP responses. The SDKs read the stream for you: `mb.answer.stream(question)` in both, an async iterator in TypeScript and an iterator (`async for` on `AsyncMirabase`) in Python. Up to `answer_concurrency` answers (3 by default, at `GET /v2/limits`) run at a time per principal, across all of its keys; another waits up to 10 seconds, then 429. 502 `model_failed` means try again later. 503 `answer_not_configured` means this deployment has no answer model: do not retry, build the pack with `context` and run your own model. If you have your own model, `context` is usually what you want. After using a pack, `POST /v2/retrieval/context/{pack_id}/feedback` with `{used_citation_ids}` says what helped. It takes references only, returns 204, and reports add up, so repeating one is safe. A citation that is not in the pack is 422 `unknown_citation`, and only the principal that built the pack can report on it. ## MCP `/mcp` is MCP over Streamable HTTP, with the same key as `Authorization: Bearer`. `tools/list` shows what this key can call: `mira.whoami`, `mira.files.list`, `.read`, `.write`, `.edit`, `.delete`, `mira.search`, `mira.context`, `mira.context.feedback`, `mira.answer`, `mira.activity`, `mira.memory.list`, `.remember`, `.forget`, `.correct`, `.review`, `mira.conversation.ingest`, `mira.text.ingest`, `mira.url.ingest`, `mira.entries.read`, `mira.trash.list` and `.restore`. A key limited to a metadata scope is only shown the tools it can use. Each tool is one `/v2` request, so permissions, limits and errors are the same, and a failed tool is a result with `isError: true`, also when the key lacks the capability the tool needs (`forbidden`): its text gives the code, whether to retry and the next step, and `_meta["dev.mirabase/error"]` carries the error envelope. A failed result has no `structuredContent`. A successful result carries its JSON once, as the text of `content`. Each tool has `annotations`: `readOnlyHint` on the tools that change nothing, `destructiveHint` on `mira.memory.forget` and `mira.files.delete`. `mira.search` and `mira.context` take the same `filter`. `mira.files.write` and `.edit` take `session_id`. File, ingest, activity and trash tools use `default` when `space_id` is left out. `mira.search`, `mira.context`, `mira.answer` and `mira.memory.list` do not: without `space_ids` (`space_id` on `mira.memory.list`) they read every Space the key can read. To fix a memory use `mira.memory.correct`, which keeps the old statement as history; `mira.memory.forget` erases for good. A tool call counts as two requests against your rate limit: the `/mcp` call, and the `/v2` request it makes. ## Request logs `GET /v2/request-logs` lists the account's recent requests, newest first: `route` (the method and route template), `status`, `error_code`, `duration_ms`, `key_id` with its name, `principal_id`, `request_id` (the `X-Request-Id` header), `trace_id` on retrieval calls, and `client` (the SDK, the CLI, an MCP client, curl, recognized from `User-Agent`). Filter with `status_class`, `route`, `key_id`, `error_code`, `client`, `since`, `until`, `request_id` and `trace_id`. Only metadata is kept, never a body, a query string or a key, for `retention_days` days (14 by default). `GET /v2/retrieval/traces/{trace_id}` reads what a search, context or answer call recorded; a search trace includes its query. The logs need a `tenant_admin` key with `knowledge:manage` and no Space or metadata restriction; such a key reads every trace, any other key only the traces of its own principal. Requests appear within about a second. ## Replacing a key A key cannot rotate itself: if the response were lost, nothing would be left to authenticate with. Issue a new key with `POST /v2/api-keys`, switch to it, then `DELETE` the old one. If the response to the issue is lost, the old key still works: issue again under a new `Idempotency-Key`. The unused key stays live until a `tenant_admin` finds it in `GET /v2/api-keys` and revokes it. ## Available now - POST /v2/retrieval/search - POST /v2/retrieval/context - POST /v2/retrieval/answer - POST /v2/retrieval/context/{pack_id}/feedback - GET /mcp - POST /mcp - GET /v2/whoami - GET /v2/usage - GET /v2/limits - GET /v2/queue - GET /v2/audit/events - GET /v2/request-logs - GET /v2/request-logs/{log_id} - GET /v2/retrieval/traces/{trace_id} - GET /v2/principals - POST /v2/principals - GET /v2/principals/{principal_id} - PATCH /v2/principals/{principal_id} - GET /v2/api-keys - POST /v2/api-keys - GET /v2/api-keys/{key_id} - DELETE /v2/api-keys/{key_id} - POST /v2/api-keys/{key_id}/rotate - GET /v2/spaces - POST /v2/spaces - GET /v2/spaces/{space_id} - PATCH /v2/spaces/{space_id} - PUT /v2/spaces/{space_id} - DELETE /v2/spaces/{space_id} - GET /v2/spaces/{space_id}/members - GET /v2/spaces/{space_id}/processing - PUT /v2/spaces/{space_id}/members/{principal_id} - DELETE /v2/spaces/{space_id}/members/{principal_id} - GET /v2/spaces/{space_id}/changes - GET /v2/spaces/{space_id}/activity - GET /v2/spaces/{space_id}/branches - POST /v2/spaces/{space_id}/branches - GET /v2/spaces/{space_id}/branches/{branch_id} - PATCH /v2/spaces/{space_id}/branches/{branch_id} - DELETE /v2/spaces/{space_id}/branches/{branch_id} - GET /v2/spaces/{space_id}/branches/{branch_id}/checkpoints - POST /v2/spaces/{space_id}/branches/{branch_id}/checkpoints - POST /v2/spaces/{space_id}/branches/{branch_id}/rollback - GET /v2/spaces/{space_id}/branches/{branch_id}/diff - POST /v2/spaces/{space_id}/branches/{branch_id}/merge - PUT /v2/spaces/{space_id}/branches/{branch_id}/objects/{sha256} - HEAD /v2/spaces/{space_id}/branches/{branch_id}/objects/{sha256} - GET /v2/spaces/{space_id}/branches/{branch_id}/objects/{sha256} - POST /v2/spaces/{space_id}/snapshots - GET /v2/spaces/{space_id}/snapshots - GET /v2/snapshots/{snapshot_id} - DELETE /v2/snapshots/{snapshot_id} - POST /v2/spaces/{space_id}/webhooks - GET /v2/spaces/{space_id}/webhooks - GET /v2/webhooks/{webhook_id} - PATCH /v2/webhooks/{webhook_id} - DELETE /v2/webhooks/{webhook_id} - POST /v2/webhooks/{webhook_id}/rotate-secret - GET /v2/webhooks/{webhook_id}/deliveries - GET /v2/spaces/{space_id}/tree - POST /v2/spaces/{space_id}/tree/operations - GET /v2/spaces/{space_id}/proposals - GET /v2/proposals/{proposal_id} - GET /v2/proposals/{proposal_id}/diff - POST /v2/proposals/{proposal_id}/approve - POST /v2/proposals/{proposal_id}/reject - POST /v2/proposals/{proposal_id}/withdraw - PUT /v2/spaces/{space_id}/files - PATCH /v2/spaces/{space_id}/files - GET /v2/spaces/{space_id}/files - HEAD /v2/spaces/{space_id}/files - DELETE /v2/spaces/{space_id}/files - POST /v2/spaces/{space_id}/files/batch - GET /v2/spaces/{space_id}/files/diff - GET /v2/spaces/{space_id}/files/lineage - GET /v2/spaces/{space_id}/files/versions - POST /v2/spaces/{space_id}/files/revert - GET /v2/spaces/{space_id}/files/content-url - POST /v2/spaces/{space_id}/uploads - POST /v2/uploads/{upload_id}/parts - POST /v2/uploads/{upload_id}/complete - POST /v2/uploads/{upload_id}/abort - POST /v2/spaces/{space_id}/ingest - GET /v2/entries - GET /v2/entries/{entry_id} - PATCH /v2/entries/{entry_id} - DELETE /v2/entries/{entry_id} - GET /v2/entries/{entry_id}/content - GET /v2/entries/{entry_id}/content-url - GET /v2/entries/{entry_id}/versions - GET /v2/entries/{entry_id}/versions/{version_id} - GET /v2/entries/{entry_id}/diff - GET /v2/entries/{entry_id}/lineage - PATCH /v2/entries/{entry_id}/versions/{version_id}/message - POST /v2/entries/{entry_id}/revert - GET /v2/entries/{entry_id}/processing - POST /v2/entries/{entry_id}/reprocess - POST /v2/entries/{entry_id}/purge - POST /v2/spaces/{space_id}/trash/purge - POST /v2/entries/{entry_id}/restore - GET /v2/jobs/{job_id} - GET /v2/jobs/{job_id}/content-url - POST /v2/spaces/{space_id}/exports - POST /v2/spaces/{space_id}/imports - GET /v2/memories - POST /v2/memories - GET /v2/memories/{memory_id} - PATCH /v2/memories/{memory_id} - DELETE /v2/memories/{memory_id} - POST /v2/memories/{memory_id}/review - POST /v2/memories/{memory_id}/correct - POST /v2/memories/{memory_id}/undo - GET /v2/memories/{memory_id}/provenance - GET /v2/openapi.yaml - GET /llms.txt Operations in the OpenAPI document marked `x-mirabase-stage: planned` do not exist yet. ## Memory consolidation (dreams) This deployment runs offline memory consolidation, called dreams. A dream only reorganizes memories that you and your agents already wrote: it generates nothing, every action it takes carries its evidence, and it can be undone. Operations in the OpenAPI document marked `x-mirabase-feature: memory-dreaming` exist only on deployments like this one; elsewhere they are 404. `GET /v2/spaces/{space_id}/memory/settings` returns `{space_id, memory_dreaming, dormancy, d4, d4_available}` (`knowledge:read`). `propose`, the default, lets dreams run for the Space; `off` stops them. `dormancy` is `report`, the default, or `apply` (see below). `d4` is `off`, the default, `shadow` or `propose` (see below); `d4_available` says whether this deployment has a model for it. The Space owner changes these with `PATCH` and `{memory_dreaming?, dormancy?, d4?}` (`knowledge:manage`); a field left out keeps its value, `auto` is not available yet and is 422. Setting `off` undoes nothing that already happened. Memory views send no change events: to see whether `/.mirabase/memory/MEMORY.md` changed, compare its `ETag` with `HEAD`. Dreams run on their own when a scope has new memories; `POST /v2/spaces/{space_id}/memory/dreams` with `{scope?: "project" | "agent"}` starts one now and answers 202 with `job_id` (follow `GET /v2/jobs/{job_id}`). A scope is the Space's project memory, or one Agent's private memory (an Agent key's default); dreams never cross scopes. Today a dream checks each distilled memory's quotes against the current version of its source and marks the ones whose quotes are all gone as dormant: `GET /v2/memories` then shows `dormant: {reason: "quote_missing", dream_id}` on them, and they stay listed and searchable. A dream never marks a memory a person confirmed (an approved candidate, or one distilled from a conversation ingested with `memory:confirm`) and never brings back forgotten ones. `status: "confirmed"` also covers distilled memories that took effect without review, and only those can be marked; they then leave `/.mirabase/memory/RECENT.md`. One dream checks at most 10,000 memories of a scope; the next one goes on from where it stopped (`remaining` in the report) and starts over once a dream reaches the end. Then a dream looks for unused distilled memories: not served for 90 days and through three dreams of the scope in a row (served means `GET /v2/memories/{memory_id}`, or handed back by `/v2/retrieval/search`, `context` or `answer`), outside the 20 most used of their kind. Rules and preferences (kinds `preference`, `profile`, `workflow`, `lesson`, `commitment`) and memories a person confirmed never count. Under `dormancy: "report"` the dream only reports them (`dormancy_candidates`, and `reported` actions that change nothing); under `apply` it marks them `dormant: {reason: "unused", dream_id}` (`dormant_unused`). An unused memory leaves `RECENT.md` (`MEMORY.md` holds only confirmed memories, which never go dormant) but stays listed and searchable, and wakes up the first time it is served again. A memory with both reasons shows `quote_missing`. The project scope needs `knowledge:write`, `memory:confirm`, editor, and no `write_root` or `read_root` in the Space; one dream per scope at a time (409 `dream_run_in_flight`), and the setting `off` is 409 `dreaming_disabled`. `GET /v2/memory/dreams/{dream_id}` is the report: counts, the number and tokens of active memories before and after (never more after), and whether it is still `undoable`. `/actions` lists each change. Reports and actions show only memories whose source you can see. `POST /v2/memory/dreams/{dream_id}/undo` with `{}` takes a dream back, skipping memories that changed since (`conflict_skipped`), until 30 days after it finished or three later dreams of the scope succeed (409 `conflict` after; approved proposals move this later, see below); later dreams do not redo what was undone (each reason on its own), and the dream's open proposals become `withdrawn`. A memory confirmed after the dream counts in `conflict_skipped`. A dream also compares pairs of distilled memories with a model (`d4`): only pairs that mention the same entity and have the same kind or predicate, never events, never two identical sentences. `d4` is `off` until the Space owner turns it on, so a Space spends no model calls by default. Under `d4: "shadow"` it only records its judgments, listed at `GET /v2/memory/dreams/{dream_id}/judgments` (`knowledge:read`, oldest first; `outcome: "shadow"`). Under `propose` a judgment that passes validation becomes an `open` proposal and is reviewed below. The model never writes text that lands in memory: it says how two memories relate and quotes the source verbatim, each quote and date is checked against the current version, and anything else is `discarded` with a `discard_reason` and no text kept. The model is skipped entirely, with the reason in `d4.skipped` of the report, when the deployment has no model (`deployment_off`, `model_not_configured`), the Space is `off`, automatic distillation is off or paused for the tenant, or a rate, token or open-proposal limit is reached; judgments from the last 30 days are reused instead of asking again. Switching `d4` to `propose` proposes from recorded judgments without another model call. Nothing a dream proposes takes effect by itself. To check these judgments by hand, write one JSON object per line in the format `memory-dreaming-label/1`: `{format, dream_id, judgment_id, outcome, kind, member_ids, members: [{memory_id, text}], plan, evidence, label}`, taking the judgment from `/judgments` and each member's `text` from `GET /v2/memories/{memory_id}`. `kind` and `plan` are `null` when the judgment has none, `evidence` is `[]`, `label` is `null` until someone fills in `{correct, fidelity, note_code?}`: `fidelity` is a boolean for a `merge` (what stays still says everything the closed memory said) and `null` otherwise, and `note_code` is one of `wrong_direction`, `different_subject`, `different_condition`, `different_number`, `different_time`, `negation`, `not_entailed`, `evidence_unsupported`, `other`, never free text. Dreams acting without a person, not available yet, needs at least 200 labeled `merge` and `supersede` judgments, fewer than 0.5% of the labeled `supersede` ones wrong, and at least 99% of the labeled `merge` ones faithful. These lines contain your memories' text, so keep the file private. Some changes a dream only proposes and leaves to a person: merging memories that say the same thing, superseding an older one, flagging a contradiction, promoting an Agent's private memory. `GET /v2/spaces/{space_id}/memory/proposals?status=&dream_id=` lists them oldest first (`status` defaults to `open`), `GET /v2/memory/proposals/{proposal_id}` reads one: `kind`, `member_ids`, `proposed_text` (absent for now: dreams do not write new text), verbatim `evidence` and, when there is something to apply, a `plan` with the memory that stays and the ones it replaces. You see a proposal only when you can see the source of every member. `POST /v2/memory/proposals/{proposal_id}/reject` with `{}` closes it without changing any memory, and the same members are not proposed for the same change again; it needs the same rights as undoing a dream of that scope, and a proposal that is no longer open is 409 `proposal_closed`. `POST /v2/memory/proposals/{proposal_id}/approve` with `{}` carries out a `merge` or `supersede` (same rights as `reject`): the memories in `plan.close`, and any other saying the same sentence in that scope, become `superseded` and are not distilled again; `plan.keep` stays with its text unchanged, nothing is rewritten. A merge adds the closed memory's quotes to the kept memory's `GET /v2/memories/{memory_id}/provenance`, each with `merged_from`. Members are checked again first: if one changed since the proposal was written the proposal becomes `stale` and the answer is 409 `proposal_closed`, and approving again gets the same. A `conflict` or `promote` is 422: settle a conflict by correcting or forgetting one side, or reject it. A source being written is 409 `space_busy`. `GET /v2/memories` and `GET /v2/memories/{memory_id}` show `pending_proposals` on memories with open proposals you can see. `counts.superseded` and `counts.merged` and the dream's `/actions` (`action: "supersede" | "merge"`, with `proposal_id` and `target_memory_id`) show what was approved. `POST /v2/memory/dreams/{dream_id}/undo` reverses approved proposals too, within 30 days of the last approval and until three later dreams of the scope succeed after it; a pair undone is not proposed again, and an approval whose memories changed since counts in `conflict_skipped`. The proposal stays `approved`: look at the action's `state`. Forgetting a member, or purging its source, deletes the proposals that quote it; forgetting a memory also forgets what was merged into it, and memories it superseded stay `superseded`. On this deployment distilled memories that say the same sentence in the same Space and scope are one group: `GET /v2/memories` lists a group once, under its smallest id you can see, with `group_id` and `sources` (the members you can see), and pages count groups. Forgetting, correcting and reviewing still take one id; forgetting one also forgets the others that say the same sentence in that scope. `/.mirabase/memory/MEMORY.md` is written differently here: sections for rules and preferences, decisions and progress, and facts; what people wrote first, then confirmed distilled memories (at most 40% of the file), dormant ones never; one memory per line ending in `[m1]`, a `References` table mapping each reference to a memory id, and `… N more: GET /v2/memories?space_id=…` when some did not fit in 2,000 tokens. Its `ETag` starts with `mf2.`. `/.mirabase/memory/RECENT.md` lists the memories written in the Space in the last 7 days, candidates included and marked, newest first, up to 50 lines and 1,000 tokens, with `[r1]` references. Both files show only what you can see, have no dates, and are read-only (405 `virtual_file`). `MEMORY.md` leaves out memories whose text reads as sensitive (health, family, finances, location, religion, politics and the like) without counting them; they stay in `GET /v2/memories`. The MCP tool `mira.memory.get` reads one memory by id, with its provenance unless `include_provenance` is false. ## Available with memory dreaming - GET /v2/spaces/{space_id}/memory/settings - PATCH /v2/spaces/{space_id}/memory/settings - POST /v2/spaces/{space_id}/memory/dreams - GET /v2/spaces/{space_id}/memory/dreams - GET /v2/memory/dreams/{dream_id} - GET /v2/memory/dreams/{dream_id}/actions - GET /v2/memory/dreams/{dream_id}/judgments - POST /v2/memory/dreams/{dream_id}/undo - GET /v2/spaces/{space_id}/memory/proposals - GET /v2/memory/proposals/{proposal_id} - POST /v2/memory/proposals/{proposal_id}/approve - POST /v2/memory/proposals/{proposal_id}/reject ## Memories on retrieval hits On this deployment a hit of `POST /v2/retrieval/search` and an item of `POST /v2/retrieval/context` may carry `memory: {id, kind, text, valid_from?, valid_to?, replaced_by?}`: the confirmed memory that was distilled from that passage. The passage is the evidence, `memory.text` is the statement; `memory.id` is the id of `GET /v2/memories/{memory_id}` (it contains `:`, percent-encode it in a path). At most one per file in a response, and in a context pack it counts toward `tokens_used`. A memory can be history. When the same attribute later took a newer value (the user moved, changed jobs), the older memory is still attached, with `valid_to`, the moment the newer value took effect, and `replaced_by: {id, text}`, the current value. A context item carrying such a memory is flagged `stale`. Before you state a fact from `memory.text`, check `replaced_by`: when it is present, the current answer is `replaced_by.text` and `memory.text` is what used to be true. Without `replaced_by` the memory is the latest value you can read. Values stated in the same conversation batch at the same moment are not ordered against each other. In search results a hit carrying the current value is listed before a hit carrying the value it replaced, whatever their scores, so the first hit is not an outdated one when both are on the page. `GET /v2/memories` and `GET /v2/memories/{memory_id}` carry the same two fields on a distilled memory whose value was replaced. Its `status` stays `confirmed`: it was true, it is not the current value. `MEMORY.md` lists only current values. ## Account approval New accounts on this deployment wait for the owner's approval. Until then you can sign in to the console, create API keys and read these docs, but every API key request answers 403 `account_pending_approval` with remediation action `wait_for_approval`. The console follows the same rule: besides managing keys and viewing the account, its actions (search, context, answer, reprocess, creating or changing Spaces and the team) answer the same 403 until approval. Do not retry in a loop: wait until the account is approved. Approval takes effect on the next request for all of the account's keys, including keys created later. A rejected account answers 403 `account_rejected`.