# Change sets

> Proposed journals and reconciliations that an admin approves before they reach the ledger.

Part of the [Prosaic API reference](https://developer.prosaic.works/docs/api.md). Base URL: `https://app.prosaic.works/api/public/v1`. Authenticate with `Authorization: Bearer <API key or access token>`.

## Submit a change-set (proposed financial writes) for an entity

`POST /api/public/v1/entities/{entityId}/change-sets`

SDK: `prosaic.changeSets.create(entityId, params)`

Records an agent-proposed set of write operations (`journal.post` and/or `reconcile`) as a PENDING change-set. Idempotent on the content hash — re-submitting identical content returns the existing change-set. The set is NOT committed here; an admin approves it (L1) before it hits the ledger. The read-only box token is permitted on this single write path and remains pinned to its entity.

### Path parameters

- `entityId` (string, required)

### Request body

Content type: `application/json`

- `operations` (array of objects, required)
- `sessionId` (string)
- `agentSessionId` (string)

### Responses

- `201`: Successful response
  - `success` (boolean, required): One of: `true`.
  - `data` (object, required)
    - `id` (string, required)
    - `status` (string, required)
    - `contentHash` (string, required)
- `400`: Invalid body
- `401`: Unauthorized
- `403`: TOKEN_READ_ONLY / TOKEN_ENTITY_MISMATCH / ENTITY_ACCESS_DENIED
- `404`: Entity has no workspace
- `422`: CHANGE_SET_INVALID — an operation failed validation (e.g. amounts do not sum
- `500`: Failed to record the change-set

### Example (Node SDK)

```ts
const { data } = await prosaic.changeSets.create(entityId, {
  operations: [
    {
      type: 'journal.post',
      payload: {
        narration: 'Office supplies',
        date: '2026-04-01',
        lines: [
          {},
        ],
      },
    },
  ],
});
```

### Example (curl)

```bash
curl -X POST https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/change-sets \
  -H "Authorization: Bearer $PROSAIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operations": [
      {
        "type": "journal.post",
        "payload": {
          "narration": "Office supplies",
          "date": "2026-04-01",
          "lines": [
            {}
          ]
        }
      }
    ]
  }'
```