# Proposals

Approval-gated agent write operations.

Proposals are drafts. Humans approve or reject them in Ledger → Approvals. Approved proposals mutate the ledger. Propose and review events are audit-logged in Log (/log) — there is no agent API to read Log in v1.

### `GET /api/v1/proposals`

Pending agent proposals awaiting human approval.

- operationId: `list_pending_proposals`
- scope: `read`

**Response**

```json
{
  "data": [ { "id": "…", "type": "categorization", "status": "pending", … } ],
  "meta": { "count": 2 }
}
```

### `GET /api/v1/proposals/{id}`

Single proposal by ID.

- operationId: `get_proposal`
- scope: `read`

**Parameters**

- `id` (uuid, required) — Proposal ID

**Response**

```json
{ "data": { "id": "…", "type": "categorization", "status": "pending", … } }
```

### `POST /api/v1/proposals/categorization`

Suggest a category for a transaction. Prefer categoryCode. Creates a pending proposal — the ledger is not updated until a human approves in Ledger → Approvals.

- operationId: `propose_categorization`
- scope: `propose-write`

**Body**

```json
{
  "transactionId": "uuid",
  "categoryCode": "5300",
  "confidence": 0.91,
  "reason": "Description matches counterparty AWS",
  "evidence": [
    { "type": "counterparty_match", "value": "aws" }
  ]
}
```

**Response**

```json
{ "data": { "id": "…", "status": "pending", "type": "categorization", … } }
```

### `POST /api/v1/proposals/journal-entry`

Propose a new manual ledger entry. Creates a pending proposal — a transaction is created only after human approval.

- operationId: `propose_journal_entry`
- scope: `propose-write`

**Body**

```json
{
  "date": "2026-08-28",
  "description": "Office supplies",
  "amount": -42.50,
  "currency": "EUR",
  "categoryCode": "5200",
  "source": "manual_csv",
  "confidence": 0.88,
  "reason": "One-off office purchase"
}
```

**Response**

```json
{ "data": { "id": "…", "status": "pending", "type": "journal_entry", … } }
```

### `POST /api/v1/proposals/receipt-link`

Suggest linking a receipt to a transaction. Approval required.

- operationId: `propose_receipt_link`
- scope: `propose-write`

**Body**

```json
{
  "transactionId": "uuid",
  "receiptId": "uuid",
  "confidence": 0.85,
  "reason": "Amount and date match"
}
```

**Response**

```json
{ "data": { "id": "…", "status": "pending", "type": "receipt_link", … } }
```

| type | On approval |
| --- | --- |
| categorization | Sets canonical category + agent metadata; status → matched |
| journal_entry | Creates new transaction (status matched) |
| receipt_link | Links receipt to transaction |
| note | Creates note on transaction |