> For AI assistants: read [llms.txt](https://docs.saturation.io/llms.txt) first for the complete documentation map, API contract, and endpoint Markdown files.

# Changelog and versioning

`/v1` is the current `1.0.0` public contract.

## Moving to `/v1`

This table maps earlier routes to their `/v1` replacements.

| Earlier API | `/v1` | Why |
|---|---|---|
| `X-API-Key` header | `Authorization: Bearer <token>` | A personal token does what your account can do in its workspace. |
| Workspace implied by the key | Workspace bound to the token | Each token belongs to one workspace. Paths never carry a workspace id. |
| Unbounded list responses | Paginated, cap 100 (default 50) | Large lists are paged. Loop through the `cursor` to fetch all. |
| `/actuals` | `/transactions?source=manual` | Manual entries are Transactions. `/transactions/bulk` replaces `/actuals/batch`. |
| Flat `/rates` | `/library/rate-packs` | Rate Packs live in the workspace Library. Enabling one makes it available to every project. |
| Per-record `/attachment` | `/documents` plus links | Upload a Document once, then link it to other records. |

The [Reference](/api-reference.md) explains what changed for Documents, Transactions, Budget, Projects, and Contacts. [Concepts](/concepts.md) explains tokens and workspaces.

## Versioning policy

The major version lives in the path. Additive changes stay in `/v1`; incompatible changes use a new major path. We publish integration changes here.

## Releases

### 2026-08-05: purchase orders and payments

- Added purchase-order Activity, Summary, Timeline, linked payment records, and suggested matches.
- Removed the overloaded purchase-order Reconciliation read.
- Added payment requests and payments. Payments use the same status names as the Payments page and include a Timeline.
- Added access details to error responses and completed the error-code list.
- Required `Idempotency-Key` on Library creates that can duplicate a record.

### 2026-06-11: workspace prefix removed (breaking, pre-launch)

Every API path lost its `/workspaces/{workspaceId}` prefix. The API reads the workspace from the token. See [Concepts](/concepts.md) for the token binding.

- `GET /v1/workspaces/{ws}/projects` is now `GET /v1/projects`, and the same applies to every public resource (`/contacts`, `/library/...`, `/webhooks`, and so on). If you see `/workspaces/{id}/...` in an old example, drop the prefix.
- `GET /me` returns the token's workspace and your role in it.
- `GET /workspaces` and `GET /workspaces/{workspaceId}` were removed. Their public fields moved into `/me`.
- A request to an old prefixed path returns `404 not_found` with a message telling you to drop the prefix.

This change shipped before `1.0.0`.

### 2026-06-11: v1.0.0 public baseline

The first public release. `/v1` covers:

- **Meta and identity**: `GET /me`, projects, spaces, and contacts.
- **Budget**: lines, phases, editable phase data, a computed document, and filtered totals.
- **Transactions**: manual and imported records, itemized lines, statistics, and bulk writes.
- **Purchase orders**: the `status` field is read-only; actions such as `submit`, `cancel-submission`, and `void` move it.
- **Documents**: upload, extract, download, and link files.
- **Library**: rate packs, incentive packs, fringes, fringe groups, globals, currencies, tags, and units for a workspace or project.
- **Search**: query transactions, purchase orders, documents, contacts, and budget lines.
- **Webhooks**: outbound and HMAC-signed. Deliveries contain the record type and ID.

## Next

- [Reference](/api-reference.md): fields and paths for each part of the API.
- [Concepts](/concepts.md): the token and one-workspace data model.
- [Errors](/errors.md): error responses, status codes, and retries.