# 大文件上传

用于超过 16 MiB 文件的分片上传。

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

## 发起大文件上传

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

发起分片上传。先调用 [`POST /v2/uploads/{upload_id}/parts`](https://mirabase.io/zh/developers/api/uploads.md#uploads-parts) 获取分片上传地址，逐片 `PUT`，再调用 [`POST /v2/uploads/{upload_id}/complete`](https://mirabase.io/zh/developers/api/uploads.md#uploads-complete) 完成上传。同一个 `Idempotency-Key` 返回同一个上传。带 `branch` 时，完成上传会写入该分支。需要 `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` | 查询 | `DevBranchRef` | 可选 | 代替主线使用的分支：分支 id，或活跃分支的名称。在这个 Space 设有 `read_root` 的成员，对任何分支都返回 403 `outside_read_root`。 |
| `mode` | 查询 | `644 \| 755` | 可选 | 文件权限，`644` 或 `755`（可执行）。只在带 `branch` 时有效。 |
| `Idempotency-Key` | 请求头 | `DevIdempotencyKey` | 可选 | `Idempotency-Key`、主体、API Key、操作和输入都相同时，24 小时内重放原结果。同一个 `Idempotency-Key` 搭配不同输入时返回 409 `conflict`。 长度 1 到 512 |

### 请求体

`application/json` `DevCreateUploadRequest` 用于超过 16 MiB 的文件，更小的文件使用 [`PUT /v2/spaces/{space_id}/files`](https://mirabase.io/zh/developers/api/files.md#files-write)。超过部署的大小上限返回 413。大到无法处理的文件仍会保存且可读，`knowledge.state` 最终为 `failed`。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `path` | `DevPath` | 必填 | 在完成上传时才解析，所以这期间该路径上的文件可能出现或变化。 |
| `size` | `integer` | 必填 | 整个文件的字节数。 不小于 1 |
| `media_type` | `string` | 必填 | 文件的媒体类型，比如 `application/pdf`。 |
| `checksum_sha256` | `string` | 必填 | 整个文件 SHA-256 的 Base64，完成时校验。 |

### 响应

- `201` `application/json` `DevUpload`

### 错误状态

`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/uploads" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path":"/notes/hello.md","size":1,"media_type":"<media_type>","checksum_sha256":"<checksum_sha256>"}'
```

### 响应结构示例

```json
{
  "id": "<id>",
  "path": "/notes/hello.md",
  "part_size": 1,
  "expires_at": "2026-11-06T00:00:00Z"
}
```

## 中止上传

`POST /v2/uploads/{upload_id}/abort`

丢弃已上传的分片。重复中止返回 204；中止已完成的上传返回 409 `upload_not_open`。需要 `knowledge:write`。

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

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `upload_id` | 路径 | `DevId` | 必填 | 服务端签发的不透明标识符，客户端按字节比较。 长度 1 到 256 |

### 响应

- `204` 无响应体

### 错误状态

`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/uploads/$UPLOAD_ID/abort" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

## 完成上传

`POST /v2/uploads/{upload_id}/complete`

合并分片并写到路径上，行为与 [`PUT /v2/spaces/{space_id}/files`](https://mirabase.io/zh/developers/api/files.md#files-write) 相同。内容相同时返回 `version_created: false`。重复完成返回同一版本，或同一个提案。已中止的上传返回 409 `upload_not_open`，过了 `expires_at` 的上传返回 422 `upload_expired`：请重新发起上传。存下的对象大小或媒体类型与上传时声明的不一致时，返回 422 `upload_size_mismatch` 或 415 `upload_media_type_mismatch`；字节的哈希与 `checksum_sha256` 不符时返回 422 `validation_error`。需要 `knowledge:write`。

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

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `upload_id` | 路径 | `DevId` | 必填 | 服务端签发的不透明标识符，客户端按字节比较。 长度 1 到 256 |
| `If-Match` | 请求头 | `string` | 可选 | 传入一个 ETag（带引号的版本 id）：不是最新版本时返回 412。或传入 `*`：文件或 Entry 不存在时返回 412。不传时后写覆盖。 |
| `Prefer` | 请求头 | `string` | 可选 | `handling=proposal`：将本会返回 403 `proposal_required` 的写入（即 `proposal` 模式的 Agent 修改不属于自己的文件）转为创建提案；其他情况下不起作用。其他偏好会被忽略。 |
| `If-None-Match` | 请求头 | `string` | 可选 | `*` 表示只创建；文件已存在时返回 412 `precondition_failed`。 |

### 请求体

`application/json` `DevCompleteUploadRequest`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `parts` | `DevCompletedPart[]` | 必填 | 文件的每一个分片，各带它的 `PUT` 返回的 `ETag`。 至少 1 项 |
| `session_id` | `string` | 可选 | 你为该文件所出自的对话指定的 id，与 `PUT files?session_id=` 相同：记录在本次完成上传所创建的版本上，可通过 `lineage` 查看。仅用于主线：分支上传传入该字段返回 422。 长度 1 到 256 |
| `occurred_at` | `string (date-time)` | 可选 | 文件内容发生的时间，例如录音或录像的录制时间。检索的 `occurred_from` / `occurred_to` 以此为准，段落中也会返回该时间；未提供时以文件写入时间为准。 |
| `metadata` | `DevMetadata` | 可选 | 整体替换 Entry 的元数据，与 [`PATCH /v2/entries/{id}`](https://mirabase.io/zh/developers/api/entries.md#entries-update) 上的 `metadata` 相同。检索的 `filter.metadata` 按它匹配。 |
| `memory_exclude` | `boolean` | 可选 | 为 `true` 时该文件不参与记忆提炼：文件照常保存、建立索引并可检索，但不会从中提炼记忆；为 `false` 时重新提炼。与 [`PATCH /v2/entries/{id}`](https://mirabase.io/zh/developers/api/entries.md#entries-update) 的 `memory_exclude` 是同一个开关。 |

### 响应

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

### 响应头

- `ETag` 刚写入内容的 `ETag`：下次写入时可传入 `If-Match`，无需重新读取文件。
- `Preference-Applied` 在接受 `Prefer: wait` 的操作上，请求实际发生等待时返回 `wait=N`；未等待时不返回（例如该 Key 已有 4 个等待中的请求）。写入转为提案时返回 `handling=proposal`。
- `Location` `/v2/proposals/{proposal_id}`：这次写入变成的提案可以在这里读取。

### 错误状态

`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/uploads/$UPLOAD_ID/complete" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"parts":[{"part_number":1,"etag":"<etag>"}]}'
```

### 响应结构示例

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

## 获取分片上传地址

`POST /v2/uploads/{upload_id}/parts`

为单次上传的最多 128 个分片获取签名 URL，有效期 5 分钟。使用返回的 `required_headers` 将每个分片 `PUT` 到对应 URL，并保存返回的 `ETag`。已接收的分片不会再次返回，因此再次调用即可续传。已完成或已中止的上传返回 409 `upload_not_open`，已超过 `expires_at` 的上传返回 422 `upload_expired`：请重新发起上传。需要 `knowledge:write`。

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

指南：[文件与版本](https://mirabase.io/zh/developers/files.md#uploads)

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `upload_id` | 路径 | `DevId` | 必填 | 服务端签发的不透明标识符，客户端按字节比较。 长度 1 到 256 |

### 请求体

`application/json` `DevUploadPartsRequest`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `part_numbers` | `integer[]` | 必填 | 从 1 开始编号。 1 到 128 项 |

### 响应

- `200` `application/json` `DevUploadParts`

### 错误状态

`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/uploads/$UPLOAD_ID/parts" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"part_numbers":[1]}'
```

### 响应结构示例

```json
{
  "data": [
    {
      "part_number": 1,
      "url": "https://example.com/article"
    }
  ],
  "received": [
    {
      "part_number": 1,
      "etag": "<etag>"
    }
  ],
  "expires_at": "2026-11-06T00:00:00Z",
  "required_headers": {
    "content-type": "<content-type>"
  }
}
```
