# ⚒️ API Reference

The **Saturation API** lets you work with your workspace data including projects, budgets, actuals, contacts, purchase orders, and attachments.

It is built for real-time collaboration and automation so you can connect it to your internal tools or third-party systems. Any changes you make through the API appear instantly in the web app.

With it, you can:

* Create, update, and organize projects and phases
* Build and track multi-phase budgets
* Sync actuals and purchase orders
* Manage contacts and crew
* Upload, retrieve, and organize attachments

---

**🔑 Authentication**
```http
GET /api/v1/projects
X-API-Key: YOUR_API_KEY
```
\
**📊 Get everything in one call**
```http
GET /projects/my-film/budget?expands[]=phases&expands[]=fringes&expands[]=lines.contact&expands[]=lines.phaseData
```
Returns the complete budget with all related records, no extra roundtrips.
\
\
**🏷️ Use your existing codes**
```http
GET /projects/my-film/budget/line/1100-LABOR    # Your account code
GET /projects/my-film/budget/phases/estimate    # Your phase name
POST /projects/my-film/actuals                  # Create with your codes
{
  "lineItemId": "2150-CAMERA",
  "amount": 5000
}
```
The API speaks your language. Use the same codes from your accounting system.
\
\
**🔄 Common patterns**
```http
# Get recent actuals with full details
GET /projects/my-film/actuals?date=2024-03-14&expands[]=contact&expands[]=attachments

# Create a purchase order
POST /projects/my-film/purchase-orders
{
  "number": "PO-001",
  "contactId": "contact-123",
  "items": [{"lineItemId": "2150", "amount": 35000}]
}

# Export complete budget for accounting
GET /projects/my-film/budget?expands[]=phases&expands[]=fringes&expands[]=globals
```
\
**💡 Pro tips**
* Create multiple budget lines in one POST to `/budget`
* Use tags liberally—they're your flexible second dimension
* Combine `accountId`, `tags`, and `date` filters for precise queries


Version: 1.0.0
License: Proprietary

## Servers

Production server
```
https://api.saturation.io/api/v1
```

## Security

### ApiKeyAuth

API key for authentication

Type: apiKey
In: header
Name: X-API-Key

## Download OpenAPI description

[⚒️ API Reference](https://docs.saturation.io/_spec/openapi.yaml)

## Projects

Create and manage productions, campaigns, or jobs.  
Each project has its own budget, actuals, and purchase orders.  
Use `idMode=user` to reference projects by alias (e.g., `"nike-spring-2024"`) instead of system IDs.


### List projects

 - [GET /projects](https://docs.saturation.io/openapi/projects/listprojects.md): Retrieve projects for the current workspace. Supports filtering by ID, space, status, name, space name, or labels.

### Create project

 - [POST /projects](https://docs.saturation.io/openapi/projects/createproject.md): Create a new project in the current workspace

### Get project

 - [GET /projects/{projectId}](https://docs.saturation.io/openapi/projects/getproject.md): Retrieve a project by its ID or alias

### Update project

 - [PUT /projects/{projectId}](https://docs.saturation.io/openapi/projects/updateproject.md): Update an existing project's details

### Delete project

 - [DELETE /projects/{projectId}](https://docs.saturation.io/openapi/projects/deleteproject.md): Soft delete a project

## Contacts

Keep crew, contractors, and clients in one workspace-wide directory.  
Link contacts to budget lines for automatic contact assignment.  
Store tax info and rate cards for quick reuse across projects.


### List contacts

 - [GET /contacts](https://docs.saturation.io/openapi/contacts/listcontacts.md): Retrieve contacts with optional filtering

### Create contact

 - [POST /contacts](https://docs.saturation.io/openapi/contacts/createcontact.md): Create a new contact

### Get contact

 - [GET /contacts/{contactId}](https://docs.saturation.io/openapi/contacts/getcontact.md): Retrieve a specific contact by ID or alias

### Update contact

 - [PUT /contacts/{contactId}](https://docs.saturation.io/openapi/contacts/updatecontact.md): Update an existing contact

### Upload tax document

 - [POST /contacts/{contactId}/tax-document](https://docs.saturation.io/openapi/contacts/uploadcontacttaxdocument.md): Upload a tax document (e.g., W-9) for a contact.
Accepts PDF or image files up to 10 MB.

### Upload attachment

 - [POST /contacts/{contactId}/attachment](https://docs.saturation.io/openapi/contacts/uploadcontactattachment.md): Upload a file to a contact profile.
Accepts PDF or image files up to 10 MB.

## Rates

Define workspace-wide rate cards for consistent budgeting.  
Set crew rates, equipment packages, and standard costs in multiple currencies.  
Supports automatic fringe calculations.


### List workspace rates

 - [GET /rates](https://docs.saturation.io/openapi/rates/listworkspacerates.md): Retrieve all rates from the workspace

### Create workspace rate

 - [POST /rates](https://docs.saturation.io/openapi/rates/createworkspacerate.md): Create a new rate in the workspace

### Update workspace rate

 - [PUT /rates/{rateId}](https://docs.saturation.io/openapi/rates/updateworkspacerate.md): Update a rate in the workspace

### Delete workspace rate

 - [DELETE /rates/{rateId}](https://docs.saturation.io/openapi/rates/deleteworkspacerate.md): Delete a rate from the workspace

## Transactions

Import raw bank and card data, match to contacts, and convert to actuals.  
Maintains a full audit trail from bank statement to budget line.


### List transactions

 - [GET /transactions](https://docs.saturation.io/openapi/transactions/listtransactions.md): Retrieve financial transactions with comprehensive filtering

### Get transaction

 - [GET /transactions/{transactionId}](https://docs.saturation.io/openapi/transactions/gettransaction.md): Retrieve a specific transaction by ID

### Update transaction

 - [PUT /transactions/{transactionId}](https://docs.saturation.io/openapi/transactions/updatetransaction.md): Update an existing transaction

### Upload transaction attachment

 - [POST /transactions/{transactionId}/attachment](https://docs.saturation.io/openapi/transactions/uploadtransactionattachment.md): Upload an attachment for a transaction

## Budget

Build hierarchical budgets with accounts, line items, subtotals, and markups.  
Use `expands[]=phases&expands[]=fringes&expands[]=globals&expands[]=lines.contact&expands[]=lines.phaseData`  
to fetch complete budget data in one call.  
Reference budget lines by account code (e.g., `"1100-LABOR"`) with `idMode=user`.


### Get budget

 - [GET /projects/{projectId}/budget](https://docs.saturation.io/openapi/budget/getbudget.md): Retrieve budget information for a project

### Create budget lines

 - [POST /projects/{projectId}/budget](https://docs.saturation.io/openapi/budget/createbudgetlines.md): Add new budget lines to an existing account within the budget hierarchy. 

This endpoint creates line items, sub-accounts, subtotals, or markups at the specified location in your budget structure. The target account must already exist in the budget hierarchy.

Use  to add lines at the top level of your budget.


### Get budget line

 - [GET /projects/{projectId}/budget/line/{lineId}](https://docs.saturation.io/openapi/budget/getbudgetline.md): Retrieve a specific budget line by its identifier.

The lineId parameter accepts both user-friendly IDs and system IDs:
- With  (default): Use account codes like "1100" or "camera-dept"
- With : Use UUIDs/nanoids like "abc123xyz" or "550e8400-e29b-41d4-a716"


### Update budget line

 - [PUT /projects/{projectId}/budget/line/{lineId}](https://docs.saturation.io/openapi/budget/updatebudgetline.md): Update an existing budget line with new values.

The lineId in the path accepts both ID formats based on the idMode in the request body:
- User-friendly IDs: Account codes like "2150" or descriptive IDs
- System IDs: Database identifiers when idMode is set to "system"


### Delete budget line

 - [DELETE /projects/{projectId}/budget/line/{lineId}](https://docs.saturation.io/openapi/budget/deletebudgetline.md): Delete a budget line from the project.

The lineId parameter accepts both ID formats:
- With  (default): Use human-readable IDs
- With : Use system-generated IDs


## Budget - Accounts

List all the budget accounts with children (i.e. Expanded Accounts)


### List budget accounts

 - [GET /projects/{projectId}/budget/accounts](https://docs.saturation.io/openapi/budget-accounts/listbudgetaccounts.md): Get a list of all budget accounts in your project, organized from top to bottom.

Returns every account that appears as its own section in your budget. Each account 
is a budget category (like "Camera Department" or "Post-Production") that contains 
its own line items and subtotals.

Perfect for:
- Building dropdown menus to select accounts
- Showing where you are in the budget (like breadcrumbs: Production > Camera > Equipment)
- Getting all account names and codes without loading the entire budget
- Understanding your budget's organization

The accounts come back in a natural reading order—parent accounts first, then their 
children. For example: [/1000 Production, /1000/1100 Camera, /1000/1200 Sound, /2000 Post]

Each account includes a path showing its location in your budget structure. For instance, 
"/2000/2100" means account 2100 sits inside account 2000.

## Budget - Phases

Manage multiple budget versions (estimate, working, actual, committed).  
Create rollup phases to auto-calculate variances.  
Each phase supports its own currency.  
Reference by name (e.g., `"estimate"`) with `idMode=user`.


### List budget phases

 - [GET /projects/{projectId}/budget/phases](https://docs.saturation.io/openapi/budget-phases/listbudgetphases.md): Retrieve all budget phases for a project

### Create budget phase

 - [POST /projects/{projectId}/budget/phases](https://docs.saturation.io/openapi/budget-phases/createbudgetphase.md): Create a new budget phase for a project

### Get budget phase

 - [GET /projects/{projectId}/budget/phases/{phaseId}](https://docs.saturation.io/openapi/budget-phases/getbudgetphase.md): Retrieve a specific budget phase

### Update budget phase

 - [PUT /projects/{projectId}/budget/phases/{phaseId}](https://docs.saturation.io/openapi/budget-phases/updatebudgetphase.md): Update an existing budget phase

### Delete budget phase

 - [DELETE /projects/{projectId}/budget/phases/{phaseId}](https://docs.saturation.io/openapi/budget-phases/deletebudgetphase.md): Delete a budget phase from a project

## Budget - Fringes

Define payroll taxes and benefits (FICA, insurance, workers comp, etc.) once,  
then auto-apply to all labor line items. Supports % or flat rates with salary cutoffs.


### List budget fringes

 - [GET /projects/{projectId}/budget/fringes](https://docs.saturation.io/openapi/budget-fringes/listbudgetfringes.md): Retrieve all fringe benefits for a project

### Create budget fringe

 - [POST /projects/{projectId}/budget/fringes](https://docs.saturation.io/openapi/budget-fringes/createbudgetfringe.md): Create a new fringe benefit for a project

### Get budget fringe

 - [GET /projects/{projectId}/budget/fringes/{fringeId}](https://docs.saturation.io/openapi/budget-fringes/getbudgetfringe.md): Retrieve a specific fringe benefit

### Update budget fringe

 - [PUT /projects/{projectId}/budget/fringes/{fringeId}](https://docs.saturation.io/openapi/budget-fringes/updatebudgetfringe.md): Update an existing fringe benefit

### Delete budget fringe

 - [DELETE /projects/{projectId}/budget/fringes/{fringeId}](https://docs.saturation.io/openapi/budget-fringes/deletebudgetfringe.md): Delete a fringe benefit from a project

## Budget - Globals

Set project-wide variables (e.g., exchange rates, shoot days, overhead %)  
for use in formulas. Updating globals auto-recalculates dependent lines.


### List budget globals

 - [GET /projects/{projectId}/budget/globals](https://docs.saturation.io/openapi/budget-globals/listbudgetglobals.md): Retrieve all global variables for a project

### Create budget global

 - [POST /projects/{projectId}/budget/globals](https://docs.saturation.io/openapi/budget-globals/createbudgetglobal.md): Create a new global variable for a project

### Get budget global

 - [GET /projects/{projectId}/budget/globals/{globalId}](https://docs.saturation.io/openapi/budget-globals/getbudgetglobal.md): Retrieve a specific global variable

### Update budget global

 - [PUT /projects/{projectId}/budget/globals/{globalId}](https://docs.saturation.io/openapi/budget-globals/updatebudgetglobal.md): Update an existing global variable

### Delete budget global

 - [DELETE /projects/{projectId}/budget/globals/{globalId}](https://docs.saturation.io/openapi/budget-globals/deletebudgetglobal.md): Delete a global variable from a project

## Actuals

Log real expenses from credit cards, manual entry, or converted POs.  
Use `expands[]=contact&expands[]=attachments` to include contact details and receipts.  
Split costs across multiple budget categories.


### List actuals

 - [GET /projects/{projectId}/actuals](https://docs.saturation.io/openapi/actuals/listactuals.md): Retrieve actual spending data for a project

### Get actual

 - [GET /projects/{projectId}/actuals/{actualId}](https://docs.saturation.io/openapi/actuals/getactual.md): Retrieve a specific actual entry

### Create actual

 - [POST /projects/{projectId}/actuals/{actualId}](https://docs.saturation.io/openapi/actuals/createactual.md): Create a new actual entry for a project

### Update actual

 - [PUT /projects/{projectId}/actuals/{actualId}](https://docs.saturation.io/openapi/actuals/updateactual.md): Update an existing actual entry

### Delete actual

 - [DELETE /projects/{projectId}/actuals/{actualId}](https://docs.saturation.io/openapi/actuals/deleteactual.md): Delete an actual entry

### Upload actual attachment

 - [POST /projects/{projectId}/actuals/{actualId}/attachment](https://docs.saturation.io/openapi/actuals/uploadactualattachment.md): Upload a receipt or other supporting document for an actual.
Accepts PDF or image files up to 10 MB.

## Purchase Orders

Create commitments to contacts/vendors before they become actuals.  
Track approvals, link to budget lines, and monitor committed vs actual spend.  
Convert POs to actuals when invoiced.


### List purchase orders

 - [GET /projects/{projectId}/purchaseOrders](https://docs.saturation.io/openapi/purchase-orders/listpurchaseorders.md): Retrieve purchase orders for a project

### Get purchase order

 - [GET /projects/{projectId}/purchaseOrders/{purchaseOrderId}](https://docs.saturation.io/openapi/purchase-orders/getpurchaseorder.md): Retrieve a specific purchase order

### Create purchase order

 - [POST /projects/{projectId}/purchaseOrders/{purchaseOrderId}](https://docs.saturation.io/openapi/purchase-orders/createpurchaseorder.md): Create a new purchase order for a project

### Update purchase order

 - [PUT /projects/{projectId}/purchaseOrders/{purchaseOrderId}](https://docs.saturation.io/openapi/purchase-orders/updatepurchaseorder.md): Update an existing purchase order

### Delete purchase order

 - [DELETE /projects/{projectId}/purchaseOrders/{purchaseOrderId}](https://docs.saturation.io/openapi/purchase-orders/deletepurchaseorder.md): Delete a purchase order

### Upload purchase order attachment

 - [POST /projects/{projectId}/purchaseOrders/{purchaseOrderId}/attachment](https://docs.saturation.io/openapi/purchase-orders/uploadpurchaseorderattachment.md): Upload a supporting document for a purchase order.
Accepts PDF or image files up to 10 MB.

## Tags

Categorize beyond account structure—e.g., by shoot day, location, department.  
Use tags to run cross-budget reports and track spend across multiple categories.


### List tags

 - [GET /projects/{projectId}/tags](https://docs.saturation.io/openapi/tags/listtags.md): Retrieve all tags for a project with optional filtering and sorting.

Tags are used for categorizing budget line items and enable advanced filtering
capabilities across budget data. Each tag includes financial totals aggregated
from all associated budget line items.


### Create tag

 - [POST /projects/{projectId}/tags](https://docs.saturation.io/openapi/tags/createtag.md): Create a new tag for the project. Tags are used to categorize budget line items
and enable advanced filtering capabilities.

Note: Tag names cannot be changed after creation. Only the color can be updated.


### Get tag

 - [GET /projects/{projectId}/tags/{tagId}](https://docs.saturation.io/openapi/tags/gettag.md): Retrieve a specific tag by ID, including its financial totals aggregated
from all associated budget line items.


### Update tag

 - [PUT /projects/{projectId}/tags/{tagId}](https://docs.saturation.io/openapi/tags/updatetag.md): Update a tag's properties. Currently, only the color can be updated.
Tag names and descriptions cannot be modified after creation.


### Delete tag

 - [DELETE /projects/{projectId}/tags/{tagId}](https://docs.saturation.io/openapi/tags/deletetag.md): Delete a tag and remove all its assignments from budget line items.
This operation cannot be undone.


## Files

Upload receipts, contracts, and documents.  
Attach files to actuals, POs, and projects.  
Supports batch uploads and direct URL access.


### Upload file

 - [POST /files/upload](https://docs.saturation.io/openapi/files/uploadfile.md): Upload a file to project storage. Accepts PDF or image files up to 10 MB.

### Download file

 - [GET /files/{fileId}/download](https://docs.saturation.io/openapi/files/downloadfile.md): Download/stream a file

### Delete file

 - [DELETE /files/{fileId}](https://docs.saturation.io/openapi/files/deletefile.md): Delete a file from storage

## Public Rates

Browse and use verified industry rate cards from the Saturation community.  
Great for starting points or pricing validation.  
Read-only access to rates from production companies, unions, and contractors.


### List public ratepacks

 - [GET /public/rates](https://docs.saturation.io/openapi/public-rates/listpublicratepacks.md): Retrieve all public ratepacks accessible across workspaces

### Get public rates

 - [GET /public/rates/{ratepackId}](https://docs.saturation.io/openapi/public-rates/getpublicrates.md): Retrieve all rates from a public ratepack

## Spaces

Group projects into folders for better organization.  
Supports nested hierarchies (e.g., by client, year, or production type).


### List spaces

 - [GET /spaces](https://docs.saturation.io/openapi/spaces/listspaces.md): Retrieve all project spaces/folders in the workspace

### Create space

 - [POST /spaces](https://docs.saturation.io/openapi/spaces/createspace.md): Create a new project space/folder

### Get space

 - [GET /spaces/{spaceId}](https://docs.saturation.io/openapi/spaces/getspace.md): Retrieve a specific space by ID or alias

### Update space

 - [PUT /spaces/{spaceId}](https://docs.saturation.io/openapi/spaces/updatespace.md): Update an existing space

### Delete space

 - [DELETE /spaces/{spaceId}](https://docs.saturation.io/openapi/spaces/deletespace.md): Soft delete a space (must not contain active projects)

## Comments

Add notes and discussions directly on budget lines.  
Track approvals and changes with timestamps—context stays intact across phases.


### List comments

 - [GET /projects/{projectId}/comments](https://docs.saturation.io/openapi/comments/listcomments.md): Retrieve all comments for a project's budget