# Branches

Copy-on-write branches of a Space, with checkpoints, diff, and merge.

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

## List branches

`GET /v2/spaces/{space_id}/branches`

Branches of a Space, in every state, ordered by id. For a member limited to a `read_root`, every branch endpoint returns 403 `outside_read_root`. 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 |
| `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` | `DevBranch[]` | 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/branches" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

### Example response

```json
{
  "data": [
    {
      "id": "<id>",
      "space_id": "<space_id>",
      "name": "research",
      "state": "active",
      "base_change_seq": 1,
      "main_changed_paths": 1,
      "created_by": "<created_by>",
      "ttl_days": 1,
      "expires_at": "2026-11-06T00:00:00Z",
      "created_at": "2026-11-06T00:00:00Z",
      "updated_at": "2026-11-06T00:00:00Z"
    }
  ]
}
```

## Open a branch

`POST /v2/spaces/{space_id}/branches`

Open a branch. Needs write access to the Space and nothing more: `write_mode` applies when you merge, not here. Returns 409 `branch_name_taken` when an active branch already has the name, or 409 `branch_limit_reached` when the Space holds as many active branches as it may. A member with a `read_root` in this Space gets 403 `outside_read_root` here and on every branch endpoint. Copying a branch or a checkpoint that holds more than `branch_paths` paths ([`GET /v2/limits`](https://mirabase.io/developers/api/usage.md#usage-limits)) returns 409 `branch_too_large`. Needs `knowledge:write`.

**Capability** `knowledge:write`

Guide: [Branches and mounts](https://mirabase.io/developers/branches.md#branches)

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

### Request body

`application/json` `DevCreateBranchRequest` `from` copies another active branch, `checkpoint_id` a checkpoint; omit both to start from main. If you send both, `checkpoint_id` must be a checkpoint of the branch in `from`, otherwise it returns 404 `checkpoint_not_found`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | Required | The branch's name, 1 to 255 characters. length 1..255 |
| `from` | `DevId` | Optional | The id of an active branch to copy. |
| `checkpoint_id` | `DevId` | Optional | The id of a checkpoint to copy. |
| `ttl_days` | `integer` | Optional | How many days each write pushes `expires_at` out by, 1 to 365. Omit it for the service default. 1..365 |

### Responses

- `201` `application/json` `DevBranch`

### 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/branches" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"research"}'
```

### Example response

```json
{
  "id": "<id>",
  "space_id": "<space_id>",
  "name": "research",
  "state": "active",
  "base_change_seq": 1,
  "main_changed_paths": 1,
  "created_by": "<created_by>",
  "ttl_days": 1,
  "expires_at": "2026-11-06T00:00:00Z",
  "created_at": "2026-11-06T00:00:00Z",
  "updated_at": "2026-11-06T00:00:00Z"
}
```

## Read a branch

`GET /v2/spaces/{space_id}/branches/{branch_id}`

Read one branch. `main_changed_paths` is the number of paths changed on main since `base_change_seq`. 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 |
| `branch_id` | Path | `DevBranchRef` | Required | A branch id, or the name of an active branch. An id starts with `brn_`. Prefer the id in anything that retries: a name can move to another branch once the first one closes. |

### Responses

- `200` `application/json` `DevBranch`

### 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/branches/$BRANCH_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

### Example response

```json
{
  "id": "<id>",
  "space_id": "<space_id>",
  "name": "research",
  "state": "active",
  "base_change_seq": 1,
  "main_changed_paths": 1,
  "created_by": "<created_by>",
  "ttl_days": 1,
  "expires_at": "2026-11-06T00:00:00Z",
  "created_at": "2026-11-06T00:00:00Z",
  "updated_at": "2026-11-06T00:00:00Z"
}
```

## Rename or renew a branch

`PATCH /v2/spaces/{space_id}/branches/{branch_id}`

Rename a branch, or renew it by setting `ttl_days`. Send at least one field. Needs `knowledge:write`.

**Capability** `knowledge:write`

Guide: [Branches and mounts](https://mirabase.io/developers/branches.md#limits)

### 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_id` | Path | `DevBranchRef` | Required | A branch id, or the name of an active branch. An id starts with `brn_`. Prefer the id in anything that retries: a name can move to another branch once the first one closes. |
| `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 |

### Request body

`application/json` `DevUpdateBranchRequest` Setting `ttl_days` also renews: `expires_at` becomes now plus that many days.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | Optional | A new name, 1 to 255 characters. length 1..255 |
| `ttl_days` | `integer` | Optional | 1 to 365. Setting it also renews the branch: `expires_at` becomes now plus that many days. 1..365 |

### Responses

- `200` `application/json` `DevBranch`

### 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 PATCH "https://api.mirabase.dev/v2/spaces/$SPACE_ID/branches/$BRANCH_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Example response

```json
{
  "id": "<id>",
  "space_id": "<space_id>",
  "name": "research",
  "state": "active",
  "base_change_seq": 1,
  "main_changed_paths": 1,
  "created_by": "<created_by>",
  "ttl_days": 1,
  "expires_at": "2026-11-06T00:00:00Z",
  "created_at": "2026-11-06T00:00:00Z",
  "updated_at": "2026-11-06T00:00:00Z"
}
```

## Abandon a branch

`DELETE /v2/spaces/{space_id}/branches/{branch_id}`

Abandon a branch. It stays readable for 7 days, then is reclaimed. Abandoning it again returns 200 with the branch; a merged branch returns 409 `branch_not_active`. Needs `knowledge:write`.

**Capability** `knowledge:write`

Guide: [Branches and mounts](https://mirabase.io/developers/branches.md#branches)

### 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_id` | Path | `DevBranchRef` | Required | A branch id, or the name of an active branch. An id starts with `brn_`. Prefer the id in anything that retries: a name can move to another branch once the first one closes. |

### Responses

- `200` `application/json` `DevBranch`

### 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 DELETE "https://api.mirabase.dev/v2/spaces/$SPACE_ID/branches/$BRANCH_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

### Example response

```json
{
  "id": "<id>",
  "space_id": "<space_id>",
  "name": "research",
  "state": "active",
  "base_change_seq": 1,
  "main_changed_paths": 1,
  "created_by": "<created_by>",
  "ttl_days": 1,
  "expires_at": "2026-11-06T00:00:00Z",
  "created_at": "2026-11-06T00:00:00Z",
  "updated_at": "2026-11-06T00:00:00Z"
}
```

## List checkpoints

`GET /v2/spaces/{space_id}/branches/{branch_id}/checkpoints`

Checkpoints of a branch, newest first. 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 |
| `branch_id` | Path | `DevBranchRef` | Required | A branch id, or the name of an active branch. An id starts with `brn_`. Prefer the id in anything that retries: a name can move to another branch once the first one closes. |
| `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` | `DevCheckpoint[]` | 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/branches/$BRANCH_ID/checkpoints" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

### Example response

```json
{
  "data": [
    {
      "id": "<id>",
      "branch_id": "<branch_id>",
      "name": "research",
      "node_count": 1,
      "created_by": "<created_by>",
      "created_at": "2026-11-06T00:00:00Z"
    }
  ]
}
```

## Create a checkpoint

`POST /v2/spaces/{space_id}/branches/{branch_id}/checkpoints`

Save the branch's own changes under a name, so `POST .../rollback` can return to them. `git` is an opaque object kept as sent, at most 4 MiB, and a `remote_url` in it must not carry credentials (422). A branch holds at most `branch_checkpoints` checkpoints ([`GET /v2/limits`](https://mirabase.io/developers/api/usage.md#usage-limits)); one more returns 409 `checkpoint_limit_reached`. 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 |
| `branch_id` | Path | `DevBranchRef` | Required | A branch id, or the name of an active branch. An id starts with `brn_`. Prefer the id in anything that retries: a name can move to another branch once the first one closes. |
| `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 |

### Request body

`application/json` `DevCreateCheckpointRequest`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | Required | A name for the checkpoint, 1 to 255 characters. length 1..255 |
| `git` | `DevCheckpointGit` | Optional |  |

### Responses

- `201` `application/json` `DevCheckpoint`

### 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/branches/$BRANCH_ID/checkpoints" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"research"}'
```

### Example response

```json
{
  "id": "<id>",
  "branch_id": "<branch_id>",
  "name": "research",
  "node_count": 1,
  "created_by": "<created_by>",
  "created_at": "2026-11-06T00:00:00Z"
}
```

## Diff a branch

`GET /v2/spaces/{space_id}/branches/{branch_id}/diff`

Paths this branch changed, text files with a unified diff. `path` narrows to a file or a directory. Order is stable, not alphabetical. Needs `knowledge:read`.

**Capability** `knowledge:read`

Guide: [Branches and mounts](https://mirabase.io/developers/branches.md#branches)

### 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_id` | Path | `DevBranchRef` | Required | A branch id, or the name of an active branch. An id starts with `brn_`. Prefer the id in anything that retries: a name can move to another branch once the first one closes. |
| `path` | Query | `DevPath` | Optional | 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` | `DevBranchDiffItem[]` | 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/branches/$BRANCH_ID/diff" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

### Example response

```json
{
  "data": [
    {
      "path": "/notes/hello.md",
      "change": "added",
      "kind": "dir"
    }
  ]
}
```

## Merge a branch

`POST /v2/spaces/{space_id}/branches/{branch_id}/merge`

Write the branch into main, all paths or none, each as a new version with `message`. Requires `Idempotency-Key`. Each path counts as one write. Conflicts return 409 `merge_conflict` with `error.conflicts`. A merge over 1000 paths returns 409 `merge_too_large`; use `paths`, or send `Prefer: respond-async` to run it as a job of up to 10,000 paths (returns 202 with `job_id`). A job plans every path first and fails with `merge_conflict` and `result.conflicts` without writing anything; then it merges 200 paths at a time, so a conflict that appears midway stops it with the merged paths already gone from the branch: merge again for the rest. A branch has one merge job at a time, and while it is queued or running, any merge of that branch and any write that changes the branch's files (file writes, tree operations, uploads, rollback) returns 409 `merge_in_progress`; renaming the branch, creating checkpoints, and abandoning it still work, and abandoning stops the job. An Agent merging a file it does not own needs `write_mode: direct`, or the request returns 403 `proposal_required`; with `Prefer: handling=proposal` its changes to such files become proposals, listed in `proposed_items`, while deleting one still returns 403 `proposal_required` without writing anything. Symlinks do not reach main and are listed in `skipped`. Mode `755` is kept as the metadata key `mirabase.mode`. Needs `knowledge:write`.

**Capability** `knowledge:write`

Guide: [Branches and mounts](https://mirabase.io/developers/branches.md#branches)

### 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_id` | Path | `DevBranchRef` | Required | A branch id, or the name of an active branch. An id starts with `brn_`. Prefer the id in anything that retries: a name can move to another branch once the first one closes. |
| `Idempotency-Key` | Header | `DevIdempotencyKey` | Required | Required here: a merge that was sent twice must not run twice. Reuse the key when you retry. length 1..512 |
| `Prefer` | Header | `string` | Optional | `handling=proposal`: an Agent in `proposal` mode changing a file it does not own proposes the change instead (`proposed_items`). `respond-async`: a merge over 1000 paths runs as a job instead, 202 `DevJobReceipt`. The two can be combined. Other preferences are ignored. |

### Request body

`application/json` `DevMergeRequest` `paths` merges just those paths, directories with everything under them, and the branch stays active; without it the branch ends `merged`. `on_conflict` applies to paths whose main latest is no longer the version the branch started from: `abort` fails the whole merge, `keep_main` skips them, `keep_branch` overwrites main. There is no content merge.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `message` | `string` | Required | 1 to 1000 characters. Recorded as the message of every version the merge writes to main. length 1..1000 |
| `paths` | `DevPath[]` | Optional | Merge only these paths, 1 to 1000 of them; a directory brings everything under it. Omit it to merge the whole branch. items 1..1000 |
| `on_conflict` | `DevMergeConflictPolicy` | Optional | What to do with a path main changed after the branch started from it: `abort`, `keep_main`, or `keep_branch`. default: "abort" |

### Responses

- `200` `application/json` `DevMergeResult`
- `202` `application/json` `DevJobReceipt`

### Response headers

- `Preference-Applied` `respond-async`.
- `Location` `/v2/jobs/{job_id}`: poll it until `status` is `succeeded` or `failed`.

### 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/branches/$BRANCH_ID/merge" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"message":"Move the launch date"}'
```

### Example response

```json
{
  "branch_id": "<branch_id>",
  "state": "active",
  "merged": [
    "/notes/hello.md"
  ],
  "skipped": [
    "/notes/hello.md"
  ],
  "merged_items": [
    {
      "path": "/notes/hello.md",
      "op": "create"
    }
  ],
  "skipped_items": [
    {
      "path": "/notes/hello.md",
      "reason": "symlink"
    }
  ]
}
```

## Read a branch object

`GET /v2/spaces/{space_id}/branches/{branch_id}/objects/{sha256}`

Read the object's bytes. Supports `Range` requests. Works on merged and abandoned branches until they are reclaimed. 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 |
| `branch_id` | Path | `DevBranchRef` | Required | A branch id, or the name of an active branch. An id starts with `brn_`. Prefer the id in anything that retries: a name can move to another branch once the first one closes. |
| `sha256` | Path | `string` | Required | Lowercase hex SHA-256 of the object, 64 characters: the name it was stored under. |
| `Range` | Header | `string` | Optional | One byte range (`bytes=0-99`, `bytes=100-`, or `bytes=-100`). Returns 206 with that slice of the object. |

### Responses

- `200` `application/octet-stream` `binary`
- `206` `application/octet-stream` `binary`

### Response headers

- `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/branches/$BRANCH_ID/objects/$SHA256" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

## Check a branch object

`HEAD /v2/spaces/{space_id}/branches/{branch_id}/objects/{sha256}`

Check whether the branch holds an object without reading its bytes. Returns 200 with `Content-Length` when it does, or returns 404 `object_not_found` when it does not. Works on merged and abandoned branches until they are reclaimed. 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 |
| `branch_id` | Path | `DevBranchRef` | Required | A branch id, or the name of an active branch. An id starts with `brn_`. Prefer the id in anything that retries: a name can move to another branch once the first one closes. |
| `sha256` | Path | `string` | Required | Lowercase hex SHA-256 of the object, 64 characters: the name it was stored under. |

### Responses

- `200` No response body

### Response headers

- `Content-Length`

### 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/branches/$BRANCH_ID/objects/$SHA256" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

## Write a branch object

`PUT /v2/spaces/{space_id}/branches/{branch_id}/objects/{sha256}`

Store an opaque object, at most 16 MiB. Objects hold Git bundles and overlays: they are not paths, do not appear in `tree` or `changes`, are not merged, parsed, or indexed, and count toward `storage_bytes`. A body that does not hash to `sha256` returns 422 `checksum_mismatch`. Returns 201 with `created: true` for a new object, or 200 with `created: false` if the branch already has it. An inactive branch returns 409 `branch_not_active`. Needs `knowledge:write`.

**Capability** `knowledge:write`

Guide: [Branches and mounts](https://mirabase.io/developers/branches.md#objects)

### 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_id` | Path | `DevBranchRef` | Required | A branch id, or the name of an active branch. An id starts with `brn_`. Prefer the id in anything that retries: a name can move to another branch once the first one closes. |
| `sha256` | Path | `string` | Required | Lowercase hex SHA-256 of the body, 64 characters. The object is stored under it. |

### Request body

`*/*` `binary`

### Responses

- `200` `application/json` `DevBranchObject`
- `201` `application/json` `DevBranchObject`

### 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 PUT "https://api.mirabase.dev/v2/spaces/$SPACE_ID/branches/$BRANCH_ID/objects/$SHA256" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @object.bin
```

### Example response

```json
{
  "branch_id": "<branch_id>",
  "sha256": "<sha256>",
  "size": 1,
  "created": false
}
```

## Roll back to a checkpoint

`POST /v2/spaces/{space_id}/branches/{branch_id}/rollback`

Return to a checkpoint of this branch. Later checkpoints stay, so a rollback can be undone. Older `changes` cursors for this branch then return 410 `cursor_expired`. 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 |
| `branch_id` | Path | `DevBranchRef` | Required | A branch id, or the name of an active branch. An id starts with `brn_`. Prefer the id in anything that retries: a name can move to another branch once the first one closes. |
| `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 |

### Request body

`application/json` `DevRollbackRequest`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `checkpoint_id` | `DevId` | Required | The id of the checkpoint to roll back to. |

### Responses

- `200` `application/json` `DevBranch`

### 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/branches/$BRANCH_ID/rollback" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"checkpoint_id":"<checkpoint_id>"}'
```

### Example response

```json
{
  "id": "<id>",
  "space_id": "<space_id>",
  "name": "research",
  "state": "active",
  "base_change_seq": 1,
  "main_changed_paths": 1,
  "created_by": "<created_by>",
  "ttl_days": 1,
  "expires_at": "2026-11-06T00:00:00Z",
  "created_at": "2026-11-06T00:00:00Z",
  "updated_at": "2026-11-06T00:00:00Z"
}
```
