# Proposals

Changes an Agent proposes to files it does not own, and their review.

API reference. Base URL: `https://api.mirabase.dev`

## 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 | Required | Description |
| --- | --- | --- | --- | --- |
| `proposal_id` | Path | `DevId` | Required | Opaque server-issued identifier. Clients compare it byte for byte. length 1..256 |

### Responses

- `200` `application/json` `DevProposal`

### Error statuses

`400` `401` `403` `404` `422` `429` `500` `503` See [Errors](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

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

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `proposal_id` | Path | `DevId` | Required | Opaque server-issued identifier. Clients compare it byte for byte. length 1..256 |
| `Idempotency-Key` | Header | `DevIdempotencyKey` | Optional | 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 | Required | Description |
| --- | --- | --- | --- |
| `message` | `string` | Optional | Becomes the new version's `message`. At most 120 characters. max length 120 |

### Responses

- `200` `application/json` `DevProposal`

### Error statuses

`400` `401` `403` `404` `408` `409` `410` `412` `413` `415` `422` `429` `500` `503` See [Errors](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

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

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `proposal_id` | Path | `DevId` | Required | Opaque server-issued identifier. Clients compare it byte for byte. length 1..256 |
| `against` | Query | `base \| latest` | Optional | 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

- `200` `application/json` `DevVersionDiff`

### Error statuses

`400` `401` `403` `404` `422` `429` `500` `503` See [Errors](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

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

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `proposal_id` | Path | `DevId` | Required | Opaque server-issued identifier. Clients compare it byte for byte. length 1..256 |
| `Idempotency-Key` | Header | `DevIdempotencyKey` | Optional | 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

- `200` `application/json` `DevProposal`

### Error statuses

`400` `401` `403` `404` `408` `409` `410` `412` `413` `415` `422` `429` `500` `503` See [Errors](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

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

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `proposal_id` | Path | `DevId` | Required | Opaque server-issued identifier. Clients compare it byte for byte. length 1..256 |
| `Idempotency-Key` | Header | `DevIdempotencyKey` | Optional | 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

- `200` `application/json` `DevProposal`

### Error statuses

`400` `401` `403` `404` `408` `409` `410` `412` `413` `415` `422` `429` `500` `503` See [Errors](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

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

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `space_id` | Path | `DevSpaceRef` | Required | 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` | Optional | Keep the proposals with this status. Defaults to `open`. default: "open" |
| `entry_id` | Query | `DevId` | Optional | Keep the proposals about this file, by its Entry id. length 1..256 |
| `author_id` | Query | `DevId` | Optional | Keep the proposals this principal made. length 1..256 |
| `cursor` | Query | `DevCursor` | Optional | The `next_cursor` of the previous page. Omit it to start from the first page. length 1..1024 |
| `limit` | Query | `integer` | Optional | How many items a page holds at most: 1 to 100, 20 by default. 1..100, default: 20 |

### Responses

- `200` `application/json`

200 response:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | `DevProposal[]` | Required | The items on this page. |
| `next_cursor` | `DevCursor` | Optional | 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](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

```bash
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"
    }
  ]
}
```
