Files and versions
MarkdownWrite, read, edit, and organize files, compare and revert versions, and handle Agent proposals.
Write a file
PUT /v2/spaces/{space_id}/files creates or replaces a file. The request body is the file. When it returns, the write is committed and readable. Size limits, status codes, and headers are in the reference.
curl -X PUT "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files?path=/notes/hello.md" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: text/markdown" \
--data-binary "Mirabase keeps files, knowledge and memory in one place."- Check
version_createdin the response: it isfalsewhen the bytes and media type are unchanged, and then no version is created and no quota is used. - Without
Content-Type, the file is stored asapplication/octet-stream. - To return only once this version can be searched, send Prefer: wait=N. When the key already holds 4 waiting requests, the call does not wait and the response has no
Preference-Applied. - With a
branchparameter the write goes to a branch instead of main. See Branches and mounts.
Record the time, metadata, and memory switch
A write can also record three things: when the content happened (occurred_at), your own metadata (metadata), and whether memory is distilled from it (memory_exclude). They are kept on the file's Entry and do not change from version to version. The body of a PUT is the file's bytes, so the three travel as query parameters, and metadata is URL-encoded JSON.
# The body is the file, so the three values ride in the query. --url-query (curl 7.87 or newer)
# URL-encodes each one; metadata is a JSON object.
curl -X PUT "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files" \
--url-query "path=/recordings/2026-11-06-standup.m4a" \
--url-query "occurred_at=2026-11-06T09:30:00+08:00" \
--url-query 'metadata={"device":"recorder-01","room":"3f"}' \
--url-query "memory_exclude=true" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: audio/mp4" \
--data-binary @standup.m4a- Only what you send changes: replacing a file leaves the items you did not send as they were. They apply even when the content is unchanged: writing the same bytes again with a new
occurred_atreturnsversion_created: false, and the time is updated. - In each item of a batch and in the completion request of a large file, they are body fields of the same names.
- To change them later, use
PATCH /v2/entries/{entry_id}.
Avoid overwriting changes
Without a condition the last write wins, and the version chain stays intact. To avoid overwriting, send the ETag you read in If-Match; to create only, send If-None-Match: *. The full rules for conditional requests are in API conventions.
# Fails with 412 if someone wrote a newer version since you read this one.
curl -X PUT "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files?path=/notes/hello.md" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H 'If-Match: "ver_2b10"' \
-H "Content-Type: text/markdown" \
--data-binary @hello.md
# Fails with 412 if the file already exists.
curl -X PUT "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files?path=/notes/new.md" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "If-None-Match: *" \
-H "Content-Type: text/markdown" \
--data-binary @new.mdOn 412 precondition_failed, current_version_id in the error is the version now: read the file again, reapply your change, and write with the new ETag.
Edit text
PATCH /v2/spaces/{space_id}/files replaces strings, so you do not send the whole file. It works on UTF-8 text, and each old_text must appear exactly once unless replace_all is set.
curl -X PATCH "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files?path=/notes/hello.md" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"edits": [{"old_text": "one place", "new_text": "a single place"}]}'A failed edit creates no version. On edit_no_match, read the file again and edit; on edit_ambiguous, add context or set replace_all; when the file is too large or not text, replace it with PUT. Error codes and size limits are in the reference.
Read a file
GET /v2/spaces/{space_id}/files reads by path and GET /v2/entries/{entry_id}/content reads by id. Both take the same parameters and read the latest version by default. view selects which form to return; the default is raw bytes. You can read the text view of a text file right after the write; the other views are available after processing finishes.
Send version to read an older version, snapshot to read through a snapshot (see Snapshots), and Range to read part of the bytes. The rules for each parameter are in the reference.
Download URLs
To hand a large file to a browser or another service, sign a short-lived URL for the original bytes with GET /v2/spaces/{space_id}/files/content-url or GET /v2/entries/{entry_id}/content-url. You can fetch the URL without the key.
# A signed URL for the original bytes, valid 60 to 300 seconds. Fetch it without the key.
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files/content-url?path=/videos/talk.mp4&expires_in=120" \
-H "Authorization: Bearer $MIRABASE_API_KEY"Organize directories
GET /v2/spaces/{space_id}/tree lists a directory. POST /v2/spaces/{space_id}/tree/operations runs mkdir, move, copy, delete, and restore in order, and all of them apply or none do.
curl -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/tree/operations" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"operations": [
{"op": "mkdir", "path": "/archive/2026"},
{"op": "move", "from": "/notes/old.md", "to": "/archive/2026/old.md"},
{"op": "copy", "from": "/templates/report.md", "to": "/reports/2026-11.md"},
{"op": "delete", "path": "/drafts", "recursive": true}
]}'toin amoveorcopyis the complete new path. When the target is occupied, the call returns 409path_conflictand nothing is overwritten or merged.- Keep the response's
delete_batch_id: it restores everything that request deleted. - Each copied file is a new Entry, listed in the response's
copies. Its history is not copied, and it is processed like a new file. - A subtree over the synchronous limit returns 409
subtree_too_large: run it as a job; see Run large tree operations as jobs.
Path rules
Paths are absolute: they start with / and have no trailing /. Names compare by NFKC and case folding, so /Docs and /docs are one directory. The full rules for length and characters are in DevPath.
/.mirabase/ is reserved: writing there returns 403 reserved_path. The exception is /.mirabase/skills/<name>/..., which holds your skill files, and context reads their SKILL.md. /.mirabase/memory/MEMORY.md is a generated read-only view; see Memory. On deployments with offline consolidation, so is /.mirabase/memory/RECENT.md; see the index layout.
Run large tree operations as jobs
A single move, copy, recursive delete, or restore by delete_batch_id over the synchronous limit runs as a job when you send Prefer: respond-async, and returns 202 with job_id and Location: /v2/jobs/{job_id}. Follow the job as described in API conventions.
# One operation over the synchronous limit runs as a job: 202 with job_id.
curl -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/tree/operations" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Prefer: respond-async" \
-H "Content-Type: application/json" \
-d '{"operations": [{"op": "delete", "path": "/old-exports", "recursive": true}]}'
# Poll until status is succeeded or failed.
curl "https://api.mirabase.dev/v2/jobs/$JOB_ID" \
-H "Authorization: Bearer $MIRABASE_API_KEY"move is one transaction, but delete, restore, and copy run in chunks and are not atomic: a failed delete job leaves a partly deleted tree, and result.delete_batch_id restores it.Write in a batch
POST /v2/spaces/{space_id}/files/batch writes and deletes several small text files in one request. Each item commits on its own, and one failing does not stop the rest; each result has its own status and matches its item by position.
curl -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files/batch" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Idempotency-Key: import-2026-11-06" \
-H "Content-Type: application/json" \
-d '{"items": [
{"op": "put", "path": "/notes/a.md", "content": "First note", "media_type": "text/markdown"},
{"op": "delete", "path": "/notes/old.md"}
]}'Sending the same Idempotency-Key again finishes a batch that was cut short: committed items replay and the rest run. A single DELETE returns 404 the second time, so use this endpoint when a retry must tell "done" from "never existed".
Upload a large file
Files over 16 MiB go through a multipart upload: start it, get part URLs, PUT each part, then complete it. The path is resolved on completion, and from there it behaves like PUT, including If-Match and If-None-Match: *.
# 1. Start the upload. checksum_sha256 is the Base64 SHA-256 of the whole file.
curl -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/uploads" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"path": "/videos/talk.mp4", "size": 734003200, "media_type": "video/mp4",
"checksum_sha256": "47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU="}'
# 2. Ask for part URLs, at most 128 at a time. Each one lasts five minutes.
curl -X POST "https://api.mirabase.dev/v2/uploads/$UPLOAD_ID/parts" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"part_numbers": [1, 2, 3]}'
# 3. PUT each part to its URL with the returned required_headers, and keep each ETag.
# 4. Finish. The file appears at its path now.
curl -X POST "https://api.mirabase.dev/v2/uploads/$UPLOAD_ID/complete" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"parts": [{"part_number": 1, "etag": "\"9b2c\""}, {"part_number": 2, "etag": "\"71fd\""}]}'- After an interruption, call
POST /v2/uploads/{upload_id}/partsagain: it leaves out the parts already received, so the upload resumes. - Part URLs and the upload session both expire, and after that you must start a new upload. The time limits are in the reference.
Add a source without a path
POST /v2/spaces/{space_id}/ingest adds a URL, text, or a conversation (see Memory) and returns 202 with entry_id, version_id, and job_id. One call makes one Entry, and the same content twice makes two, so send Idempotency-Key when retrying. A URL is fetched after the response, so a bad one shows up as a failed job.
curl -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/ingest" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Idempotency-Key: article-2026-11-06" \
-H "Content-Type: application/json" \
-d '{"kind": "url", "url": "https://example.com/article"}'Text and conversations take redact_secrets, which replaces whatever looks like a credential before anything is stored. It only recognizes credentials with a clear shape, so it is no substitute for your own scrubbing. Conversations also take memory_instructions, which tells distillation what matters in your app.
Compare and revert versions
GET /v2/entries/{entry_id}/versions lists the chain, newest first. POST /v2/entries/{entry_id}/revert writes an older version's content as a new version, without rewriting history.
curl "https://api.mirabase.dev/v2/entries/$ENTRY_ID/versions" \
-H "Authorization: Bearer $MIRABASE_API_KEY"
curl -X POST "https://api.mirabase.dev/v2/entries/$ENTRY_ID/revert" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"version_id": "ver_1a07"}'GET /v2/entries/{entry_id}/diff?from=&to= compares two versions, and GET /v2/entries/{entry_id}/lineage tells where the Entry came from and how each version came about. By path, use GET /v2/spaces/{space_id}/files/diff and GET /v2/spaces/{space_id}/files/lineage.
# Compare an older version with the latest.
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files/diff?path=/notes/hello.md&from=ver_1a07" \
-H "Authorization: Bearer $MIRABASE_API_KEY"
# Where the file came from, and how each version came about.
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files/lineage?path=/notes/hello.md" \
-H "Authorization: Bearer $MIRABASE_API_KEY"An Agent editing a file can record which conversation the change came from: send session_id on PUT and PATCH writes on main, with the same value the conversation was ingested with. lineage shows it on that version, and GET /v2/entries?metadata={"session_id":"…"} finds the conversation later.
changes reports it, so a 200 does not promise the path keeps those bytes. The failed version stays in versions as discarded: read its bytes with version or bring it back with revert. Check knowledge.state when you need to know the new version took.Check processing status
GET /v2/entries/{entry_id}/processing and GET /v2/jobs/{job_id} report processing progress. POST /v2/entries/{entry_id}/reprocess retries a failed version or processes the latest one again. To wait until a file is searchable or follow a bulk import, see Processing status.
Delete and erase
| Operation | Effect | Requires | Undo |
|---|---|---|---|
DELETE a file or Entry | Moves to the trash and leaves search at once | knowledge:write and editor | Yes, with restore |
POST /v2/entries/{entry_id}/purge | Erases the Entry, every version, and its path | knowledge:manage and the Space owner | No |
Handle Agent proposals
When an Agent changes a file it does not own, the call returns 403 proposal_required by default, and nothing is created. It can write directly once the Space owner sets its write_mode to direct; see Permissions. Otherwise, the Agent can send Prefer: handling=proposal to turn the write into a proposal: the file stays as it is, the call returns 202 with proposal_id, and a reviewer decides. File PUT and PATCH, files/batch, the completion of a multipart upload, and branch merges all take this header.
# As the Agent: propose instead of failing with 403 proposal_required.
curl -X PUT "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files?path=/notes/plan.md" \
-H "Authorization: Bearer $AGENT_KEY" \
-H "Prefer: handling=proposal" \
-H "Content-Type: text/markdown" \
--data-binary @plan.md
# As a reviewer: open proposals, what each one changes, then decide.
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/proposals" \
-H "Authorization: Bearer $MIRABASE_API_KEY"
curl "https://api.mirabase.dev/v2/proposals/$PROPOSAL_ID/diff" \
-H "Authorization: Bearer $MIRABASE_API_KEY"
curl -X POST "https://api.mirabase.dev/v2/proposals/$PROPOSAL_ID/approve" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"message": "Agreed plan"}'- It only acts when the write would otherwise return 403: your own files and new files are written directly.
- Moving, deleting, and restoring other people's files,
revert, and memory writes cannot be proposed and still return 403. - Reviewers are the Space owner and editors who can change the file directly: people, and Agents in
directmode with the file inside theirwrite_root. - A proposal is not a version: only its author and the Space owner see the proposed content in
versions, and search never returns it.
Next steps
- Sync, snapshots, and export: keep up with changes to files.
- Retrieval and context: search what you wrote.
- API conventions: the general rules for conditional requests and idempotency.
