Before you start
You need an API key from Settings > API keys. Copy the key when you create it because Saturation shows the full value once.
The production base URL is:
The OpenAPI reference is available at:
The OpenAPI file currently lists api.saturation.io in its server metadata. That hostname does not serve the Next /v1 API. When generating a client from the file, set its base URL to https://next-api.saturation.io/v1.
Send your first request
Send the API key in the Authorization header as a Bearer token. Do not send it as a query parameter or an X-API-Key header.
This request returns the key owner's identity and the workspace the key can reach:
--header "Authorization: Bearer $SATURATION_API_KEY" \
--header "Accept: application/json"
The response includes a workspaceId. Most records are already limited to the workspace attached to the key, so you do not choose a workspace by adding a scope to the key.
Work with Saturation records
The API includes endpoints for projects, budgets, transactions, contacts, documents, purchase orders, workspace library data, search, webhooks, and usage. Check the OpenAPI reference for the available methods, request fields, and response shapes.
Use record IDs returned by the API instead of names when a request links one record to another. For example, a transaction can refer to a project, contact, or budget line by ID.
For a write request that supports Idempotency-Key, send a stable unique value in that header. Retrying the same request with the same key prevents an integration timeout from creating the same record twice.
Permissions and access changes
An API key does not have a separate set of selectable permissions. It follows the current workspace and project access of the teammate who created it.
If the teammate loses access to a project, the key loses access to that project.
If the teammate's role changes, the key's permissions change with it.
If the key is revoked or expires, requests made with it stop working.
Keep separate keys for separate integrations. This makes it possible to revoke one integration without interrupting another.
Handle common errors
401 means the Bearer token is missing, invalid, or expired.
403 means the key is valid but its owner cannot perform the requested action, or API access is unavailable for the workspace.
404 can mean the record does not exist or is outside the key owner's access.
429 means the request limit was reached. Wait for the number of seconds in the Retry-After header before trying again.
The default limit is 600 requests per key per minute and 3,000 requests per workspace per minute. Build retries with backoff instead of immediately repeating a failed request.
Usage credits
API requests are recorded in workspace usage. They currently charge zero usage credits, so calling the public API does not reduce the workspace credit balance.