Files
MarkdownFiles reached by path: read, write, edit, delete, and their history.
Read a file
GET/v2/spaces/{space_id}/files
view=raw (default) returns bytes, meta the Entry, the rest a content view. version picks an older version, except with meta. A directory returns 404: use tree. text on a text file works right after the write; other views return 404 content_not_ready until processing finishes. With view=raw, Range returns one byte range as 206; a range outside the file returns 416 range_not_satisfiable. Several ranges or a Range the server cannot parse are ignored and return 200 with the whole file. With branch, a path the branch changed is served from the branch and everything else from main's latest; changed paths have raw, meta, and, for text files, text, and take no version. With snapshot, the file is read as the snapshot pinned it, even if it has since changed, moved, or gone to the trash; every view except meta works (meta returns 422 view_not_available), and the response carries Mirabase-Snapshot-Id. /.mirabase/memory/MEMORY.md is a generated, read-only view of this Space's memory for an Agent starting work. The same memories give the same bytes, so it is safe as a prompt-cache prefix. It only has view=raw, has no versions, is not listed in tree, and answers If-None-Match with 304. Writing to it returns 405 virtual_file. On deployments with memory dreaming enabled, MEMORY.md has sections (rules and preferences, decisions and progress, facts), one memory per line ending in a reference such as [m1], and a References table mapping each reference to a memory id; it holds what people wrote and confirmed distilled memories, up to 2,000 tokens, and its ETag starts with mf2.. A second generated file, /.mirabase/memory/RECENT.md, lists the memories written in this Space in the last 7 days, candidates included, newest first, with [r1] references (ETag prefix rf1.); it follows the same rules. Both show only memories you can see, so two callers can get different bytes. Elsewhere RECENT.md is a reserved path. 503 original_unavailable means the stored bytes could not be read right now: retry later. Needs knowledge:read.
Capability knowledge:read
Guide: Files and versions
Parameters
| Name | In | Type | Description |
|---|---|---|---|
space_idRequired | Path | 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.length 1..256 |
pathRequired | Query | 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.length 1..4096 |
branch | Query | DevBranchRef | The branch to use instead of main: its id, or the name of an active branch. For a member with a read_root in this Space, any branch returns 403 outside_read_root. |
snapshot | Query | DevSnapshotRef | A snapshot id or name. Paths, versions, and a read_root are judged as they were when the snapshot was taken; the file must also still be visible to you now. |
view | Query | DevFileView | Which form of the file to return: raw (the default) for its bytes, meta for the Entry, or text, table, or recognized for a processed view. |
version | Query | DevId | The id of a version of this file: read that version instead of the latest. view=meta does not take it and returns 422.length 1..256 |
Range | Header | string | One range: bytes=0-99, bytes=100-, or bytes=-100. Applies to view=raw only; other views ignore it. |
If-Range | Header | string | An ETag. If the file has a newer version, the response is 200 with the whole file instead of a range. |
If-None-Match | Header | string | An ETag you already hold. With view=raw (the default), unchanged bytes return 304 with no body. Other views are not conditional: meta and the processed views change while the version stays the same. |
Responses
200*/*binary,application/jsonDevEntry | DevEntryContent | DevBranchFileMeta | DevBranchFileText | DevEntry | DevEntryContent206*/*binary
Response headers
ETagMirabase-Entry-IdMirabase-Version-IdMirabase-Knowledge-StateLast-ModifiedWhen the content last changed, as an HTTP date. Only when the latest version is served.Mirabase-Snapshot-IdWithsnapshot: the id of the snapshot the file was read from.Mirabase-Branch-IdWithbranch: the id of the branch the read went through.Mirabase-PathWithsnapshot, and withbranchon a path the branch did not change: the path of the file that was served, percent-encoded.Mirabase-Sha256Withbranch, on a file the branch changed: hex SHA-256 of its bytes on the branch.Mirabase-ModeWithbranch, on a path the branch changed: its mode,644or755.Content-RangeAccept-Ranges
Error statuses
400 401 403 404 416 422 429 500 503 See Errors for the error shape and Error codes for what each code means.
Example request
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files?path=/notes/hello.md" \
-H "Authorization: Bearer $MIRABASE_API_KEY"Example response
{
"id": "<id>",
"space_id": "<space_id>",
"title": "Launch notes",
"latest_version_id": "<latest_version_id>",
"metadata": {},
"created_at": "2026-11-06T00:00:00Z",
"updated_at": "2026-11-06T00:00:00Z",
"file": {
"path": "/notes/hello.md",
"size": 1,
"media_type": "<media_type>",
"etag": "<etag>"
},
"knowledge": {
"state": "readable"
},
"memory": {
"scope": "project",
"kind": "<kind>",
"pinned": false,
"exclude": false
},
"memory_exclude": false,
"access": {
"role": "owner",
"capabilities": [
"knowledge:read"
]
}
}Read a file's headers
HEAD/v2/spaces/{space_id}/files
The headers of the latest version, of the file on a branch, or of the version a snapshot pinned, with Content-Type and Content-Length. No body. Needs knowledge:read.
Capability knowledge:read
Parameters
| Name | In | Type | Description |
|---|---|---|---|
space_idRequired | Path | 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.length 1..256 |
pathRequired | Query | 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.length 1..4096 |
branch | Query | DevBranchRef | The branch to use instead of main: its id, or the name of an active branch. For a member with a read_root in this Space, any branch returns 403 outside_read_root. |
snapshot | Query | DevSnapshotRef | A snapshot id or name. Paths, versions, and a read_root are judged as they were when the snapshot was taken; the file must also still be visible to you now. |
Responses
200No response body
Response headers
ETagMirabase-Entry-IdMirabase-Version-IdMirabase-Knowledge-StateLast-ModifiedWhen the content last changed, as an HTTP date. Only when the latest version is served.Mirabase-Snapshot-IdWithsnapshot: the id of the snapshot the file was read from.Mirabase-Branch-IdWithbranch: the id of the branch the read went through.Mirabase-PathWithsnapshot, and withbranchon a path the branch did not change: the path of the file that was served, percent-encoded.Mirabase-Sha256Withbranch, on a file the branch changed: hex SHA-256 of its bytes on the branch.Mirabase-ModeWithbranch, on a path the branch changed: its mode,644or755.
Error statuses
400 401 403 404 422 429 500 503 See Errors for the error shape and Error codes for what each code means.
Example request
curl --head "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files?path=/notes/hello.md" \
-H "Authorization: Bearer $MIRABASE_API_KEY"Write a file
PUT/v2/spaces/{space_id}/files
Create or replace a file, at most 16 MiB. Returns 201 on create and 200 on update, both committed and readable. Without If-Match, the last write wins. The same bytes and media type return 200 with version_created: false. An Agent changing a file it does not own needs write_mode: direct, or the request returns 403 proposal_required; with Prefer: handling=proposal, the write becomes a proposal instead and returns 202 with Preference-Applied: handling=proposal, and the file does not change until a reviewer approves it. If-Match still applies, and identical content still returns 200. A member with a write_root gets 403 outside_write_root for a path outside it. A busy Space returns 409 space_busy with Retry-After. With branch the bytes land on the branch: no version, no processing, no writes until a merge, and the response is DevBranchFileWrite. A write that becomes a proposal cannot carry occurred_at, metadata, or memory_exclude (returns 422). An author holds at most 100 open proposals in a Space; one more returns 409 too_many_open_proposals. A branch holds at most branch_paths paths (GET /v2/limits); a write that would exceed it returns 409 branch_too_large. Needs knowledge:write.
Capability knowledge:write
Guide: Files and versions
Parameters
| Name | In | Type | Description |
|---|---|---|---|
space_idRequired | Path | 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.length 1..256 |
pathRequired | Query | 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.length 1..4096 |
branch | Query | DevBranchRef | The branch to use instead of main: its id, or the name of an active branch. For a member with a read_root in this Space, any branch returns 403 outside_read_root. |
mode | Query | 644 | 755 | The file mode, 644 or 755 (executable). With branch only. Without it a new file is 644 and a changed file keeps its mode. |
session_id | Query | string | Your id for the conversation this change came from, 1 to 256 characters: the same session_id you ingest the conversation with. It is recorded on the version the write creates and shown by lineage, so a later reader can tell which conversation changed the file and look it up. Main only: with branch it returns 422.length 1..256 |
occurred_at | Query | string (date-time) | When the file's content happened, such as when a recording was captured: RFC 3339 with an offset, URL-encoded. Retrieval's occurred_from / occurred_to go by it and passages report it. Only changes when sent. Main only: with branch it returns 422. |
metadata | Query | string | The Entry's metadata as a URL-encoded JSON object, such as {"device":"cam-01"}: the same shape and limits as metadata in a request body. It replaces the Entry's metadata as a whole; leave it out to keep what is there. Main only: with branch it returns 422. |
memory_exclude | Query | boolean | true keeps the file out of memory distillation; false distills it again. The same switch as memory_exclude on PATCH /v2/entries/{id}. Only changes when sent. Main only: with branch it returns 422. |
Idempotency-Key | Header | DevIdempotencyKey | The same Idempotency-Key, principal, API key, operation, and input replay the original result for 24 hours. The same Idempotency-Key with different input returns 409 conflict.length 1..512 |
If-Match | Header | string | One ETag (the version id in quotes): returns 412 unless it matches the latest version. Or *: returns 412 unless the file or Entry exists. Omit for last-write-wins. |
Prefer | Header | string | wait=N, at most 10: hold the response for up to N seconds until this version finishes processing. The write is already committed, so timing out only means knowledge.state has not reached indexed yet. On files writes, handling=proposal turns a write that would be 403 proposal_required into a proposal (202 DevProposalReceipt); anywhere else it changes nothing. Other preferences are ignored. |
If-None-Match | Header | string | * creates only; an existing file fails with 412 precondition_failed. |
Request body
*/* binary
Responses
200application/jsonDevFileWrite | DevBranchFileWrite201application/jsonDevFileWrite | DevBranchFileWrite202application/jsonDevProposalReceipt
Response headers
Preference-Appliedwait=Nwhen the request waited, on operations that takePrefer: wait. Absent when it did not, such as when the key already has 4 requests waiting.handling=proposalwhen a write became a proposal.ETagTheETagof what was just written: send it inIf-Matchon the next write without reading it again.Location/v2/proposals/{proposal_id}: where to read the proposal this write became.
Error statuses
400 401 403 404 405 408 409 410 412 413 415 422 429 500 503 See Errors for the error shape and Error codes for what each code means.
Example request
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 @hello.mdExample response
{
"entry": {
"id": "<id>",
"space_id": "<space_id>",
"title": "Launch notes",
"latest_version_id": "<latest_version_id>",
"metadata": {},
"created_at": "2026-11-06T00:00:00Z",
"updated_at": "2026-11-06T00:00:00Z",
"file": {
"path": "/notes/hello.md",
"size": 1,
"media_type": "<media_type>",
"etag": "<etag>"
},
"knowledge": {
"state": "readable"
},
"memory": {
"scope": "project",
"kind": "<kind>",
"pinned": false,
"exclude": false
},
"memory_exclude": false,
"access": {
"role": "owner",
"capabilities": [
"knowledge:read"
]
}
},
"version_id": "<version_id>",
"version_created": false
}Edit a file's text
PATCH/v2/spaces/{space_id}/files
Apply text edits. An old_text that matches nowhere returns 422 edit_no_match, and one that matches more than once without replace_all returns 422 edit_ambiguous; neither creates a version. Prefer: handling=proposal works as on PUT: the edits apply to the latest version and the whole result is proposed. Needs knowledge:write.
Capability knowledge:write
Guide: Files and versions
Parameters
| Name | In | Type | Description |
|---|---|---|---|
space_idRequired | Path | 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.length 1..256 |
pathRequired | Query | 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.length 1..4096 |
branch | Query | DevBranchRef | The branch to use instead of main: its id, or the name of an active branch. For a member with a read_root in this Space, any branch returns 403 outside_read_root. |
session_id | Query | string | Your id for the conversation this change came from, 1 to 256 characters: the same session_id you ingest the conversation with. It is recorded on the version the write creates and shown by lineage, so a later reader can tell which conversation changed the file and look it up. Main only: with branch it returns 422.length 1..256 |
Idempotency-Key | Header | DevIdempotencyKey | The same Idempotency-Key, principal, API key, operation, and input replay the original result for 24 hours. The same Idempotency-Key with different input returns 409 conflict.length 1..512 |
If-Match | Header | string | One ETag (the version id in quotes): returns 412 unless it matches the latest version. Or *: returns 412 unless the file or Entry exists. Omit for last-write-wins. |
Prefer | Header | string | wait=N, at most 10: hold the response for up to N seconds until this version finishes processing. The write is already committed, so timing out only means knowledge.state has not reached indexed yet. On files writes, handling=proposal turns a write that would be 403 proposal_required into a proposal (202 DevProposalReceipt); anywhere else it changes nothing. Other preferences are ignored. |
Request body
application/json DevFilePatchRequest UTF-8 text files only: anything else returns 415 unsupported_media_type. A file over 1 MiB returns 413 patch_base_too_large, so replace it with PUT. Edits apply in order, each to the result of the one before. A baseline that moves during the request retries once, then returns 412 precondition_failed. With If-Match it does not retry.
| Field | Type | Description |
|---|---|---|
editsRequired | DevFileEdit[] | 1 to 100 edits, applied in order.items 1..100 |
Responses
200application/jsonDevFileWrite | DevBranchFileWrite202application/jsonDevProposalReceipt
Response headers
Preference-Appliedwait=Nwhen the request waited, on operations that takePrefer: wait. Absent when it did not, such as when the key already has 4 requests waiting.handling=proposalwhen a write became a proposal.ETagTheETagof what was just written: send it inIf-Matchon the next write without reading it again.Location/v2/proposals/{proposal_id}: where to read the proposal this write became.
Error statuses
400 401 403 404 405 408 409 410 412 413 415 422 429 500 503 See Errors for the error shape and Error codes for what each code means.
Example request
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":"<old_text>","new_text":"<new_text>"}]}'Example response
{
"entry": {
"id": "<id>",
"space_id": "<space_id>",
"title": "Launch notes",
"latest_version_id": "<latest_version_id>",
"metadata": {},
"created_at": "2026-11-06T00:00:00Z",
"updated_at": "2026-11-06T00:00:00Z",
"file": {
"path": "/notes/hello.md",
"size": 1,
"media_type": "<media_type>",
"etag": "<etag>"
},
"knowledge": {
"state": "readable"
},
"memory": {
"scope": "project",
"kind": "<kind>",
"pinned": false,
"exclude": false
},
"memory_exclude": false,
"access": {
"role": "owner",
"capabilities": [
"knowledge:read"
]
}
},
"version_id": "<version_id>",
"version_created": false
}Delete a file
DELETE/v2/spaces/{space_id}/files
Move a file to the trash: the editor role and knowledge:write are enough. restore in tree/operations brings it back. A second delete returns 404; files/batch takes Idempotency-Key when a retry must tell the two apart. A directory returns 404: use tree/operations. With branch the file is hidden on that branch and main is untouched.
Capability knowledge:write
Guide: Connect an Agent (MCP)
Parameters
| Name | In | Type | Description |
|---|---|---|---|
space_idRequired | Path | 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.length 1..256 |
pathRequired | Query | 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.length 1..4096 |
branch | Query | DevBranchRef | The branch to use instead of main: its id, or the name of an active branch. For a member with a read_root in this Space, any branch returns 403 outside_read_root. |
If-Match | Header | string | One ETag (the version id in quotes): returns 412 unless it matches the latest version. Or *: returns 412 unless the file or Entry exists. Omit for last-write-wins. |
Responses
200application/jsonDevFileDeletion | DevBranchFileDeletion
Error statuses
400 401 403 404 405 408 409 410 412 413 415 422 429 500 503 See Errors for the error shape and Error codes for what each code means.
Example request
curl -X DELETE "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files?path=/notes/hello.md" \
-H "Authorization: Bearer $MIRABASE_API_KEY"Example response
{
"entry_id": "<entry_id>",
"deleted": true
}Write and delete in a batch
POST/v2/spaces/{space_id}/files/batch
Write and delete several text files in one request: 1 to 50 items, each put at most 64 KiB of UTF-8 text, and at most 1 MiB in total (413 payload_too_large over that). Each item commits on its own, in order, and the response has one result per item. Prefer: handling=proposal applies to every put: an item that becomes a proposal has status 202 and proposal. Deletes are never proposals. Needs knowledge:write.
Capability knowledge:write
Guide: Files and versions
Parameters
| Name | In | Type | Description |
|---|---|---|---|
space_idRequired | Path | 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.length 1..256 |
branch | Query | DevBranchRef | The branch to use instead of main: its id, or the name of an active branch. For a member with a read_root in this Space, any branch returns 403 outside_read_root. |
Idempotency-Key | Header | DevIdempotencyKey | The same Idempotency-Key, principal, API key, operation, and input replay the original result for 24 hours. The same Idempotency-Key with different input returns 409 conflict.length 1..512 |
Prefer | Header | string | handling=proposal: a write that would be 403 proposal_required, an Agent in proposal mode changing a file it does not own, becomes a proposal instead. Anywhere else it changes nothing. Other preferences are ignored. |
Request body
application/json DevFileBatchRequest At most 50 items and 1 MiB in total. Each item commits in its own transaction, in order. One failing does not stop the rest: the response is 200 and each result has its own status. With Idempotency-Key, sending the request again finishes it: committed items replay, the rest run. An item whose Entry was purged since replays as 410 gone with path set to /: the write happened, and its receipt was erased with the Entry. Match results to items by position.
| Field | Type | Description |
|---|---|---|
itemsRequired | DevFileBatchItem[] | 1 to 50 writes and deletes, applied in order.items 1..50 |
session_id | string | Your id for the conversation these changes came from, as on PUT files?session_id=: it is recorded on the version each put creates and shown by lineage. Main only: with branch it returns 422.length 1..256 |
Responses
200application/jsonDevFileBatchResponse
Response headers
Preference-Appliedwait=Nwhen the request waited, on operations that takePrefer: wait. Absent when it did not, such as when the key already has 4 requests waiting.handling=proposalwhen a write became a proposal.
Error statuses
400 401 403 404 408 409 410 412 413 415 422 429 500 503 See Errors for the error shape and Error codes for what each code means.
Example request
curl -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files/batch" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"items":[{"op":"put","path":"/notes/hello.md","content":"The launch moved to March 14.\n"}]}'Example response
{
"data": [
{
"path": "/notes/hello.md",
"status": 1
}
]
}Get a file's download URL
GET/v2/spaces/{space_id}/files/content-url
GET /v2/entries/{entry_id}/content-url for the file at path, or for the version a snapshot pinned. branch returns 422: branch bytes have no direct download yet. Needs knowledge:read.
Capability knowledge:read
Guide: Files and versions
Parameters
| Name | In | Type | Description |
|---|---|---|---|
space_idRequired | Path | 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.length 1..256 |
pathRequired | Query | 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.length 1..4096 |
version | Query | DevId | The id of the version to sign a URL for. Defaults to the latest.length 1..256 |
snapshot | Query | DevSnapshotRef | A snapshot id or name. Paths, versions, and a read_root are judged as they were when the snapshot was taken; the file must also still be visible to you now. |
expires_in | Query | integer | How long the URL stays valid, in seconds: 60 to 300, 300 by default.60..300, default: 300 |
Responses
200application/jsonDevContentUrl
Error statuses
400 401 403 404 409 422 429 500 503 See Errors for the error shape and Error codes for what each code means.
Example request
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files/content-url?path=/notes/hello.md" \
-H "Authorization: Bearer $MIRABASE_API_KEY"Example response
{
"url": "https://example.com/article",
"method": "GET",
"expires_at": "2026-11-06T00:00:00Z",
"entry_id": "<entry_id>",
"version_id": "<version_id>",
"size_bytes": 1,
"media_type": "<media_type>"
}Diff versions by path
GET/v2/spaces/{space_id}/files/diff
GET /v2/entries/{entry_id}/diff for the file at path. A branch has its own diff, so branch here returns 422. Needs knowledge:read.
Capability knowledge:read
Guide: Files and versions
Parameters
| Name | In | Type | Description |
|---|---|---|---|
space_idRequired | Path | 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.length 1..256 |
pathRequired | Query | 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.length 1..4096 |
fromRequired | Query | DevId | The id of the version to compare from.length 1..256 |
to | Query | DevId | The id of the version to compare to. Defaults to the latest.length 1..256 |
Responses
200application/jsonDevVersionDiff
Error statuses
400 401 403 404 422 429 500 503 See Errors for the error shape and Error codes for what each code means.
Example request
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files/diff?path=/notes/hello.md&from=<from>" \
-H "Authorization: Bearer $MIRABASE_API_KEY"Example response
{
"entry_id": "<entry_id>",
"from_version_id": "<from_version_id>",
"to_version_id": "<to_version_id>",
"identical": false,
"basis": "original"
}Read lineage by path
GET/v2/spaces/{space_id}/files/lineage
GET /v2/entries/{entry_id}/lineage for the file at path. Needs knowledge:read.
Capability knowledge:read
Guide: Files and versions
Parameters
| Name | In | Type | Description |
|---|---|---|---|
space_idRequired | Path | 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.length 1..256 |
pathRequired | Query | 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.length 1..4096 |
cursor | Query | DevCursor | The next_cursor of the previous page. Omit it to start from the first page.length 1..1024 |
limit | Query | integer | How many items a page holds at most: 1 to 100, 20 by default.1..100, default: 20 |
Responses
200application/jsonDevLineage
Error statuses
400 401 403 404 422 429 500 503 See Errors for the error shape and Error codes for what each code means.
Example request
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files/lineage?path=/notes/hello.md" \
-H "Authorization: Bearer $MIRABASE_API_KEY"Example response
{
"entry_id": "<entry_id>",
"origin": {
"kind": "created"
},
"data": [
{
"version_id": "<version_id>",
"parent_version_ids": [
"<parent_version_ids>"
],
"created_at": "2026-11-06T00:00:00Z",
"kind": "create"
}
]
}Revert by path
POST/v2/spaces/{space_id}/files/revert
POST /v2/entries/{entry_id}/revert for the file at path: write the content of an older version as a new version. Without If-Match, the last write wins; reverting to the latest version creates no new version. The response carries the new ETag. Needs knowledge:write.
Capability knowledge:write
Parameters
| Name | In | Type | Description |
|---|---|---|---|
space_idRequired | Path | 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.length 1..256 |
pathRequired | Query | 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.length 1..4096 |
Idempotency-Key | Header | DevIdempotencyKey | The same Idempotency-Key, principal, API key, operation, and input replay the original result for 24 hours. The same Idempotency-Key with different input returns 409 conflict.length 1..512 |
If-Match | Header | string | One ETag (the version id in quotes): returns 412 unless it matches the latest version. Or *: returns 412 unless the file or Entry exists. Omit for last-write-wins. |
Request body
application/json DevRevertRequest
| Field | Type | Description |
|---|---|---|
version_idRequired | DevId | The id of the version to revert to; its content becomes the new latest version. |
Responses
200application/jsonDevEntry
Response headers
ETagTheETagof what was just written: send it inIf-Matchon the next write without reading it again.
Error statuses
400 401 403 404 408 409 410 412 413 415 422 429 500 503 See Errors for the error shape and Error codes for what each code means.
Example request
curl -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files/revert?path=/notes/hello.md" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"version_id":"<version_id>"}'Example response
{
"id": "<id>",
"space_id": "<space_id>",
"title": "Launch notes",
"latest_version_id": "<latest_version_id>",
"metadata": {},
"created_at": "2026-11-06T00:00:00Z",
"updated_at": "2026-11-06T00:00:00Z",
"file": {
"path": "/notes/hello.md",
"size": 1,
"media_type": "<media_type>",
"etag": "<etag>"
},
"knowledge": {
"state": "readable"
},
"memory": {
"scope": "project",
"kind": "<kind>",
"pinned": false,
"exclude": false
},
"memory_exclude": false,
"access": {
"role": "owner",
"capabilities": [
"knowledge:read"
]
}
}List versions by path
GET/v2/spaces/{space_id}/files/versions
GET /v2/entries/{entry_id}/versions for the file at path: its versions, newest first. Main only: branch returns 422 because a branch has no versions. Needs knowledge:read.
Capability knowledge:read
Parameters
| Name | In | Type | Description |
|---|---|---|---|
space_idRequired | Path | 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.length 1..256 |
pathRequired | Query | 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.length 1..4096 |
cursor | Query | DevCursor | The next_cursor of the previous page. Omit it to start from the first page.length 1..1024 |
limit | Query | integer | How many items a page holds at most: 1 to 100, 20 by default.1..100, default: 20 |
Responses
200application/json
| Field | Type | Description |
|---|---|---|
dataRequired | DevVersion[] | The items on this page. |
next_cursor | DevCursor | Pass it as cursor to get the next page. Absent on the last page. |
Error statuses
400 401 403 404 422 429 500 503 See Errors for the error shape and Error codes for what each code means.
Example request
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files/versions?path=/notes/hello.md" \
-H "Authorization: Bearer $MIRABASE_API_KEY"Example response
{
"data": [
{
"id": "<id>",
"entry_id": "<entry_id>",
"status": "accepted",
"created_at": "2026-11-06T00:00:00Z"
}
]
}