Falcon Rundown REST API Falcon Rundown

Base URL: https://rundown.wearefalcon.tv/api/v1
Format: JSON requests and JSON responses
Authentication: User-created Bearer tokens from Falcon Rundown

Overview

The Falcon Rundown REST API is a structured control and data API for external systems that need to manage workspaces, members, folders, rundowns and stories in Falcon Rundown. It is built on the same access model as the Falcon Rundown web app, so workspace ownership, member roles, rundown filters and archived-rundown protections are enforced server-side.

Use this API when an integration needs to create, read, update, publish, archive, duplicate or delete concrete Falcon Rundown objects. Typical use cases include newsroom automation, planning dashboards, custom editorial tools, data migration scripts, scheduling workflows and system-to-system workspace management.

REST API vs Gateway API

Falcon Rundown has more than one integration surface. The REST API and Gateway API are related, but they solve different problems.

In short: use the Gateway API to consume or transact with published rundown/media flows. Use the REST API to manage the underlying Falcon Rundown workspace data.

Base URL and request format

https://rundown.wearefalcon.tv/api/v1

All request and response bodies are JSON. For POST and PATCH requests, send:

Content-Type: application/json

Example request:

curl -H "Authorization: Bearer $FALCON_RUNDOWN_TOKEN" \
  https://rundown.wearefalcon.tv/api/v1/workspaces

Authentication

Every REST endpoint requires a Bearer token.

Authorization: Bearer fr_live_...

Users create tokens inside Falcon Rundown from the Workspaces page footer user badge menu under API Tokens. A token is shown only once when created. Falcon stores only a hashed version of the token.

Scopes

Each token has scopes. Write scopes also allow the matching read operation.

Roles and access rules

The REST API reuses Falcon Rundown workspace roles:

Member rundown filters are respected. If a member is filtered to specific folders or rundowns, the REST API will only expose allowed rundowns and stories.

Response model

Successful responses use a consistent envelope:

{
  "data": {},
  "meta": {}
}

List responses include pagination metadata when relevant:

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

REST-layer errors use:

{
  "error": {
    "code": "missing_bearer_token",
    "message": "Use Authorization: Bearer <token>."
  }
}

REST Resource IDs

REST v1 now exposes stable opaque resource IDs instead of internal database integers. They are intentionally token-like, safe to pass to integrations, and should be treated as strings.

Use these IDs in URL paths and JSON fields such as folder_id, parent_id, rundown_id and story reorder payloads. New clients should not store or depend on numeric database IDs. Legacy numeric IDs are still accepted by the router for backwards compatibility, but REST responses return the opaque format.

GET /api/v1/workspaces/prj_mUN_3p5tpK3eqYFc/rundowns
GET /api/v1/rundowns/rdn_Izqszf4NCzaf2Pag/stories
PATCH /api/v1/stories/sto_-sfWOvHnMyuds9XV

Status codes

Endpoint summary

Identity

Verify token

Returns the token user and token metadata.

{
  "data": {
    "user": {
      "id": 43271,
      "email": "user@example.com",
      "name": "Example User"
    },
    "token": {
      "id": 4,
      "name": "Production integration",
      "prefix": "fr_live_abc123",
      "scopes": ["workspaces:read", "rundowns:read"]
    }
  }
}

Workspaces

List workspaces

Returns owned and shared workspaces visible to the token user. Supports limit and offset.

curl -H "Authorization: Bearer $FALCON_RUNDOWN_TOKEN" \
  "https://rundown.wearefalcon.tv/api/v1/workspaces?limit=50"

Create workspace

{
  "name": "Evening News",
  "asset_package_id": 7
}

asset_package_id is optional.

Read workspace

Returns workspace metadata and the current user's role.

Update workspace

{
  "name": "Evening News Updated",
  "asset_package_id": null
}

Requires owner access.

Delete workspace

Requires owner access. This removes workspace members, folders, rundowns and stories belonging to the workspace.

Members

List members

Returns owner and member rows with roles and any rundown/folder filters.

Add or update member

{
  "email": "producer@example.com",
  "role": "rw"
}

Allowed roles are superuser, rw, comment and ro. Requires owner or superuser access.

Change member role

{
  "role": "superuser"
}

Remove member

URL-encode the email address if needed.

Folders

List folders

Returns folders in the workspace. Each row includes id, workspace_id, parent_id, name and updated_at.

Create folder

{
  "name": "Studio rundowns",
  "parent_id": null
}

Rundowns

List rundowns

Lists active rundowns in the workspace. Supports limit, offset, folder_id and include_archived=1.

curl -H "Authorization: Bearer $FALCON_RUNDOWN_TOKEN" \
  "https://rundown.wearefalcon.tv/api/v1/workspaces/prj_mUN_3p5tpK3eqYFc/rundowns?limit=25&offset=0"

Rundown responses include a token field. This is the encrypted rundown ID used by Gateway/MOS-style integrations. It is not the same as the REST Bearer token.

Create rundown

{
  "title": "Evening News 18:00",
  "type": "rundown",
  "folder_id": null,
  "rundown_date": "2026-06-11",
  "start_time": "18:00:00",
  "end_time": "19:00:00"
}

type can be rundown or notelist.

Read rundown

Returns metadata, publish state, on-air state, encrypted Gateway token and tags.

Update rundown

{
  "title": "Evening News Updated",
  "start_time": "18:05:00",
  "end_time": "19:00:00",
  "rundown_date": "2026-06-11",
  "ignore_vo_time": false,
  "layout_id": null
}

Archived rundowns are read-only and return 409 for write endpoints.

Delete rundown

Duplicate rundown

Copies rundown metadata, stories and tags into a new rundown. The new rundown is not published by default.

Archive or restore rundown

Archiving a rundown also clears its Gateway publish state.

Publishing to Gateway catalog

REST can mark a rundown as published or unpublished. Published rundowns are eligible for Gateway catalog discovery. Gateway clients still consume the Gateway API; REST only controls the publish flag on the Rundown side.

Publish rundown

{
  "data": {
    "id": "rdn_Izqszf4NCzaf2Pag",
    "gateway_published": true
  }
}

Unpublish rundown

Stories

List stories

Returns stories ordered by pos. Story bodies are returned as HTML in text_html.

Create story

{
  "pos": 0,
  "type": "story",
  "title": "Opening headlines"
}

Read story

Update story

Any subset of these fields can be sent:

{
  "title": "Updated title",
  "comments": "Producer notes",
  "story_time": "00:01:30",
  "vo_time": "00:00:20",
  "total_time": "00:01:50",
  "text_html": "<p>Script body</p>",
  "type": "story",
  "bg_color": "cam",
  "links": null,
  "files": null,
  "isTemplate": 0,
  "parked": 0,
  "seq": 1,
  "pos": 0
}

Delete story

Reorder stories

{
  "stories": [
    { "id": "sto_-sfWOvHnMyuds9XV", "pos": 0 },
    { "id": "sto_ixizDXWUj_9MIWBY", "pos": 1 }
  ]
}

Common examples

Verify token

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

List workspaces

curl -H "Authorization: Bearer $FALCON_RUNDOWN_TOKEN" \
  https://rundown.wearefalcon.tv/api/v1/workspaces

Create a rundown

curl -X POST \
  -H "Authorization: Bearer $FALCON_RUNDOWN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "title": "Morning Show",
        "type": "rundown",
        "folder_id": null,
        "rundown_date": "2026-06-11",
        "start_time": "08:00:00",
        "end_time": "09:00:00"
      }' \
  https://rundown.wearefalcon.tv/api/v1/workspaces/prj_mUN_3p5tpK3eqYFc/rundowns

Create a story

curl -X POST \
  -H "Authorization: Bearer $FALCON_RUNDOWN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"pos":0,"type":"story","title":"Opening"}' \
  https://rundown.wearefalcon.tv/api/v1/rundowns/rdn_Izqszf4NCzaf2Pag/stories

Publish a rundown for Gateway discovery

curl -X POST \
  -H "Authorization: Bearer $FALCON_RUNDOWN_TOKEN" \
  https://rundown.wearefalcon.tv/api/v1/rundowns/rdn_Izqszf4NCzaf2Pag/publish

Python

import os, requests

BASE = "https://rundown.wearefalcon.tv/api/v1"
TOKEN = os.environ["FALCON_RUNDOWN_TOKEN"]
headers = {"Authorization": f"Bearer {TOKEN}"}

workspaces = requests.get(f"{BASE}/workspaces", headers=headers).json()
print(workspaces)

workspace_id = workspaces["data"][0]["id"]
rundowns = requests.get(
    f"{BASE}/workspaces/{workspace_id}/rundowns",
    headers=headers,
    params={"limit": 25},
).json()
print(rundowns)

Recommended integration workflow

1. Create a dedicated API token from Falcon Rundown with only the scopes the integration needs.
2. Call GET /me to verify the token and token user.
3. Call GET /workspaces and select the workspace by ID.
4. Read members, folders and rundowns as needed.
5. For write integrations, create or update a test workspace first.
6. If Gateway or MOS consumers need the rundown, publish the rundown with REST, then consume it through the Gateway API.

Troubleshooting

Version notes

This manual documents Falcon Rundown REST API v1 as introduced in June 2026. The API is designed to coexist with the existing Falcon Rundown web app API and the Gateway API. Resource IDs are exposed as opaque strings with prj_, fld_, rdn_ and sto_ prefixes; numeric IDs are accepted only for legacy compatibility.