Skip to content
Developer docs
Docs menu

Files 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

NameInTypeDescription
space_idRequiredPathDevSpaceRefA 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
pathRequiredQueryDevPathAbsolute 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
branchQueryDevBranchRefThe 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.
snapshotQueryDevSnapshotRefA 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.
viewQueryDevFileViewWhich 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.
versionQueryDevIdThe 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
RangeHeaderstringOne range: bytes=0-99, bytes=100-, or bytes=-100. Applies to view=raw only; other views ignore it.
If-RangeHeaderstringAn ETag. If the file has a newer version, the response is 200 with the whole file instead of a range.
If-None-MatchHeaderstringAn 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

Response headers

  • ETag
  • Mirabase-Entry-Id
  • Mirabase-Version-Id
  • Mirabase-Knowledge-State
  • Last-Modified When the content last changed, as an HTTP date. Only when the latest version is served.
  • Mirabase-Snapshot-Id With snapshot: the id of the snapshot the file was read from.
  • Mirabase-Branch-Id With branch: the id of the branch the read went through.
  • Mirabase-Path With snapshot, and with branch on a path the branch did not change: the path of the file that was served, percent-encoded.
  • Mirabase-Sha256 With branch, on a file the branch changed: hex SHA-256 of its bytes on the branch.
  • Mirabase-Mode With branch, on a path the branch changed: its mode, 644 or 755.
  • Content-Range
  • Accept-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
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files?path=/notes/hello.md" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

Example response

json
{
  "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

NameInTypeDescription
space_idRequiredPathDevSpaceRefA 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
pathRequiredQueryDevPathAbsolute 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
branchQueryDevBranchRefThe 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.
snapshotQueryDevSnapshotRefA 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

  • 200 No response body

Response headers

  • ETag
  • Mirabase-Entry-Id
  • Mirabase-Version-Id
  • Mirabase-Knowledge-State
  • Last-Modified When the content last changed, as an HTTP date. Only when the latest version is served.
  • Mirabase-Snapshot-Id With snapshot: the id of the snapshot the file was read from.
  • Mirabase-Branch-Id With branch: the id of the branch the read went through.
  • Mirabase-Path With snapshot, and with branch on a path the branch did not change: the path of the file that was served, percent-encoded.
  • Mirabase-Sha256 With branch, on a file the branch changed: hex SHA-256 of its bytes on the branch.
  • Mirabase-Mode With branch, on a path the branch changed: its mode, 644 or 755.

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
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

NameInTypeDescription
space_idRequiredPathDevSpaceRefA 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
pathRequiredQueryDevPathAbsolute 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
branchQueryDevBranchRefThe 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.
modeQuery644 | 755The file mode, 644 or 755 (executable). With branch only. Without it a new file is 644 and a changed file keeps its mode.
session_idQuerystringYour 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_atQuerystring (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.
metadataQuerystringThe 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_excludeQuerybooleantrue 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-KeyHeaderDevIdempotencyKeyThe 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-MatchHeaderstringOne 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.
PreferHeaderstringwait=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-MatchHeaderstring* creates only; an existing file fails with 412 precondition_failed.

Request body

*/* binary

Responses

Response headers

  • Preference-Applied wait=N when the request waited, on operations that take Prefer: wait. Absent when it did not, such as when the key already has 4 requests waiting. handling=proposal when a write became a proposal.
  • ETag The ETag of what was just written: send it in If-Match on 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
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.md

Example response

json
{
  "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

NameInTypeDescription
space_idRequiredPathDevSpaceRefA 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
pathRequiredQueryDevPathAbsolute 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
branchQueryDevBranchRefThe 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_idQuerystringYour 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-KeyHeaderDevIdempotencyKeyThe 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-MatchHeaderstringOne 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.
PreferHeaderstringwait=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.

FieldTypeDescription
editsRequiredDevFileEdit[]1 to 100 edits, applied in order.items 1..100

Responses

Response headers

  • Preference-Applied wait=N when the request waited, on operations that take Prefer: wait. Absent when it did not, such as when the key already has 4 requests waiting. handling=proposal when a write became a proposal.
  • ETag The ETag of what was just written: send it in If-Match on 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
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

json
{
  "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

NameInTypeDescription
space_idRequiredPathDevSpaceRefA 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
pathRequiredQueryDevPathAbsolute 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
branchQueryDevBranchRefThe 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-MatchHeaderstringOne 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

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
curl -X DELETE "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files?path=/notes/hello.md" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

Example response

json
{
  "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

NameInTypeDescription
space_idRequiredPathDevSpaceRefA 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
branchQueryDevBranchRefThe 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-KeyHeaderDevIdempotencyKeyThe 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
PreferHeaderstringhandling=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.

FieldTypeDescription
itemsRequiredDevFileBatchItem[]1 to 50 writes and deletes, applied in order.items 1..50
session_idstringYour 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

Response headers

  • Preference-Applied wait=N when the request waited, on operations that take Prefer: wait. Absent when it did not, such as when the key already has 4 requests waiting. handling=proposal when 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
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

json
{
  "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

NameInTypeDescription
space_idRequiredPathDevSpaceRefA 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
pathRequiredQueryDevPathAbsolute 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
versionQueryDevIdThe id of the version to sign a URL for. Defaults to the latest.length 1..256
snapshotQueryDevSnapshotRefA 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_inQueryintegerHow long the URL stays valid, in seconds: 60 to 300, 300 by default.60..300, default: 300

Responses

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
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files/content-url?path=/notes/hello.md" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

Example response

json
{
  "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

NameInTypeDescription
space_idRequiredPathDevSpaceRefA 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
pathRequiredQueryDevPathAbsolute 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
fromRequiredQueryDevIdThe id of the version to compare from.length 1..256
toQueryDevIdThe id of the version to compare to. Defaults to the latest.length 1..256

Responses

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
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

json
{
  "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

NameInTypeDescription
space_idRequiredPathDevSpaceRefA 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
pathRequiredQueryDevPathAbsolute 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
cursorQueryDevCursorThe next_cursor of the previous page. Omit it to start from the first page.length 1..1024
limitQueryintegerHow many items a page holds at most: 1 to 100, 20 by default.1..100, default: 20

Responses

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
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files/lineage?path=/notes/hello.md" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

Example response

json
{
  "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

NameInTypeDescription
space_idRequiredPathDevSpaceRefA 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
pathRequiredQueryDevPathAbsolute 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-KeyHeaderDevIdempotencyKeyThe 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-MatchHeaderstringOne 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

FieldTypeDescription
version_idRequiredDevIdThe id of the version to revert to; its content becomes the new latest version.

Responses

Response headers

  • ETag The ETag of what was just written: send it in If-Match on 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
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

json
{
  "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

NameInTypeDescription
space_idRequiredPathDevSpaceRefA 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
pathRequiredQueryDevPathAbsolute 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
cursorQueryDevCursorThe next_cursor of the previous page. Omit it to start from the first page.length 1..1024
limitQueryintegerHow many items a page holds at most: 1 to 100, 20 by default.1..100, default: 20

Responses

  • 200 application/json
FieldTypeDescription
dataRequiredDevVersion[]The items on this page.
next_cursorDevCursorPass 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
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files/versions?path=/notes/hello.md" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

Example response

json
{
  "data": [
    {
      "id": "<id>",
      "entry_id": "<entry_id>",
      "status": "accepted",
      "created_at": "2026-11-06T00:00:00Z"
    }
  ]
}