Proposals
MarkdownChanges an Agent proposes to files it does not own, and their review.
Read a proposal
GET/v2/proposals/{proposal_id}
Read one proposal. Only its author and the Space's reviewers can see it; for anyone else it returns 404 not_found. Needs knowledge:read.
Capability knowledge:read
Parameters
| Name | In | Type | Description |
|---|---|---|---|
proposal_idRequired | Path | DevId | Opaque server-issued identifier. Clients compare it byte for byte.length 1..256 |
Responses
200application/jsonDevProposal
Error statuses
400 401 403 404 422 429 500 503 See Errors for the error shape and Error codes for what each code means.
Example request
curl "https://api.mirabase.dev/v2/proposals/$PROPOSAL_ID" \
-H "Authorization: Bearer $MIRABASE_API_KEY"Example response
{
"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"
}Approve a proposal
POST/v2/proposals/{proposal_id}/approve
Write the proposed content as the file's new version, authored by the Agent. Reviewers only, and only inside their write_root. If the file has changed since the proposal was made, or is in the trash, it returns 409 proposal_conflict with current_version_id and the proposal stays open, so the Agent must submit a new one. A proposal that is no longer open returns 409 proposal_closed. Needs knowledge:write.
Capability knowledge:write
Parameters
| Name | In | Type | Description |
|---|---|---|---|
proposal_idRequired | Path | DevId | Opaque server-issued identifier. Clients compare it byte for byte.length 1..256 |
Idempotency-Key | Header | DevIdempotencyKey | 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 DevApproveProposalRequest
| Field | Type | Description |
|---|---|---|
message | string | Becomes the new version's message. At most 120 characters.max length 120 |
Responses
200application/jsonDevProposal
Error statuses
400 401 403 404 408 409 410 412 413 415 422 429 500 503 See Errors for the error shape and Error codes for what each code means.
Example request
curl -X POST "https://api.mirabase.dev/v2/proposals/$PROPOSAL_ID/approve" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'Example response
{
"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"
}Diff a proposal
GET/v2/proposals/{proposal_id}/diff
Compare the proposed content with base (the default: the version the proposal was made from) or with the file's latest, to see what is left after the file moved on. Same shape as an Entry's diff. A file in the trash returns 404. Needs knowledge:read.
Capability knowledge:read
Parameters
| Name | In | Type | Description |
|---|---|---|---|
proposal_idRequired | Path | DevId | Opaque server-issued identifier. Clients compare it byte for byte.length 1..256 |
against | Query | base | latest | Version to compare the proposed content against: base (default, the version the proposal was made from) or latest (the current version of the file).default: "base" |
Responses
200application/jsonDevVersionDiff
Error statuses
400 401 403 404 422 429 500 503 See Errors for the error shape and Error codes for what each code means.
Example request
curl "https://api.mirabase.dev/v2/proposals/$PROPOSAL_ID/diff" \
-H "Authorization: Bearer $MIRABASE_API_KEY"Example response
{
"entry_id": "<entry_id>",
"from_version_id": "<from_version_id>",
"to_version_id": "<to_version_id>",
"identical": false,
"basis": "original"
}Reject a proposal
POST/v2/proposals/{proposal_id}/reject
Close the proposal without changing the file. Reviewers only. A proposal that is no longer open returns 409 proposal_closed. Needs knowledge:write.
Capability knowledge:write
Parameters
| Name | In | Type | Description |
|---|---|---|---|
proposal_idRequired | Path | DevId | Opaque server-issued identifier. Clients compare it byte for byte.length 1..256 |
Idempotency-Key | Header | DevIdempotencyKey | 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 DevEmptyRequest
Responses
200application/jsonDevProposal
Error statuses
400 401 403 404 408 409 410 412 413 415 422 429 500 503 See Errors for the error shape and Error codes for what each code means.
Example request
curl -X POST "https://api.mirabase.dev/v2/proposals/$PROPOSAL_ID/reject" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'Example response
{
"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"
}Withdraw a proposal
POST/v2/proposals/{proposal_id}/withdraw
Close a proposal you authored. A proposal that is no longer open returns 409 proposal_closed. Needs knowledge:write.
Capability knowledge:write
Parameters
| Name | In | Type | Description |
|---|---|---|---|
proposal_idRequired | Path | DevId | Opaque server-issued identifier. Clients compare it byte for byte.length 1..256 |
Idempotency-Key | Header | DevIdempotencyKey | 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 DevEmptyRequest
Responses
200application/jsonDevProposal
Error statuses
400 401 403 404 408 409 410 412 413 415 422 429 500 503 See Errors for the error shape and Error codes for what each code means.
Example request
curl -X POST "https://api.mirabase.dev/v2/proposals/$PROPOSAL_ID/withdraw" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'Example response
{
"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"
}List proposals
GET/v2/spaces/{space_id}/proposals
List the proposals in this Space that you can see, oldest first. Needs knowledge:read.
Capability knowledge:read
Parameters
| Name | In | Type | Description |
|---|---|---|---|
space_idRequired | Path | DevSpaceRef | 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 |
status | Query | DevProposalStatus | Keep the proposals with this status. Defaults to open.default: "open" |
entry_id | Query | DevId | Keep the proposals about this file, by its Entry id.length 1..256 |
author_id | Query | DevId | Keep the proposals this principal made.length 1..256 |
cursor | Query | DevCursor | The next_cursor of the previous page. Omit it to start from the first page.length 1..1024 |
limit | Query | integer | How many items a page holds at most: 1 to 100, 20 by default.1..100, default: 20 |
Responses
200application/json
| Field | Type | Description |
|---|---|---|
dataRequired | DevProposal[] | The items on this page. |
next_cursor | DevCursor | 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 for the error shape and Error codes for what each code means.
Example request
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/proposals" \
-H "Authorization: Bearer $MIRABASE_API_KEY"Example response
{
"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"
}
]
}