FoxCueDocs
Open FoxCue
API reference

FoxCue API: Recordings and Media download and Director media and more

Request examples, parameters, scopes and response statuses for FoxCue API recordings and media download and director media and more.

These operations are copied from the live OpenAPI schema at GET /api/v1/openapi.json (2026-10-28, 297 operations). Each example request is built from that operation's schema: required fields, and optional fields when the object is small. Response bodies are not in that schema. Where the JSON shape is known, it is listed below with an example. Shared errors are on Limits and errors.

Send Authorization: Bearer <workspace API key>. Base URL: https://app.foxcue.com/api/v1.

Recordings

GET /recordings

List uploaded recording sessions

Scope: media:read.

Parameters

NameInRequiredTypeRules
project_idquerynostring
script_idquerynostring
collection_idquerynostring
scope_typequerynostring
scope_idquerynostring
kindquerynostring
limitquerynostring
offsetquerynostring

Example request

curl -X GET "https://app.foxcue.com/api/v1/recordings?project_id=example&script_id=example&collection_id=example&scope_type=example&scope_id=example&kind=example" \
  -H "Authorization: Bearer <workspace API key>"

Response

The body is a JSON array of these fields. limit is 1–100 (default 50) and offset starts at 0. The array has no total.

FieldType
idstring
org_idstring
script_idstring
collection_idstring
titlestring
statusstring
aspectstring
duration_snumber
created_atstring
updated_atstring
[
  {
    "id": "id",
    "org_id": "workspace_id",
    "script_id": "id",
    "collection_id": "id",
    "title": "example",
    "status": "queued",
    "aspect": "example",
    "duration_s": 0,
    "created_at": "2026-10-28T00:00:00.000Z",
    "updated_at": "2026-10-28T00:00:00.000Z"
  }
]
StatusMeaning
200Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

POST /recordings

Create recording session before uploading a source

Scope: media:write.

Example request

{
  "title": "example",
  "status": "draft",
  "aspect": "16:9",
  "duration_s": 0,
  "capture_id": "00000000-0000-4000-8000-000000000000"
}
curl -X POST "https://app.foxcue.com/api/v1/recordings" \
  -H "Authorization: Bearer <workspace API key>" \
  -H "Content-Type: application/json" \
  -d @body.json

Response

The body is a JSON object with these fields.

FieldType
idstring
org_idstring
script_idstring
collection_idstring
titlestring
statusstring
aspectstring
duration_snumber
created_atstring
updated_atstring
{
  "id": "id",
  "org_id": "workspace_id",
  "script_id": "id",
  "collection_id": "id",
  "title": "example",
  "status": "queued",
  "aspect": "example",
  "duration_s": 0,
  "created_at": "2026-10-28T00:00:00.000Z",
  "updated_at": "2026-10-28T00:00:00.000Z"
}
StatusMeaning
201Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

GET /recordings/{id}

Read recording session

Scope: media:read.

Parameters

NameInRequiredTypeRules
idpathyesstring

Example request

curl -X GET "https://app.foxcue.com/api/v1/recordings/example" \
  -H "Authorization: Bearer <workspace API key>"

Response

The body is a JSON object with these fields.

FieldType
idstring
org_idstring
script_idstring
collection_idstring
titlestring
statusstring
aspectstring
duration_snumber
created_atstring
updated_atstring
{
  "id": "id",
  "org_id": "workspace_id",
  "script_id": "id",
  "collection_id": "id",
  "title": "example",
  "status": "queued",
  "aspect": "example",
  "duration_s": 0,
  "created_at": "2026-10-28T00:00:00.000Z",
  "updated_at": "2026-10-28T00:00:00.000Z"
}
StatusMeaning
200Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

POST /recordings/{id}/sources/upload

Upload recording track; use upload_id UUID for retry protection

Scope: media:write.

Parameters

NameInRequiredTypeRules
idpathyesstring

Example request

Body is raw bytes (video/webm), not JSON.

curl -X POST "https://app.foxcue.com/api/v1/recordings/example/sources/upload" \
  -H "Authorization: Bearer <workspace API key>" \
  --data-binary @file

Response

StatusMeaning
201Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

Media download

GET /media

Download owned media using the key query parameter

Scope: media:read.

Parameters

NameInRequiredTypeRules
keyqueryyesstring

Example request

curl -X GET "https://app.foxcue.com/api/v1/media?key=example" \
  -H "Authorization: Bearer <workspace API key>"

Response

StatusMeaning
200Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

Editing runs

GET /editing/styles

Available recording editing styles and their treatment

Scope: media:read.

Parameters

NameInRequiredTypeRules
project_idquerynostring
script_idquerynostring
collection_idquerynostring
scope_typequerynostring
scope_idquerynostring
kindquerynostring
limitquerynostring
offsetquerynostring

Example request

curl -X GET "https://app.foxcue.com/api/v1/editing/styles?project_id=example&script_id=example&collection_id=example&scope_type=example&scope_id=example&kind=example" \
  -H "Authorization: Bearer <workspace API key>"

Response

StatusMeaning
200Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

POST /editing/styles/{ref}/copies

Save a customized copy of an editing style in Library

Scope: media:write.

Parameters

NameInRequiredTypeRules
refpathyesstring

Example request

{
  "name": "example",
  "settings": {
    "schema": 1,
    "family": "clean",
    "pacing": "calm",
    "presenter_corner": "top-right",
    "canvas": "dark",
    "blocks": [
      "example"
    ],
    "references": [
      {
        "title": "example",
        "url": "example",
        "technique": "example"
      }
    ],
    "presenter_crop": "center",
    "presentation": {
      "version": 1,
      "presenter_percent": 0,
      "min_visual_seconds": 3,
      "max_visual_seconds": 4,
      "max_presenter_seconds": 3
    },
    "accepts": [
      "video"
    ]
  }
}

Required fields: name, settings.

curl -X POST "https://app.foxcue.com/api/v1/editing/styles/example/copies" \
  -H "Authorization: Bearer <workspace API key>" \
  -H "Content-Type: application/json" \
  -d @body.json

Response

StatusMeaning
201Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

GET /editing/runs

List durable video edit runs, optionally filtered by composition_id

Scope: jobs:read.

Parameters

NameInRequiredTypeRules
project_idquerynostring
script_idquerynostring
collection_idquerynostring
scope_typequerynostring
scope_idquerynostring
kindquerynostring
limitquerynostring
offsetquerynostring

Example request

curl -X GET "https://app.foxcue.com/api/v1/editing/runs?project_id=example&script_id=example&collection_id=example&scope_type=example&scope_id=example&kind=example" \
  -H "Authorization: Bearer <workspace API key>"

Response

StatusMeaning
200Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

POST /editing/runs

Edit an owned recording with original voice, timed captions, automatic owned Library cutaways and editorial motion blocks. Also requires media:write.

Scope: generation:write.

Example request

{
  "idempotency_key": "example-",
  "media_id": "example",
  "recording_id": "example",
  "title": "example"
}

Required fields: idempotency_key.

curl -X POST "https://app.foxcue.com/api/v1/editing/runs" \
  -H "Authorization: Bearer <workspace API key>" \
  -H "Content-Type: application/json" \
  -d @body.json

Response

StatusMeaning
202Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

GET /editing/runs/{id}

Read a durable editing run, progress, decisions and checked output

Scope: jobs:read.

Parameters

NameInRequiredTypeRules
idpathyesstring

Example request

curl -X GET "https://app.foxcue.com/api/v1/editing/runs/example" \
  -H "Authorization: Bearer <workspace API key>"

Response

StatusMeaning
200Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

POST /editing/runs/{id}/cancel

Cancel editing; retain originals and completed work

Scope: generation:write.

Parameters

NameInRequiredTypeRules
idpathyesstring

Example request

curl -X POST "https://app.foxcue.com/api/v1/editing/runs/example/cancel" \
  -H "Authorization: Bearer <workspace API key>"

Response

StatusMeaning
201Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

POST /editing/runs/{id}/retry

Resume a failed edit from retained completed stages

Scope: generation:write.

Parameters

NameInRequiredTypeRules
idpathyesstring

Example request

curl -X POST "https://app.foxcue.com/api/v1/editing/runs/example/retry" \
  -H "Authorization: Bearer <workspace API key>"

Response

StatusMeaning
202Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

POST /editing/runs/{id}/rebuild

Rebuild an owned edit with the same narration, timing, style and plan. Creates a new revision and checked output without AI replanning. Also requires media:write.

Scope: generation:write.

Parameters

NameInRequiredTypeRules
idpathyesstring

Example request

{
  "base_revision": 1,
  "idempotency_key": "example-",
  "visual_direction": true
}

Required fields: base_revision, idempotency_key.

curl -X POST "https://app.foxcue.com/api/v1/editing/runs/example/rebuild" \
  -H "Authorization: Bearer <workspace API key>" \
  -H "Content-Type: application/json" \
  -d @body.json

Response

StatusMeaning
202Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

Director media

POST /director/from-recording

Open an owned recorded or uploaded video as an editable composition, preserving original audio and order; no AI or captions are generated

Scope: media:write.

Example request

{
  "media_id": "example",
  "recording_id": "example",
  "title": "example",
  "recipe": {
    "id": "example",
    "revision": "example",
    "format": "example"
  },
  "aspect": "16:9",
  "script_id": "example",
  "idempotency_key": "example-"
}
curl -X POST "https://app.foxcue.com/api/v1/director/from-recording" \
  -H "Authorization: Bearer <workspace API key>" \
  -H "Content-Type: application/json" \
  -d @body.json

Response

StatusMeaning
201Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

GET /director/media

List reusable screenshots and video recordings in this workspace

Scope: media:read.

Parameters

NameInRequiredTypeRules
project_idquerynostring
script_idquerynostring
collection_idquerynostring
scope_typequerynostring
scope_idquerynostring
kindquerynostring
limitquerynostring
offsetquerynostring

Example request

curl -X GET "https://app.foxcue.com/api/v1/director/media?project_id=example&script_id=example&collection_id=example&scope_type=example&scope_id=example&kind=example" \
  -H "Authorization: Bearer <workspace API key>"

Response

StatusMeaning
200Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

POST /director/media

Upload a reusable screenshot or recorded video with raw bytes (API64MiB; browser500MB). Optional name and description query fields. Each accepted upload creates one new asset.

Scope: media:write.

Example request

Body is raw bytes (image/png), not JSON.

curl -X POST "https://app.foxcue.com/api/v1/director/media" \
  -H "Authorization: Bearer <workspace API key>" \
  --data-binary @file

Response

StatusMeaning
201Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

GET /director/blocks

List reusable animation blocks and typed parameters for composition edits

Scope: media:read.

Parameters

NameInRequiredTypeRules
project_idquerynostring
script_idquerynostring
collection_idquerynostring
scope_typequerynostring
scope_idquerynostring
kindquerynostring
limitquerynostring
offsetquerynostring

Example request

curl -X GET "https://app.foxcue.com/api/v1/director/blocks?project_id=example&script_id=example&collection_id=example&scope_type=example&scope_id=example&kind=example" \
  -H "Authorization: Bearer <workspace API key>"

Response

StatusMeaning
200Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

Compositions

GET /compositions/{id}

Read an owned editable video composition and its resolved timeline

Scope: outputs:read.

Parameters

NameInRequiredTypeRules
idpathyesstring

Example request

curl -X GET "https://app.foxcue.com/api/v1/compositions/example" \
  -H "Authorization: Bearer <workspace API key>"

Response

StatusMeaning
200Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

POST /compositions/{id}/ops

Apply reversible composition edits against a required base revision

Scope: media:write.

Parameters

NameInRequiredTypeRules
idpathyesstring

Example request

{
  "base_revision": 1,
  "ops": [
    "example"
  ],
  "summary": "example"
}

Required fields: base_revision, ops.

curl -X POST "https://app.foxcue.com/api/v1/compositions/example/ops" \
  -H "Authorization: Bearer <workspace API key>" \
  -H "Content-Type: application/json" \
  -d @body.json

Response

StatusMeaning
200Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

POST /compositions/{id}/render

Render a reviewed composition revision into a saved video output; poll compositions/render-jobs/{jobId}

Scope: generation:write.

Parameters

NameInRequiredTypeRules
idpathyesstring

Example request

{
  "base_revision": 1,
  "idempotency_key": "example-"
}

Required fields: base_revision, idempotency_key.

curl -X POST "https://app.foxcue.com/api/v1/compositions/example/render" \
  -H "Authorization: Bearer <workspace API key>" \
  -H "Content-Type: application/json" \
  -d @body.json

Response

StatusMeaning
202Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

GET /compositions/render-jobs/{jobId}

Poll this workspace composition render job; interrupted jobs report an error and retain the editable source

Scope: jobs:read.

Parameters

NameInRequiredTypeRules
jobIdpathyesstring

Example request

curl -X GET "https://app.foxcue.com/api/v1/compositions/render-jobs/example" \
  -H "Authorization: Bearer <workspace API key>"

Response

StatusMeaning
200Success
400Invalid request
401Invalid, expired or revoked key
403Missing scope
404Resource not found in workspace
409Revision or idempotency conflict
429Rate or active-job limit exceeded

Scripts and script versions and jobs and more

Previous Page

Library and YouTube publishing and video claims

Next Page

On this page

RecordingsGET /recordingsParametersExample requestResponsePOST /recordingsExample requestResponseGET /recordings/{id}ParametersExample requestResponsePOST /recordings/{id}/sources/uploadParametersExample requestResponseMedia downloadGET /mediaParametersExample requestResponseEditing runsGET /editing/stylesParametersExample requestResponsePOST /editing/styles/{ref}/copiesParametersExample requestResponseGET /editing/runsParametersExample requestResponsePOST /editing/runsExample requestResponseGET /editing/runs/{id}ParametersExample requestResponsePOST /editing/runs/{id}/cancelParametersExample requestResponsePOST /editing/runs/{id}/retryParametersExample requestResponsePOST /editing/runs/{id}/rebuildParametersExample requestResponseDirector mediaPOST /director/from-recordingExample requestResponseGET /director/mediaParametersExample requestResponsePOST /director/mediaExample requestResponseGET /director/blocksParametersExample requestResponseCompositionsGET /compositions/{id}ParametersExample requestResponsePOST /compositions/{id}/opsParametersExample requestResponsePOST /compositions/{id}/renderParametersExample requestResponseGET /compositions/render-jobs/{jobId}ParametersExample requestResponseRelated articles