Skip to content
Developer docs
Docs menu

Proposals

Markdown

Changes 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

NameInTypeDescription
proposal_idRequiredPathDevIdOpaque server-issued identifier. Clients compare it byte for byte.length 1..256

Responses

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
curl "https://api.mirabase.dev/v2/proposals/$PROPOSAL_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

Example response

json
{
  "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

NameInTypeDescription
proposal_idRequiredPathDevIdOpaque server-issued identifier. Clients compare it byte for byte.length 1..256
Idempotency-KeyHeaderDevIdempotencyKeyThe 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

FieldTypeDescription
messagestringBecomes the new version's message. At most 120 characters.max length 120

Responses

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

json
{
  "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

NameInTypeDescription
proposal_idRequiredPathDevIdOpaque server-issued identifier. Clients compare it byte for byte.length 1..256
againstQuerybase | latestVersion 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

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
curl "https://api.mirabase.dev/v2/proposals/$PROPOSAL_ID/diff" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

Example response

json
{
  "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

NameInTypeDescription
proposal_idRequiredPathDevIdOpaque server-issued identifier. Clients compare it byte for byte.length 1..256
Idempotency-KeyHeaderDevIdempotencyKeyThe 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

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

json
{
  "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

NameInTypeDescription
proposal_idRequiredPathDevIdOpaque server-issued identifier. Clients compare it byte for byte.length 1..256
Idempotency-KeyHeaderDevIdempotencyKeyThe 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

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

json
{
  "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

NameInTypeDescription
space_idRequiredPathDevSpaceRefA 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
statusQueryDevProposalStatusKeep the proposals with this status. Defaults to open.default: "open"
entry_idQueryDevIdKeep the proposals about this file, by its Entry id.length 1..256
author_idQueryDevIdKeep the proposals this principal made.length 1..256
cursorQueryDevCursorThe next_cursor of the previous page. Omit it to start from the first page.length 1..1024
limitQueryintegerHow many items a page holds at most: 1 to 100, 20 by default.1..100, default: 20

Responses

  • 200 application/json
FieldTypeDescription
dataRequiredDevProposal[]The items on this page.
next_cursorDevCursorPass 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
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/proposals" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

Example response

json
{
  "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"
    }
  ]
}