Skip to content

⚒️ API Reference (1.0.0)

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

GET /api/v1/projects
X-API-Key: YOUR_API_KEY


📊 Get everything in one call

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

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

# 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
Download OpenAPI description
openapi.json
openapi.yaml
Overview
URL

https://support.saturation.io

License

Proprietary

Languages
Servers
Production server

https://api.saturation.io/api/v1/

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.

Operations

List projects

Request

Retrieve projects for the current workspace. Supports filtering by ID, space, status, name, space name, or labels.

Security
ApiKeyAuth
Query
idstring or Array of strings

Return only projects matching these IDs or aliases

Example: id=nike-swoosh-commercial
One of:
string
spaceIdstring or Array of strings

Return projects belonging to these space IDs or aliases

Example: spaceId=commercial-productions
One of:
string
statusstring

Filter by project status

Enum"active""archived"
Example: status=active
namestring or Array of strings

Case-insensitive substring match on project name

Example: name=Swoosh
One of:
string
spaceNamestring or Array of strings

Case-insensitive substring match on space name

Example: spaceName=Commercial
One of:
string
labelsstring or Array of strings

Return projects that include all specified labels

Example: labels=nike&labels=q2-2024
One of:
string
curl -i -X GET \
  'https://api.saturation.io/api/v1/projects?id=nike-swoosh-commercial&spaceId=commercial-productions&status=active&name=Swoosh&spaceName=Commercial&labels=nike%2Cq2-2024' \
  -H 'X-API-Key: YOUR_API_KEY_HERE'

Responses

List of projects

Bodyapplication/json
projectsArray of objects(Project)
Response
application/json
{
  "projects": [
    { … }
  ]
}

Create project

Request

Create a new project in the current workspace

Security
ApiKeyAuth
Bodyapplication/jsonrequired
namestring or null

Project display name (defaults to "Untitled Project")

Example: "Nike Holiday Commercial"
iconstring or null

Project icon or emoji

Example: "📊"
imageUrlstring or null

Project image URL

Example: "https://example.com/banner.jpg"
spaceIdstring or null

Associated project space ID

Example: "commercial-productions"
statusstring

Project status

Default "active"
Enum"active""archived"
Example: "active"
templateIdstring or null

Template project ID if creating from template

Example: "commercial-template-v2"
labelsArray of strings

Labels to assign to the project (will be created if they don't exist)

Example: ["marketing","q4-2024"]
curl -i -X POST \
  https://api.saturation.io/api/v1/projects \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{
    "name": "Nike Holiday Commercial",
    "icon": "📊",
    "imageUrl": "https://example.com/banner.jpg",
    "spaceId": "commercial-productions",
    "status": "active",
    "templateId": "commercial-template-v2",
    "labels": [
      "marketing",
      "q4-2024"
    ]
  }'

Responses

Project created successfully

Bodyapplication/json
idstringrequired

Project identifier (alias in user mode, UUID in system mode)

Example: "nike-swoosh-commercial"
namestring or null

Project display name

Example: "Nike Swoosh Commercial"
iconstring or null

Project icon or emoji

Example: "☀️"
imageUrlstring or null

Project image URL

Example: "https://example.com/project-banner.jpg"
spaceIdstring or null

Associated project space ID (deprecated, use space object)

Example: "commercial-productions"
spaceobject or null

Project space/folder information

templateIdstring or null

Template project ID (deprecated, use template object)

Example: "commercial-template"
templateobject or null

Template project information

statusstringrequired

Project status

Enum"active""archived"
Example: "active"
labelsArray of strings

Project labels for categorization

Example: ["nike","q2-2024","post-production"]
createdAtstring(date-time)required

Project creation timestamp

Example: "2024-01-15T10:00:00Z"
updatedAtstring(date-time)required

Project last update timestamp

Example: "2024-03-20T14:30:00Z"
Response
application/json
{
  "id": "nike-swoosh-commercial",
  "name": "Nike Swoosh Commercial",
  "icon": "☀️",
  "imageUrl": "https://example.com/project-banner.jpg",
  "spaceId": "commercial-productions",
  "space": {
    "id": "commercial-productions",
    "name": "Commercial Productions"
  },
  "templateId": "commercial-template",
  "template": {
    "id": "commercial-template",
    "name": "Commercial Template"
  },
  "status": "active",
  "labels": [
    "nike",
    "q2-2024",
    "post-production"
  ],
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-03-20T14:30:00Z"
}

Get project

Request

Retrieve a project by its ID or alias

Security
ApiKeyAuth
Path
projectIdstringrequired

Project identifier (alias or ID)

Example: nike-spring-2024
curl -i -X GET \
  https://api.saturation.io/api/v1/projects/nike-spring-2024 \
  -H 'X-API-Key: YOUR_API_KEY_HERE'

Responses

Project details

Bodyapplication/json
idstringrequired

Project identifier (alias in user mode, UUID in system mode)

Example: "nike-swoosh-commercial"
namestring or null

Project display name

Example: "Nike Swoosh Commercial"
iconstring or null

Project icon or emoji

Example: "☀️"
imageUrlstring or null

Project image URL

Example: "https://example.com/project-banner.jpg"
spaceIdstring or null

Associated project space ID (deprecated, use space object)

Example: "commercial-productions"
spaceobject or null

Project space/folder information

templateIdstring or null

Template project ID (deprecated, use template object)

Example: "commercial-template"
templateobject or null

Template project information

statusstringrequired

Project status

Enum"active""archived"
Example: "active"
labelsArray of strings

Project labels for categorization

Example: ["nike","q2-2024","post-production"]
createdAtstring(date-time)required

Project creation timestamp

Example: "2024-01-15T10:00:00Z"
updatedAtstring(date-time)required

Project last update timestamp

Example: "2024-03-20T14:30:00Z"
Response
application/json
{
  "id": "nike-swoosh-commercial",
  "name": "Nike Swoosh Commercial",
  "icon": "☀️",
  "imageUrl": "https://example.com/project-banner.jpg",
  "spaceId": "commercial-productions",
  "space": {
    "id": "commercial-productions",
    "name": "Commercial Productions"
  },
  "templateId": "commercial-template",
  "template": {
    "id": "commercial-template",
    "name": "Commercial Template"
  },
  "status": "active",
  "labels": [
    "nike",
    "q2-2024",
    "post-production"
  ],
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-03-20T14:30:00Z"
}

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.

Operations

Rates

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

Operations

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.

Operations

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.

Operations

Budget - Accounts

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

Operations

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.

Operations

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.

Operations

Budget - Globals

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

Operations

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.

Operations

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.

Operations

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.

Operations

Files

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

Operations

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.

Operations

Spaces

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

Operations

Comments

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

Operations