Agent 对不属于自己的文件提出的修改,以及对这些修改的审核。
读取提案
GET/v2/proposals/{proposal_id}
读取一个提案。只有作者和 Space 的审核人能看到;对其他人返回 404 not_found。需要 knowledge:read。
需要的能力 knowledge:read
参数
| 名称 | 位置 | 类型 | 说明 |
|---|---|---|---|
proposal_id必填 | 路径 | DevId | 服务端签发的不透明标识符,客户端按字节比较。长度 1 到 256 |
响应
200application/jsonDevProposal
错误状态
400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl "https://api.mirabase.dev/v2/proposals/$PROPOSAL_ID" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"id": "<id>",
"space_id": "<space_id>",
"entry_id": "<entry_id>",
"status": "open",
"base_version_id": "<base_version_id>",
"proposed_version_id": "<proposed_version_id>",
"size_bytes": 1,
"media_type": "<media_type>",
"created_at": "2026-11-06T00:00:00Z"
}批准提案
POST/v2/proposals/{proposal_id}/approve
将提案内容写成文件的新版本,作者是提交提案的 Agent。只有审核人能操作,且只限其 write_root 以内。提交提案后文件已修改或已移入废纸篓时返回 409 proposal_conflict(含 current_version_id),提案保持打开状态,Agent 需要重新提交。已不在打开状态的提案返回 409 proposal_closed。需要 knowledge:write。
需要的能力 knowledge:write
参数
| 名称 | 位置 | 类型 | 说明 |
|---|---|---|---|
proposal_id必填 | 路径 | DevId | 服务端签发的不透明标识符,客户端按字节比较。长度 1 到 256 |
Idempotency-Key | 请求头 | DevIdempotencyKey | Idempotency-Key、主体、API Key、操作和输入都相同时,24 小时内重放原结果。同一个 Idempotency-Key 搭配不同输入时返回 409 conflict。长度 1 到 512 |
请求体
application/json DevApproveProposalRequest
| 字段 | 类型 | 说明 |
|---|---|---|
message | string | 成为新版本的 message,最多 120 个字符。最长 120 |
响应
200application/jsonDevProposal
错误状态
400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl -X POST "https://api.mirabase.dev/v2/proposals/$PROPOSAL_ID/approve" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'响应结构示例
{
"id": "<id>",
"space_id": "<space_id>",
"entry_id": "<entry_id>",
"status": "open",
"base_version_id": "<base_version_id>",
"proposed_version_id": "<proposed_version_id>",
"size_bytes": 1,
"media_type": "<media_type>",
"created_at": "2026-11-06T00:00:00Z"
}查看提案改动
GET/v2/proposals/{proposal_id}/diff
将提案内容与 base(默认,即提案所基于的版本)或文件的 latest 比较,查看文件更新后还剩哪些改动。响应结构与 Entry 的 diff 相同。文件在废纸篓中时返回 404。需要 knowledge:read。
需要的能力 knowledge:read
参数
| 名称 | 位置 | 类型 | 说明 |
|---|---|---|---|
proposal_id必填 | 路径 | DevId | 服务端签发的不透明标识符,客户端按字节比较。长度 1 到 256 |
against | 查询 | base | latest | 与提案内容比较的基准版本:base(默认,即提案基于的版本)或 latest(文件当前版本)。默认 "base" |
响应
200application/jsonDevVersionDiff
错误状态
400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl "https://api.mirabase.dev/v2/proposals/$PROPOSAL_ID/diff" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"entry_id": "<entry_id>",
"from_version_id": "<from_version_id>",
"to_version_id": "<to_version_id>",
"identical": false,
"basis": "original"
}拒绝提案
POST/v2/proposals/{proposal_id}/reject
关闭提案而不修改文件。只有审核人能操作。已不在打开状态的提案返回 409 proposal_closed。需要 knowledge:write。
需要的能力 knowledge:write
参数
| 名称 | 位置 | 类型 | 说明 |
|---|---|---|---|
proposal_id必填 | 路径 | DevId | 服务端签发的不透明标识符,客户端按字节比较。长度 1 到 256 |
Idempotency-Key | 请求头 | DevIdempotencyKey | Idempotency-Key、主体、API Key、操作和输入都相同时,24 小时内重放原结果。同一个 Idempotency-Key 搭配不同输入时返回 409 conflict。长度 1 到 512 |
请求体
application/json DevEmptyRequest
响应
200application/jsonDevProposal
错误状态
400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl -X POST "https://api.mirabase.dev/v2/proposals/$PROPOSAL_ID/reject" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'响应结构示例
{
"id": "<id>",
"space_id": "<space_id>",
"entry_id": "<entry_id>",
"status": "open",
"base_version_id": "<base_version_id>",
"proposed_version_id": "<proposed_version_id>",
"size_bytes": 1,
"media_type": "<media_type>",
"created_at": "2026-11-06T00:00:00Z"
}撤回提案
POST/v2/proposals/{proposal_id}/withdraw
关闭自己提交的提案。已不在打开状态的提案返回 409 proposal_closed。需要 knowledge:write。
需要的能力 knowledge:write
参数
| 名称 | 位置 | 类型 | 说明 |
|---|---|---|---|
proposal_id必填 | 路径 | DevId | 服务端签发的不透明标识符,客户端按字节比较。长度 1 到 256 |
Idempotency-Key | 请求头 | DevIdempotencyKey | Idempotency-Key、主体、API Key、操作和输入都相同时,24 小时内重放原结果。同一个 Idempotency-Key 搭配不同输入时返回 409 conflict。长度 1 到 512 |
请求体
application/json DevEmptyRequest
响应
200application/jsonDevProposal
错误状态
400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl -X POST "https://api.mirabase.dev/v2/proposals/$PROPOSAL_ID/withdraw" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'响应结构示例
{
"id": "<id>",
"space_id": "<space_id>",
"entry_id": "<entry_id>",
"status": "open",
"base_version_id": "<base_version_id>",
"proposed_version_id": "<proposed_version_id>",
"size_bytes": 1,
"media_type": "<media_type>",
"created_at": "2026-11-06T00:00:00Z"
}列出提案
GET/v2/spaces/{space_id}/proposals
列出这个 Space 中你能看到的提案,最早的在前。需要 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 |
status | 查询 | DevProposalStatus | 只保留这个状态的提案。默认 open。默认 "open" |
entry_id | 查询 | DevId | 只保留针对这个文件的提案,用它的 Entry id 指定。长度 1 到 256 |
author_id | 查询 | DevId | 只保留这个主体提交的提案。长度 1 到 256 |
cursor | 查询 | DevCursor | 上一页的 next_cursor。不传则从第一页开始。长度 1 到 1024 |
limit | 查询 | integer | 每页最多返回的条目数:1 到 100,默认 20。1 到 100,默认 20 |
响应
200application/json
| 字段 | 类型 | 说明 |
|---|---|---|
data必填 | DevProposal[] | 这一页的条目。 |
next_cursor | DevCursor | 作为 cursor 传入以获取下一页。最后一页不返回该字段。 |
错误状态
400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/proposals" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"data": [
{
"id": "<id>",
"space_id": "<space_id>",
"entry_id": "<entry_id>",
"status": "open",
"base_version_id": "<base_version_id>",
"proposed_version_id": "<proposed_version_id>",
"size_bytes": 1,
"media_type": "<media_type>",
"created_at": "2026-11-06T00:00:00Z"
}
]
}