canonical: https://jentic.com/apis/saturation.io/saturation

# Saturation API

The Saturation API reads and writes production finance data: project budgets with phases such as estimate, actual, rollup, and committed, budget lines, transactions, purchase orders, payments, and supporting documents. Purchase orders move through draft, pending, approved, actualizing, paid, and void, and can be linked to the transactions that settle them. Uploaded documents are classified and their fields and line items extracted, and a shared library holds rate packs, incentive packs, fringes, globals, currencies, units, and tags that projects reuse. Money is sent as integer minor units with an ISO-4217 currency, and webhooks report events such as transaction.created and budget.changed.

## For AI agents

Read and update production budgets, record transactions, raise and approve purchase orders, and extract fields from uploaded invoices and receipts in a Saturation workspace.

## Scope

Does not issue cards, move money, or run payroll. Use for production budgets, transactions, purchase orders, and finance documents in Saturation only.

## Capabilities

- Read a project's budget with its phases, totals, and line tree, or just the totals for one phase or account
- Add up to 100 budget lines in one call, or update up to 500 line and phase entries atomically with an Idempotency-Key
- Record manual transactions, singly or up to 500 in bulk, and filter them by budgetLineId, contactId, purchaseOrderId, dateFrom, dateTo, or amountMin
- Raise purchase orders, submit them for approval, void them, and mark them paid once a transaction is linked
- Upload an invoice or receipt and read its classification, extracted fields, line items, and confidence scores once ready
- Attach rate packs, incentives, fringes, and currencies from the library to a project
- Subscribe a webhook to events such as transaction.created and budget.changed, send a test delivery, and list recent deliveries

## Use cases

### AI agent reconciling production spend

An agent asked to tidy a production's books searches Jentic for 'list Saturation transactions', loads the transactions_list operation, and filters by projectId with hasDocuments false to find spend with no receipt. It uploads the matching receipts, reads each extraction once the document is ready, and links the document to its transaction, with the Saturation token injected at call time.

Example prompt: Call GET /transactions with projectId prj_123 and hasDocuments false, then for each result POST /documents with the receipt file and GET `/documents/{documentId}/extraction` once its status is ready

### Purchase order approval flow

Crew requests for rentals and services become purchase orders tied to a budget line and contact. The API creates the order with its items, submits it for approval, and once approved and settled lets an agent link the paying transaction and mark it paid. Every change is visible on the purchase order timeline, and void or cancel-submission handle orders that should not proceed.

Example prompt: POST /purchase-orders with projectId prj_123, name 'Lens rental', contactId con_456, and budgetLineId bl_789, then POST `/purchase-orders/{purchaseOrderId}/submit` with an Idempotency-Key

### Budget versus actuals checks

Producers want to know where a show stands against its estimate. The budget totals operation returns totals for a chosen phase, account, or path at computedAt, and transaction stats return the count and total amount of matching transactions in one currency, so an agent can flag accounts drifting past their estimate.

Example prompt: Call GET `/projects/{projectId}/budget/totals` for project prj_123 with phase set to the estimate phase ID, then GET `/transactions/stats` with projectId prj_123 and compare

### Budget change notifications

Teams that mirror budgets into other tools subscribe a webhook to events such as budget.changed and transaction.updated. The webhook URL must use HTTPS and resolve to a public address, a secret is generated if none is sent, and a test delivery plus the recent deliveries list make it easy to confirm the receiver works.

Example prompt: POST /webhooks with url https://hooks.example.com/saturation and events ['budget.changed','transaction.created'], then POST `/webhooks/{webhookId}/test-delivery`

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/projects/{projectId}/budget` | Get a project budget |
| GET | `/projects/{projectId}/budget/totals` | Get budget totals |
| POST | `/projects/{projectId}/budget/lines/bulk` | Create up to 100 budget lines |
| GET | `/transactions` | List and filter transactions |
| POST | `/transactions` | Create a manual transaction |
| POST | `/purchase-orders` | Create a purchase order |
| POST | `/purchase-orders/{purchaseOrderId}/submit` | Submit a purchase order for approval |
| GET | `/documents/{documentId}/extraction` | Get extracted document data |

## Key resources

- **Budgets** — Per-project phases, totals, and a tree of budget lines
- **Transactions** — Manual and synced spend with amounts in minor units
- **Purchase orders** — Orders with items, approval status, and linked transactions
- **Documents** — Uploaded files with classification and extracted fields
- **Library** — Rate packs, incentive packs, fringes, globals, currencies, units, and tags
- **Webhooks** — Event subscriptions with test delivery and delivery history

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 58 / 100
- **Maturity:** Foundational
- **Dimensions:**
  - Foundational Compliance: 74 / 100
  - Developer Experience & Jentic Compatibility: 61 / 100
  - AI-Readiness & Agent Experience: 39 / 100
  - Agent Usability: 65 / 100
  - Security: 75 / 100
  - AI Discoverability: 76 / 100
- **View full report:** https://jentic.com/apis/saturation.io/saturation/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring Saturation by hand means sending a workspace-bound bearer token, converting money to integer minor units, paging with nextCursor, and generating an Idempotency-Key for every bulk or submit call. Through Jentic you install once, import Saturation from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Saturation puts the project id in the URL path for budget, comment, and project library operations (`/projects/{projectId}/...`), so a rule can pin your agent to one production's budget. Transactions and purchase orders carry projectId in the query or body, so for those a rule bounds which operations it may call, and destructive ones like budget_deleteLine or purchase-orders_void are not included unless you add them.
- **Credential handling:** Your Saturation token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'get a production budget' or 'submit a purchase order for approval', and Jentic returns the matching Saturation operation, such as budget_get or purchase-orders_submit, with its input schema.

## Related APIs

- **Ramp API** — Corporate cards, spend management, and bill pay
- **Brex API** — Corporate cards and expense management
- **Veryfi API** — OCR for receipts and invoices
- **Xero Accounting API** — General ledger, invoices, and bank reconciliation

## FAQ

### What authentication does the Saturation API use?

Per its OpenAPI spec, the Saturation API uses a personal API token sent in the Authorization header with the Bearer prefix, declared with a JWT bearer format. You create the token under Settings > Developers > API, and each token belongs to one workspace. Through Jentic the token is stored by your own instance and attached at call time.

### How does the Saturation API represent money?

Amounts are integer minor units with an ISO-4217 currency, for example amount 152900 with currency USD for 1,529.00 dollars. Dates use ISO 8601, and lists default to 50 items with a maximum of 100, paged by passing nextCursor back as cursor.

### Can the Saturation API extract data from invoices and receipts?

Yes. Upload the file to the documents endpoint, optionally linking it to targets through metadata.links, then read the extraction once the document status is ready. It returns the classification, extracted fields, line items, and confidence scores, and returns 404 not_found while processing. Uploading is billable.

### What are the rate limits for the Saturation API?

The OpenAPI spec does not give a general rate limit. It does limit the feedback endpoint to 20 items per credential owner in any 24 hours, returning 429 feedback_limit past that. Check https://docs.saturation.io for current limits on other endpoints.

### Is there a Saturation MCP server?

You don't need an MCP server to give your agent Saturation. Jentic connects it directly from the API Directory: import it, store your Saturation token once, and your agent calls the budget, transaction, and purchase order operations it needs.

### How do I record a transaction in Saturation through Jentic?

Search Jentic for 'create a Saturation transaction', load the transactions_create operation, and execute POST /transactions with type, amount, and timestamp, plus projectId and budgetLineId to place it in the budget. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Can I limit what my agent is allowed to do with the Saturation API?

Yes. For a reporting agent, allow only GET `/projects/prj_123/budget`, its totals, and GET `/transactions/stats`, so it can read one production's numbers while purchase order approvals, transaction deletes, and budget edits stay outside its rule. Every call it makes is logged.
