大文件上传
Markdown 版用于超过 16 MiB 文件的分片上传。
发起大文件上传
POST/v2/spaces/{space_id}/uploads
发起分片上传。先调用 POST /v2/uploads/{upload_id}/parts 获取分片上传地址,逐片 PUT,再调用 POST /v2/uploads/{upload_id}/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。超过部署的大小上限返回 413。大到无法处理的文件仍会保存且可读,knowledge.state 最终为 failed。
| 字段 | 类型 | 说明 |
|---|---|---|
path必填 | DevPath | 在完成上传时才解析,所以这期间该路径上的文件可能出现或变化。 |
size必填 | integer | 整个文件的字节数。不小于 1 |
media_type必填 | string | 文件的媒体类型,比如 application/pdf。 |
checksum_sha256必填 | string | 整个文件 SHA-256 的 Base64,完成时校验。 |
响应
201application/jsonDevUpload
错误状态
400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
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>"}'响应结构示例
{
"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
参数
响应
204无响应体
错误状态
400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
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 相同。内容相同时返回 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} 上的 metadata 相同。检索的 filter.metadata 按它匹配。 |
memory_exclude | boolean | 为 true 时该文件不参与记忆提炼:文件照常保存、建立索引并可检索,但不会从中提炼记忆;为 false 时重新提炼。与 PATCH /v2/entries/{id} 的 memory_exclude 是同一个开关。 |
响应
200application/jsonDevFileWrite | DevBranchFileWrite202application/jsonDevProposalReceipt
响应头
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 错误结构见 错误,各错误码的含义见 错误码。
请求示例
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>"}]}'响应结构示例
{
"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
指南:文件与版本
参数
请求体
application/json DevUploadPartsRequest
| 字段 | 类型 | 说明 |
|---|---|---|
part_numbers必填 | integer[] | 从 1 开始编号。1 到 128 项 |
响应
200application/jsonDevUploadParts
错误状态
400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
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]}'响应结构示例
{
"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>"
}
}