Falcon Operations REST API v1

Base URL: https://operations.wearefalcon.tv/api/v1
Format: JSON; multipart form data for file uploads
Authentication: user-created Falcon Operations Bearer tokens

Overview

The Falcon Operations REST API is the supported integration surface for managing Operations workspaces, productions, people and assets, bookings and handover, production planning data, notes and files. It uses the same workspace roles, access groups, production filters, module permissions and license limits as the Falcon Operations web app.

Use this API for scheduling tools, production dashboards, inventory integrations, automation services, migration scripts and other server-to-server workflows that need concrete Operations data.

Public REST API vs the browser API

Falcon Rundown Gateway/MOS APIs solve published-rundown and media exchange workflows. Use this Operations REST API for Operations management data.

Authentication and token lifecycle

Every REST endpoint requires a Bearer token:

Authorization: Bearer fo_live_...

Create tokens in Falcon Operations from the footer user menu under API Tokens. Enter a descriptive name, choose scopes and optionally set an expiry. Falcon shows the full token once and stores only an HMAC-SHA-256 hash. The dialog shows each token's prefix, scopes, expiry, last use and state, and lets the owner revoke it.

export FALCON_OPERATIONS_TOKEN='fo_live_...'

curl \
  -H "Authorization: Bearer $FALCON_OPERATIONS_TOKEN" \
  https://operations.wearefalcon.tv/api/v1/me

Scopes

Write scopes also grant the matching read permission. Scopes do not bypass the token user's normal Falcon permissions.

Roles and access rules

Opaque IDs and field names

REST responses use opaque public IDs and snake_case JSON fields. Sequential database IDs and legacy browser-route IDs are never part of the public contract.

Responses, pagination and errors

Single resource

{
  "data": {
    "id": "prj_...",
    "workspace_id": "wsp_...",
    "name": "Summer campaign"
  }
}

List

{
  "data": [],
  "meta": {
    "count": 0,
    "limit": 100,
    "offset": 0
  }
}

List endpoints accept limit (1-200), offset, and resource-specific search and status filters. Bookings also accept production_id.

Error

{
  "error": {
    "code": "scope_required",
    "message": "Token scope tasks:write is required.",
    "request_id": "..."
  }
}

Deletes return 204 No Content.

Endpoint summary

Current user and workspaces

Members and access groups

Productions

Resources and assets

Bookings and handover

Production planning

Budgets

Budget-sheet responses include row count, income, expenses, actuals and results. Account-plan entries are organisation-wide but routed through a production so normal budget access is always checked.

Guests

Guest-booking lists accept start, end and status. Acceptance secrets and accepting IP addresses are never exposed.

Call sheet content

Each collection supports GET/POST; each item supports GET/PATCH/DELETE. Creates reference resource_id, equipment_id or vehicle_id. Schedule items require start_time and activity; contacts require name.

Common examples

Create a production

curl -X POST \
  -H "Authorization: Bearer $FALCON_OPERATIONS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Summer campaign",
    "code": "SUM-26",
    "type": "commercial",
    "status": "planning",
    "client_name": "Example Client",
    "start_date": "2026-08-01",
    "end_date": "2026-08-14",
    "currency": "DKK",
    "total_budget": 250000
  }' \
  https://operations.wearefalcon.tv/api/v1/workspaces/wsp_.../productions

Create equipment

{
  "name": "Sony FX6",
  "category": "Camera",
  "manufacturer": "Sony",
  "model": "FX6",
  "serial_number": "EXAMPLE-001",
  "status": "available",
  "home_location_id": "loc_...",
  "daily_rate": 1250,
  "currency": "DKK",
  "tags": ["camera", "full-frame"]
}

Equipment, vehicle and space status values are available, in_use, maintenance and retired. Active bookings must be completed or cancelled before deleting an asset.

Create a booking

{
  "title": "Camera package",
  "booked_for_resource_id": "res_...",
  "production_id": "prj_...",
  "starts_at": "2026-08-03T08:00:00+02:00",
  "ends_at": "2026-08-03T18:00:00+02:00",
  "status": "confirmed",
  "purpose": "Location shoot",
  "items": [
    {"asset_type": "equipment", "asset_id": "eqp_..."},
    {"asset_type": "vehicle", "asset_id": "veh_..."}
  ]
}

Detected overlaps are returned in meta.conflicts. Checkout locks ordinary status and manifest changes until all items are returned.

Checkout

{
  "asset_type": "equipment",
  "asset_id": "eqp_...",
  "condition": "Complete and undamaged"
}

Return

{
  "asset_type": "equipment",
  "asset_id": "eqp_...",
  "location_id": "loc_...",
  "condition": "Returned in good condition"
}

Create a task

{
  "title": "Confirm camera crew",
  "description": "Confirm availability and rates",
  "status": "todo",
  "priority": "high",
  "assignee_email": "producer@example.com",
  "due_date": "2026-08-01",
  "tags": ["crew"]
}

Task status is the production's task-column key. Priority values are low, medium, high and urgent.

Assign production crew

{
  "resource_id": "res_...",
  "role": "Director of Photography",
  "start_date": "2026-08-01",
  "end_date": "2026-08-14",
  "daily_rate": 6500
}

Create a budget row

{
  "account_id": "acc_...",
  "description": "Camera crew",
  "quantity": 3,
  "unit": "days",
  "unit_price": 6500,
  "currency": "DKK",
  "approval_status": "draft"
}

row_type is entry, groupHeader, subtotal or textOnly. Approval status is draft, pending, approved or rejected.

Create a guest booking

{
  "guest_id": "gst_...",
  "title": "Guest appearance",
  "starts_at": "2026-08-03T10:00:00+02:00",
  "ends_at": "2026-08-03T11:00:00+02:00",
  "location": "Studio A",
  "live_link": "https://example.com/live"
}

Create a calendar event

{
  "title": "Location scout",
  "start_at": "2026-08-01T09:00:00+02:00",
  "end_at": "2026-08-01T11:00:00+02:00",
  "all_day": false,
  "location": "Example address"
}

Create a call sheet

{
  "title": "Shoot day 1",
  "date": "2026-08-03",
  "call_time": "07:00:00",
  "wrap_time": "18:00:00",
  "location": "Studio A",
  "status": "draft",
  "general_notes": "Bring ID"
}

Call sheet status values are draft, published, archived and cancelled.

Update a rich production note

Rich note content is TipTap JSON. Updates use optimistic concurrency and require the version most recently read:

{
  "expected_version": 3,
  "title": "Updated production note",
  "content": {
    "type": "doc",
    "content": [
      {
        "type": "paragraph",
        "content": [{"type": "text", "text": "Hello"}]
      }
    ]
  },
  "plain_text": "Hello"
}

A stale version returns 409 version_conflict.

Upload a file

curl -X POST \
  -H "Authorization: Bearer $FALCON_OPERATIONS_TOKEN" \
  -F "file=@brief.pdf" \
  -F "description=Client brief" \
  https://operations.wearefalcon.tv/api/v1/productions/prj_.../files

The maximum file size is 20 MB. Executable and active web content types are blocked. The returned content_url also requires the Bearer token.

Validation and conflict protections

• Location trees reject cycles and duplicate sibling codes. Locations with children or assigned assets cannot be deleted.
• Bookings validate that resources and assets belong to the same workspace and return overlap details.
• Booking handover uses database row locks and records checkout/return condition and location history.
• Rich notes use versions to prevent overwriting another editor's changes.
• Workspace, module, production-filter and license checks run for every endpoint.
• Every REST mutation writes actor, token, request ID, action and public resource ID to the Operations audit log.

HTTP status codes

Troubleshooting

401 authentication_required

Add the Authorization: Bearer ... header. Do not send tokens in the URL.

401 invalid_token

The token is wrong, expired or revoked, or its Falcon user is no longer active. Create a new token in Operations.

403 scope_required

Create a new token with the named scope. Existing token scopes cannot be broadened after creation.

403 forbidden

The token user lacks the required workspace, production, access-group, module or license permission.

404 not_found

Confirm that the opaque ID uses the correct prefix for the route and that the resource has not been deleted.

409 handover_locked

Return every checked-out item before replacing the manifest, changing ordinary status or deleting the booking.

409 version_conflict

Reload the rich note and retry with its newest version as expected_version.

Browser integrations

The API is designed primarily for server-to-server clients. If a browser sends Origin or Referer, it must match the configured Falcon Operations origin.