# Saturation API Docs

> Saturation exposes production finance data through a workspace-bound REST API. Use the OpenAPI contract for exact schemas, and use the Markdown pages for auth, pagination, errors, retries, and workflows.

Important rules:
- Base URL for this docs build: `https://next-api.saturation.io/v1`
- Authenticate with `Authorization: Bearer <token>`. There is no API-key header.
- A token acts in exactly one workspace. Do not add `/workspaces/{id}` to resource paths.
- Lists use `{ data, nextCursor }`. Errors use `{ success: false, code, message, requestId }`.
- For endpoint schemas, fetch `/openapi.yaml`. For copyable endpoint context, fetch the per-operation Markdown file.

## Start Here

- [Overview](https://docs.saturation.io/index.md): Mental model, base URL, docs map, and LLM entrypoints.
- [Getting Started](https://docs.saturation.io/getting-started.md): Token, base URL, first request, response shapes, and the workspace-bound path model.
- [Authentication](https://docs.saturation.io/authentication.md): Bearer tokens, workspace binding, scopes, revocation, and auth error codes.
- [Concepts](https://docs.saturation.io/concepts.md): Workspaces, projects, Library copies, transactions, documents, search, and API conventions.
- [Quickstart](https://docs.saturation.io/quickstart.md): A copyable HTTP/fetch flow for auth, budget totals, and paginated transactions.

## Core Guides

- [Guides](https://docs.saturation.io/guides.md): Task-oriented recipes for Library setup, pagination, errors, idempotency, and webhooks.
- [MCP](https://docs.saturation.io/mcp.md): OAuth setup, public tools, purchase-order reads, generated writes, and contract policy.
- [Errors](https://docs.saturation.io/errors.md): Error envelope, retry model, support request IDs, and the complete code catalog.
- [Pagination](https://docs.saturation.io/pagination.md): Cursor pagination, limits, counts, and invalid cursors.
- [Idempotency](https://docs.saturation.io/idempotency.md): How to mark retried creates and interpret idempotency conflicts.
- [Rate Limits](https://docs.saturation.io/rate-limits.md): 429 responses, Retry-After, backoff, and integration-level throttling.
- [Webhook Events](https://docs.saturation.io/webhook-events.md): Webhook subscription shape, thin payloads, signatures, and retry handling.
- [Changelog and Versioning](https://docs.saturation.io/changelog.md): Version policy, launch status, and migration notes from the legacy API.

## API Contract

- [OpenAPI YAML](https://docs.saturation.io/openapi.yaml): The source contract Scalar renders and code generators should consume.
- [API Reference Markdown](https://docs.saturation.io/api-reference.md): A generated Markdown index of every operation.
- [Guides and Endpoint Summaries](https://docs.saturation.io/llms-full.txt): All authored pages plus generated endpoint summaries in one file.

## Find an Endpoint

Use `/api-reference.md` to search by method, path, or operationId.
Fetch `/api-reference/{operationId}.md` only for the operation you are about to call.

## Optional

- [Human docs app](https://docs.saturation.io/): Guides and the Scalar API reference.