# 分支

Space 的写时复制分支，带检查点、对比和合并。

API 参考。Base URL：`https://api.mirabase.dev`

## 列出分支

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

Space 下所有状态的分支，按 id 排序。受 `read_root` 限制的成员调用任何分支接口均返回 403 `outside_read_root`。需要 `knowledge:read`。

**需要的能力** `knowledge:read`

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `space_id` | 路径 | `DevSpaceRef` | 必填 | Space id；`default` 表示你的默认 Space（你自己的默认 Space，否则为唯一可见的 Space）；或 `ext:<external_id>`，表示带有你为它设定的 id 的 Space，例如 `ext:user-42`。三种写法均可用于路径、`?space_id=` 和 `space_ids`。没有可见的 Space 带有该 `external_id` 时返回 404。 长度 1 到 256 |
| `cursor` | 查询 | `DevCursor` | 可选 | 上一页的 `next_cursor`。不传则从第一页开始。 长度 1 到 1024 |
| `limit` | 查询 | `integer` | 可选 | 每页最多返回的条目数：1 到 100，默认 20。 1 到 100，默认 20 |

### 响应

- `200` `application/json`

200 响应：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `data` | `DevBranch[]` | 必填 | 这一页的条目。 |
| `next_cursor` | `DevCursor` | 可选 | 作为 `cursor` 传入以获取下一页。最后一页不返回该字段。 |

### 错误状态

`400` `401` `403` `404` `422` `429` `500` `503` 错误结构见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)，各错误码的含义见 [错误码](https://mirabase.io/zh/developers/errors.md)。

### 请求示例

```bash
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/branches" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

### 响应结构示例

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

## 创建分支

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

创建分支。只需要 Space 写入权限：`write_mode` 在合并时生效，此处不适用。同名活跃分支已存在时返回 409 `branch_name_taken`；Space 的活跃分支数达到上限时返回 409 `branch_limit_reached`。在这个 Space 设有 `read_root` 的成员，调用此接口和所有分支接口时都会收到 403 `outside_read_root`。复制的分支或检查点里路径超过 `branch_paths` 个（见 [`GET /v2/limits`](https://mirabase.io/zh/developers/api/usage.md#usage-limits)）时返回 409 `branch_too_large`。需要 `knowledge:write`。

**需要的能力** `knowledge:write`

指南：[分支与挂载](https://mirabase.io/zh/developers/branches.md#branches)

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `space_id` | 路径 | `DevSpaceRef` | 必填 | Space id；`default` 表示你的默认 Space（你自己的默认 Space，否则为唯一可见的 Space）；或 `ext:<external_id>`，表示带有你为它设定的 id 的 Space，例如 `ext:user-42`。三种写法均可用于路径、`?space_id=` 和 `space_ids`。没有可见的 Space 带有该 `external_id` 时返回 404。 长度 1 到 256 |
| `Idempotency-Key` | 请求头 | `DevIdempotencyKey` | 可选 | `Idempotency-Key`、主体、API Key、操作和输入都相同时，24 小时内重放原结果。同一个 `Idempotency-Key` 搭配不同输入时返回 409 `conflict`。 长度 1 到 512 |

### 请求体

`application/json` `DevCreateBranchRequest` `from` 复制另一个活跃分支，`checkpoint_id` 复制一个检查点。两者都不传时从主线创建。同时传两者时，`checkpoint_id` 必须是 `from` 所指分支的检查点，否则返回 404 `checkpoint_not_found`。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `name` | `string` | 必填 | 分支的名称，1 到 255 个字符。 长度 1 到 255 |
| `from` | `DevId` | 可选 | 要复制的活跃分支的 id。 |
| `checkpoint_id` | `DevId` | 可选 | 要复制的检查点的 id。 |
| `ttl_days` | `integer` | 可选 | 每次写入把 `expires_at` 推后的天数，1 到 365。不传则使用服务默认值。 1 到 365 |

### 响应

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

### 错误状态

`400` `401` `403` `404` `408` `409` `410` `412` `413` `415` `422` `429` `500` `503` 错误结构见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)，各错误码的含义见 [错误码](https://mirabase.io/zh/developers/errors.md)。

### 请求示例

```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"}'
```

### 响应结构示例

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

## 读取分支

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

读取一个分支。`main_changed_paths` 表示自 `base_change_seq` 以来主线发生变更的路径数。需要 `knowledge:read`。

**需要的能力** `knowledge:read`

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `space_id` | 路径 | `DevSpaceRef` | 必填 | Space id；`default` 表示你的默认 Space（你自己的默认 Space，否则为唯一可见的 Space）；或 `ext:<external_id>`，表示带有你为它设定的 id 的 Space，例如 `ext:user-42`。三种写法均可用于路径、`?space_id=` 和 `space_ids`。没有可见的 Space 带有该 `external_id` 时返回 404。 长度 1 到 256 |
| `branch_id` | 路径 | `DevBranchRef` | 必填 | 分支 id，或活跃分支的名字。id 以 `brn_` 开头。会重试的调用里请用 id：第一个分支关闭后，名字可能指向另一个分支。 |

### 响应

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

### 错误状态

`400` `401` `403` `404` `422` `429` `500` `503` 错误结构见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)，各错误码的含义见 [错误码](https://mirabase.io/zh/developers/errors.md)。

### 请求示例

```bash
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/branches/$BRANCH_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

### 响应结构示例

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

## 重命名或续期分支

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

重命名分支，或通过设置 `ttl_days` 续期。至少传一个字段。需要 `knowledge:write`。

**需要的能力** `knowledge:write`

指南：[分支与挂载](https://mirabase.io/zh/developers/branches.md#limits)

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `space_id` | 路径 | `DevSpaceRef` | 必填 | Space id；`default` 表示你的默认 Space（你自己的默认 Space，否则为唯一可见的 Space）；或 `ext:<external_id>`，表示带有你为它设定的 id 的 Space，例如 `ext:user-42`。三种写法均可用于路径、`?space_id=` 和 `space_ids`。没有可见的 Space 带有该 `external_id` 时返回 404。 长度 1 到 256 |
| `branch_id` | 路径 | `DevBranchRef` | 必填 | 分支 id，或活跃分支的名字。id 以 `brn_` 开头。会重试的调用里请用 id：第一个分支关闭后，名字可能指向另一个分支。 |
| `Idempotency-Key` | 请求头 | `DevIdempotencyKey` | 可选 | `Idempotency-Key`、主体、API Key、操作和输入都相同时，24 小时内重放原结果。同一个 `Idempotency-Key` 搭配不同输入时返回 409 `conflict`。 长度 1 到 512 |

### 请求体

`application/json` `DevUpdateBranchRequest` 设置 `ttl_days` 同时续期：`expires_at` 更新为当前时间加上该天数。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `name` | `string` | 可选 | 新名字，1 到 255 个字符。 长度 1 到 255 |
| `ttl_days` | `integer` | 可选 | 1 到 365。设置后同时为分支续期：`expires_at` 更新为当前时间加上该天数。 1 到 365 |

### 响应

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

### 错误状态

`400` `401` `403` `404` `408` `409` `410` `412` `413` `415` `422` `429` `500` `503` 错误结构见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)，各错误码的含义见 [错误码](https://mirabase.io/zh/developers/errors.md)。

### 请求示例

```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 '{}'
```

### 响应结构示例

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

## 放弃分支

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

放弃分支。分支在 7 天内仍可读取，随后回收。对已放弃的分支重复调用仍返回 200；对已合并的分支调用返回 409 `branch_not_active`。需要 `knowledge:write`。

**需要的能力** `knowledge:write`

指南：[分支与挂载](https://mirabase.io/zh/developers/branches.md#branches)

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `space_id` | 路径 | `DevSpaceRef` | 必填 | Space id；`default` 表示你的默认 Space（你自己的默认 Space，否则为唯一可见的 Space）；或 `ext:<external_id>`，表示带有你为它设定的 id 的 Space，例如 `ext:user-42`。三种写法均可用于路径、`?space_id=` 和 `space_ids`。没有可见的 Space 带有该 `external_id` 时返回 404。 长度 1 到 256 |
| `branch_id` | 路径 | `DevBranchRef` | 必填 | 分支 id，或活跃分支的名字。id 以 `brn_` 开头。会重试的调用里请用 id：第一个分支关闭后，名字可能指向另一个分支。 |

### 响应

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

### 错误状态

`400` `401` `403` `404` `408` `409` `410` `412` `413` `415` `422` `429` `500` `503` 错误结构见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)，各错误码的含义见 [错误码](https://mirabase.io/zh/developers/errors.md)。

### 请求示例

```bash
curl -X DELETE "https://api.mirabase.dev/v2/spaces/$SPACE_ID/branches/$BRANCH_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

### 响应结构示例

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

## 列出检查点

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

分支的检查点，最新的在前。需要 `knowledge:read`。

**需要的能力** `knowledge:read`

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `space_id` | 路径 | `DevSpaceRef` | 必填 | Space id；`default` 表示你的默认 Space（你自己的默认 Space，否则为唯一可见的 Space）；或 `ext:<external_id>`，表示带有你为它设定的 id 的 Space，例如 `ext:user-42`。三种写法均可用于路径、`?space_id=` 和 `space_ids`。没有可见的 Space 带有该 `external_id` 时返回 404。 长度 1 到 256 |
| `branch_id` | 路径 | `DevBranchRef` | 必填 | 分支 id，或活跃分支的名字。id 以 `brn_` 开头。会重试的调用里请用 id：第一个分支关闭后，名字可能指向另一个分支。 |
| `cursor` | 查询 | `DevCursor` | 可选 | 上一页的 `next_cursor`。不传则从第一页开始。 长度 1 到 1024 |
| `limit` | 查询 | `integer` | 可选 | 每页最多返回的条目数：1 到 100，默认 20。 1 到 100，默认 20 |

### 响应

- `200` `application/json`

200 响应：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `data` | `DevCheckpoint[]` | 必填 | 这一页的条目。 |
| `next_cursor` | `DevCursor` | 可选 | 作为 `cursor` 传入以获取下一页。最后一页不返回该字段。 |

### 错误状态

`400` `401` `403` `404` `422` `429` `500` `503` 错误结构见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)，各错误码的含义见 [错误码](https://mirabase.io/zh/developers/errors.md)。

### 请求示例

```bash
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/branches/$BRANCH_ID/checkpoints" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

### 响应结构示例

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

## 创建检查点

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

把分支自己的改动以一个名称保存下来，之后 `POST .../rollback` 可以回到这里。`git` 是一个不透明对象，按原样保存，最大 4 MiB，其中的 `remote_url` 不能带凭据（422）。一个分支最多有 `branch_checkpoints` 个检查点（见 [`GET /v2/limits`](https://mirabase.io/zh/developers/api/usage.md#usage-limits)），再多一个返回 409 `checkpoint_limit_reached`。需要 `knowledge:write`。

**需要的能力** `knowledge:write`

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `space_id` | 路径 | `DevSpaceRef` | 必填 | Space id；`default` 表示你的默认 Space（你自己的默认 Space，否则为唯一可见的 Space）；或 `ext:<external_id>`，表示带有你为它设定的 id 的 Space，例如 `ext:user-42`。三种写法均可用于路径、`?space_id=` 和 `space_ids`。没有可见的 Space 带有该 `external_id` 时返回 404。 长度 1 到 256 |
| `branch_id` | 路径 | `DevBranchRef` | 必填 | 分支 id，或活跃分支的名字。id 以 `brn_` 开头。会重试的调用里请用 id：第一个分支关闭后，名字可能指向另一个分支。 |
| `Idempotency-Key` | 请求头 | `DevIdempotencyKey` | 可选 | `Idempotency-Key`、主体、API Key、操作和输入都相同时，24 小时内重放原结果。同一个 `Idempotency-Key` 搭配不同输入时返回 409 `conflict`。 长度 1 到 512 |

### 请求体

`application/json` `DevCreateCheckpointRequest`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `name` | `string` | 必填 | 检查点的名字，1 到 255 个字符。 长度 1 到 255 |
| `git` | `DevCheckpointGit` | 可选 |  |

### 响应

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

### 错误状态

`400` `401` `403` `404` `408` `409` `410` `412` `413` `415` `422` `429` `500` `503` 错误结构见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)，各错误码的含义见 [错误码](https://mirabase.io/zh/developers/errors.md)。

### 请求示例

```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"}'
```

### 响应结构示例

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

## 查看分支改动

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

列出该分支修改过的路径，文本文件附带统一 diff。`path` 可将范围限定为单个文件或目录。返回顺序固定，但不按字母顺序排列。需要 `knowledge:read`。

**需要的能力** `knowledge:read`

指南：[分支与挂载](https://mirabase.io/zh/developers/branches.md#branches)

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `space_id` | 路径 | `DevSpaceRef` | 必填 | Space id；`default` 表示你的默认 Space（你自己的默认 Space，否则为唯一可见的 Space）；或 `ext:<external_id>`，表示带有你为它设定的 id 的 Space，例如 `ext:user-42`。三种写法均可用于路径、`?space_id=` 和 `space_ids`。没有可见的 Space 带有该 `external_id` 时返回 404。 长度 1 到 256 |
| `branch_id` | 路径 | `DevBranchRef` | 必填 | 分支 id，或活跃分支的名字。id 以 `brn_` 开头。会重试的调用里请用 id：第一个分支关闭后，名字可能指向另一个分支。 |
| `path` | 查询 | `DevPath` | 可选 | Space 内的绝对路径：以 `/` 开头，名字之间用单个 `/` 连接，结尾不带 `/`。最多 64 层、4096 字节，单个名字最多 255 字节。名称按 NFKC 和大小写折叠比较，并保留写入时的拼写。不允许 `.`、`..`、控制字符、反斜杠和首尾空白。`/.mirabase/` 是保留路径，`/.mirabase/skills/<name>/...` 除外。路径超出这些限制时返回 422 `path_too_long`。 长度 1 到 4096 |
| `cursor` | 查询 | `DevCursor` | 可选 | 上一页的 `next_cursor`。不传则从第一页开始。 长度 1 到 1024 |
| `limit` | 查询 | `integer` | 可选 | 每页最多返回的条目数：1 到 100，默认 20。 1 到 100，默认 20 |

### 响应

- `200` `application/json`

200 响应：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `data` | `DevBranchDiffItem[]` | 必填 | 这一页的条目。 |
| `next_cursor` | `DevCursor` | 可选 | 作为 `cursor` 传入以获取下一页。最后一页不返回该字段。 |

### 错误状态

`400` `401` `403` `404` `422` `429` `500` `503` 错误结构见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)，各错误码的含义见 [错误码](https://mirabase.io/zh/developers/errors.md)。

### 请求示例

```bash
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/branches/$BRANCH_ID/diff" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

### 响应结构示例

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

## 合并分支

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

把分支写入主线，全部生效或全部不生效，每个路径产生一个带 `message` 的新版本。必须提供 `Idempotency-Key`。每个路径计一次写入。发生冲突时，接口返回 409 `merge_conflict`，冲突列在 `error.conflicts`。超过 1000 个路径时，接口返回 409 `merge_too_large`：用 `paths` 分批，或者带 `Prefer: respond-async` 作为任务执行，最多 10000 个路径（接口返回 202 和 `job_id`）。任务先规划全部路径，有冲突时以 `merge_conflict` 失败，冲突列在 `result.conflicts`，不写入任何内容；然后每批合并 200 个路径，所以中途出现的冲突会让任务停止，已合并的路径已从分支移除：再次合并以处理剩余路径。一个分支同时只有一个合并任务，任务排队或运行期间，对这个分支的任何合并，以及任何修改分支文件的写入（文件写入、目录操作、上传、回滚），接口都返回 409 `merge_in_progress`；重命名分支、创建检查点和放弃分支仍然可用，放弃分支会让任务停止。Agent 合并不属于自己的文件需要 `write_mode: direct`，否则接口返回 403 `proposal_required`；带 `Prefer: handling=proposal` 时，Agent 对这类文件的修改变成提案，列在 `proposed_items`，但删除这类文件时，接口仍返回 403 `proposal_required`，不写入任何内容。符号链接不进入主线，列在 `skipped` 里。权限位 `755` 保存为元数据键 `mirabase.mode`。需要 `knowledge:write`。

**需要的能力** `knowledge:write`

指南：[分支与挂载](https://mirabase.io/zh/developers/branches.md#branches)

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `space_id` | 路径 | `DevSpaceRef` | 必填 | Space id；`default` 表示你的默认 Space（你自己的默认 Space，否则为唯一可见的 Space）；或 `ext:<external_id>`，表示带有你为它设定的 id 的 Space，例如 `ext:user-42`。三种写法均可用于路径、`?space_id=` 和 `space_ids`。没有可见的 Space 带有该 `external_id` 时返回 404。 长度 1 到 256 |
| `branch_id` | 路径 | `DevBranchRef` | 必填 | 分支 id，或活跃分支的名字。id 以 `brn_` 开头。会重试的调用里请用 id：第一个分支关闭后，名字可能指向另一个分支。 |
| `Idempotency-Key` | 请求头 | `DevIdempotencyKey` | 必填 | 此处必填，防止重复发送的合并请求执行两次。重试时请沿用同一个键。 长度 1 到 512 |
| `Prefer` | 请求头 | `string` | 可选 | `handling=proposal`：`proposal` 模式的 Agent 修改不属于自己的文件时，改为提交提案（`proposed_items`）。`respond-async`：超过 1000 个路径的合并改为任务执行，接口返回 202 `DevJobReceipt`。两者可以一起用。其他偏好会被忽略。 |

### 请求体

`application/json` `DevMergeRequest` `paths` 只合并这些路径，目录连同下面的全部内容，分支保持活跃；不传时合并后分支变为 `merged`。`on_conflict` 作用于主线最新版本已不是分支起点版本的路径：`abort` 让整次合并失败，`keep_main` 跳过它们，`keep_branch` 覆盖主线。不做内容合并。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `message` | `string` | 必填 | 1 到 1000 个字符。记为本次合并写入主线的每个版本的说明。 长度 1 到 1000 |
| `paths` | `DevPath[]` | 可选 | 只合并这些路径，1 到 1000 个；目录会包含其下的全部内容。不传则合并整个分支。 1 到 1000 项 |
| `on_conflict` | `DevMergeConflictPolicy` | 可选 | 对分支起点之后主线又修改过的路径的处理方式：`abort`、`keep_main` 或 `keep_branch`。 默认 "abort" |

### 响应

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

### 响应头

- `Preference-Applied` `respond-async`。
- `Location` `/v2/jobs/{job_id}`：轮询它，直到 `status` 变成 `succeeded` 或 `failed`。

### 错误状态

`400` `401` `403` `404` `408` `409` `410` `412` `413` `415` `422` `429` `500` `503` 错误结构见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)，各错误码的含义见 [错误码](https://mirabase.io/zh/developers/errors.md)。

### 请求示例

```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"}'
```

### 响应结构示例

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

## 读取分支对象

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

读取对象的字节。支持 `Range` 请求。分支已合并或已放弃时，在回收之前仍可读。需要 `knowledge:read`。

**需要的能力** `knowledge:read`

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `space_id` | 路径 | `DevSpaceRef` | 必填 | Space id；`default` 表示你的默认 Space（你自己的默认 Space，否则为唯一可见的 Space）；或 `ext:<external_id>`，表示带有你为它设定的 id 的 Space，例如 `ext:user-42`。三种写法均可用于路径、`?space_id=` 和 `space_ids`。没有可见的 Space 带有该 `external_id` 时返回 404。 长度 1 到 256 |
| `branch_id` | 路径 | `DevBranchRef` | 必填 | 分支 id，或活跃分支的名字。id 以 `brn_` 开头。会重试的调用里请用 id：第一个分支关闭后，名字可能指向另一个分支。 |
| `sha256` | 路径 | `string` | 必填 | 对象的小写十六进制 SHA-256（64 个字符），也是对象存储时使用的名称。 |
| `Range` | 请求头 | `string` | 可选 | 一个区间：`bytes=0-99`、`bytes=100-` 或 `bytes=-100`。响应返回 206 和对象的这一部分。 |

### 响应

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

### 响应头

- `Content-Range`
- `Accept-Ranges`

### 错误状态

`400` `401` `403` `404` `416` `422` `429` `500` `503` 错误结构见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)，各错误码的含义见 [错误码](https://mirabase.io/zh/developers/errors.md)。

### 请求示例

```bash
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/branches/$BRANCH_ID/objects/$SHA256" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

## 检查分支对象

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

不读取字节，检查分支中是否存在该对象：存在时返回 200 并附带 `Content-Length`；不存在时返回 404 `object_not_found`。分支已合并或已放弃时，在回收之前仍可用。需要 `knowledge:read`。

**需要的能力** `knowledge:read`

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `space_id` | 路径 | `DevSpaceRef` | 必填 | Space id；`default` 表示你的默认 Space（你自己的默认 Space，否则为唯一可见的 Space）；或 `ext:<external_id>`，表示带有你为它设定的 id 的 Space，例如 `ext:user-42`。三种写法均可用于路径、`?space_id=` 和 `space_ids`。没有可见的 Space 带有该 `external_id` 时返回 404。 长度 1 到 256 |
| `branch_id` | 路径 | `DevBranchRef` | 必填 | 分支 id，或活跃分支的名字。id 以 `brn_` 开头。会重试的调用里请用 id：第一个分支关闭后，名字可能指向另一个分支。 |
| `sha256` | 路径 | `string` | 必填 | 对象的小写十六进制 SHA-256（64 个字符），也是对象存储时使用的名称。 |

### 响应

- `200` 无响应体

### 响应头

- `Content-Length`

### 错误状态

`400` `401` `403` `404` `422` `429` `500` `503` 错误结构见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)，各错误码的含义见 [错误码](https://mirabase.io/zh/developers/errors.md)。

### 请求示例

```bash
curl --head "https://api.mirabase.dev/v2/spaces/$SPACE_ID/branches/$BRANCH_ID/objects/$SHA256" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

## 写入分支对象

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

存储一个不透明对象，最大 16 MiB。对象用于存储 Git bundle 和 overlay：它们不是路径，不出现在 `tree` 和 `changes` 中，不合并、不解析、不索引，计入 `storage_bytes`。请求体的哈希与 `sha256` 不符时返回 422 `checksum_mismatch`。首次写入返回 201（`created: true`），写入分支已有的对象返回 200（`created: false`）。分支不是活跃状态返回 409 `branch_not_active`。需要 `knowledge:write`。

**需要的能力** `knowledge:write`

指南：[分支与挂载](https://mirabase.io/zh/developers/branches.md#objects)

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `space_id` | 路径 | `DevSpaceRef` | 必填 | Space id；`default` 表示你的默认 Space（你自己的默认 Space，否则为唯一可见的 Space）；或 `ext:<external_id>`，表示带有你为它设定的 id 的 Space，例如 `ext:user-42`。三种写法均可用于路径、`?space_id=` 和 `space_ids`。没有可见的 Space 带有该 `external_id` 时返回 404。 长度 1 到 256 |
| `branch_id` | 路径 | `DevBranchRef` | 必填 | 分支 id，或活跃分支的名字。id 以 `brn_` 开头。会重试的调用里请用 id：第一个分支关闭后，名字可能指向另一个分支。 |
| `sha256` | 路径 | `string` | 必填 | 请求体的小写十六进制 SHA-256，64 个字符。对象按它存放。 |

### 请求体

`*/*` `binary`

### 响应

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

### 错误状态

`400` `401` `403` `404` `408` `409` `410` `412` `413` `415` `422` `429` `500` `503` 错误结构见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)，各错误码的含义见 [错误码](https://mirabase.io/zh/developers/errors.md)。

### 请求示例

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

### 响应结构示例

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

## 回滚到检查点

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

回到这个分支的一个检查点。之后的检查点保留，所以回滚可以撤销。这个分支更早的 `changes` 游标随后返回 410 `cursor_expired`。需要 `knowledge:write`。

**需要的能力** `knowledge:write`

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `space_id` | 路径 | `DevSpaceRef` | 必填 | Space id；`default` 表示你的默认 Space（你自己的默认 Space，否则为唯一可见的 Space）；或 `ext:<external_id>`，表示带有你为它设定的 id 的 Space，例如 `ext:user-42`。三种写法均可用于路径、`?space_id=` 和 `space_ids`。没有可见的 Space 带有该 `external_id` 时返回 404。 长度 1 到 256 |
| `branch_id` | 路径 | `DevBranchRef` | 必填 | 分支 id，或活跃分支的名字。id 以 `brn_` 开头。会重试的调用里请用 id：第一个分支关闭后，名字可能指向另一个分支。 |
| `Idempotency-Key` | 请求头 | `DevIdempotencyKey` | 可选 | `Idempotency-Key`、主体、API Key、操作和输入都相同时，24 小时内重放原结果。同一个 `Idempotency-Key` 搭配不同输入时返回 409 `conflict`。 长度 1 到 512 |

### 请求体

`application/json` `DevRollbackRequest`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `checkpoint_id` | `DevId` | 必填 | 要回滚到的检查点的 id。 |

### 响应

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

### 错误状态

`400` `401` `403` `404` `408` `409` `410` `412` `413` `415` `422` `429` `500` `503` 错误结构见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)，各错误码的含义见 [错误码](https://mirabase.io/zh/developers/errors.md)。

### 请求示例

```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>"}'
```

### 响应结构示例

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