# Files

Files reached by path: read, write, edit, delete, and their history.

API reference. Base URL: `https://api.mirabase.dev`

## 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](https://mirabase.io/developers/files.md#read)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `space_id` | Path | `DevSpaceRef` | Required | 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 |
| `path` | Query | `DevPath` | Required | 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` | Optional | 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` | Optional | 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` | Optional | 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` | Optional | 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` | Optional | One range: `bytes=0-99`, `bytes=100-`, or `bytes=-100`. Applies to `view=raw` only; other views ignore it. |
| `If-Range` | Header | `string` | Optional | 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` | Optional | 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/json` `DevEntry | DevEntryContent | DevBranchFileMeta | DevBranchFileText | DevEntry | DevEntryContent`
- `206` `*/*` `binary`

### 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](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

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

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `space_id` | Path | `DevSpaceRef` | Required | 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 |
| `path` | Query | `DevPath` | Required | 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` | Optional | 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` | Optional | 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

- `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](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

```bash
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`](https://mirabase.io/developers/api/usage.md#usage-limits)); a write that would exceed it returns 409 `branch_too_large`. Needs `knowledge:write`.

**Capability** `knowledge:write`

Guide: [Files and versions](https://mirabase.io/developers/files.md#write)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `space_id` | Path | `DevSpaceRef` | Required | 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 |
| `path` | Query | `DevPath` | Required | 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` | Optional | 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` | Optional | 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` | Optional | 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)` | Optional | 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` | Optional | 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` | Optional | `true` keeps the file out of memory distillation; `false` distills it again. The same switch as `memory_exclude` on [`PATCH /v2/entries/{id}`](https://mirabase.io/developers/api/entries.md#entries-update). Only changes when sent. Main only: with `branch` it returns 422. |
| `Idempotency-Key` | Header | `DevIdempotencyKey` | Optional | 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` | Optional | 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` | Optional | `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` | Optional | `*` creates only; an existing file fails with 412 `precondition_failed`. |

### Request body

`*/*` `binary`

### Responses

- `200` `application/json` `DevFileWrite | DevBranchFileWrite`
- `201` `application/json` `DevFileWrite | DevBranchFileWrite`
- `202` `application/json` `DevProposalReceipt`

### 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](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

```bash
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](https://mirabase.io/developers/files.md#patch)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `space_id` | Path | `DevSpaceRef` | Required | 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 |
| `path` | Query | `DevPath` | Required | 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` | Optional | 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` | Optional | 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` | Optional | 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` | Optional | 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` | Optional | `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 | Required | Description |
| --- | --- | --- | --- |
| `edits` | `DevFileEdit[]` | Required | 1 to 100 edits, applied in order. items 1..100 |

### Responses

- `200` `application/json` `DevFileWrite | DevBranchFileWrite`
- `202` `application/json` `DevProposalReceipt`

### 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](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

```bash
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)](https://mirabase.io/developers/agents.md#tools)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `space_id` | Path | `DevSpaceRef` | Required | 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 |
| `path` | Query | `DevPath` | Required | 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` | Optional | 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` | Optional | 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

- `200` `application/json` `DevFileDeletion | DevBranchFileDeletion`

### Error statuses

`400` `401` `403` `404` `405` `408` `409` `410` `412` `413` `415` `422` `429` `500` `503` See [Errors](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

```bash
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](https://mirabase.io/developers/files.md#batch)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `space_id` | Path | `DevSpaceRef` | Required | 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` | Optional | 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` | Optional | 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` | Optional | `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 | Required | Description |
| --- | --- | --- | --- |
| `items` | `DevFileBatchItem[]` | Required | 1 to 50 writes and deletes, applied in order. items 1..50 |
| `session_id` | `string` | Optional | Your id for the conversation these changes came from, as on `PUT files?session_id=`: it is recorded on the version each `put` creates and shown by `lineage`. Main only: with `branch` it returns 422. length 1..256 |

### Responses

- `200` `application/json` `DevFileBatchResponse`

### 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](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

```bash
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`](https://mirabase.io/developers/api/entries.md#entries-contenturl) 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](https://mirabase.io/developers/files.md#read)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `space_id` | Path | `DevSpaceRef` | Required | 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 |
| `path` | Query | `DevPath` | Required | 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` | Optional | The id of the version to sign a URL for. Defaults to the latest. length 1..256 |
| `snapshot` | Query | `DevSnapshotRef` | Optional | 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` | Optional | How long the URL stays valid, in seconds: 60 to 300, 300 by default. 60..300, default: 300 |

### Responses

- `200` `application/json` `DevContentUrl`

### Error statuses

`400` `401` `403` `404` `409` `422` `429` `500` `503` See [Errors](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

```bash
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`](https://mirabase.io/developers/api/entries.md#entries-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](https://mirabase.io/developers/files.md#versions)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `space_id` | Path | `DevSpaceRef` | Required | 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 |
| `path` | Query | `DevPath` | Required | 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 |
| `from` | Query | `DevId` | Required | The id of the version to compare from. length 1..256 |
| `to` | Query | `DevId` | Optional | The id of the version to compare to. Defaults to the latest. length 1..256 |

### Responses

- `200` `application/json` `DevVersionDiff`

### Error statuses

`400` `401` `403` `404` `422` `429` `500` `503` See [Errors](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

```bash
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`](https://mirabase.io/developers/api/entries.md#entries-lineage) for the file at `path`. Needs `knowledge:read`.

**Capability** `knowledge:read`

Guide: [Files and versions](https://mirabase.io/developers/files.md#versions)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `space_id` | Path | `DevSpaceRef` | Required | 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 |
| `path` | Query | `DevPath` | Required | 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` | Optional | The `next_cursor` of the previous page. Omit it to start from the first page. length 1..1024 |
| `limit` | Query | `integer` | Optional | How many items a page holds at most: 1 to 100, 20 by default. 1..100, default: 20 |

### Responses

- `200` `application/json` `DevLineage`

### Error statuses

`400` `401` `403` `404` `422` `429` `500` `503` See [Errors](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

```bash
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`](https://mirabase.io/developers/api/entries.md#entries-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 | Required | Description |
| --- | --- | --- | --- | --- |
| `space_id` | Path | `DevSpaceRef` | Required | 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 |
| `path` | Query | `DevPath` | Required | 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` | Optional | 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` | Optional | 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 | Required | Description |
| --- | --- | --- | --- |
| `version_id` | `DevId` | Required | The id of the version to revert to; its content becomes the new latest version. |

### Responses

- `200` `application/json` `DevEntry`

### 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](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

```bash
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`](https://mirabase.io/developers/api/entries.md#entries-listversions) 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 | Required | Description |
| --- | --- | --- | --- | --- |
| `space_id` | Path | `DevSpaceRef` | Required | 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 |
| `path` | Query | `DevPath` | Required | 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` | Optional | The `next_cursor` of the previous page. Omit it to start from the first page. length 1..1024 |
| `limit` | Query | `integer` | Optional | How many items a page holds at most: 1 to 100, 20 by default. 1..100, default: 20 |

### Responses

- `200` `application/json`

200 response:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | `DevVersion[]` | Required | The items on this page. |
| `next_cursor` | `DevCursor` | Optional | 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](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

```bash
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"
    }
  ]
}
```
