FoxCueDocs
Open FoxCue
API reference

FoxCue API: Library and YouTube publishing and Video claims

Request examples, parameters, scopes and response statuses for FoxCue API library and youtube publishing and video claims.

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.

Video claims

POST /video-claims/preview

Preview a one-use video claim for the connected workspace without consuming the code

Scope: outputs:read.

Example request

{
  "code": "example"
}

Required fields: code.

curl -X POST "https://app.foxcue.com/api/v1/video-claims/preview" \
  -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 /video-claims

Confirm and queue a copy of the existing editable video and finished output into this workspace; no generation, provider charges or subscription

Scope: media:write.

Parameters

NameInRequiredTypeRules
Idempotency-KeyheaderyesstringminLength 8; maxLength 128

Example request

{
  "code": "example",
  "confirm": true
}

Required fields: code, confirm.

curl -X POST "https://app.foxcue.com/api/v1/video-claims" \
  -H "Authorization: Bearer <workspace API key>" \
  -H "Idempotency-Key: example-key-001" \
  -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 /video-claims/{id}

Read this workspace video claim progress and copied video links

Scope: outputs:read.

Parameters

NameInRequiredTypeRules
idpathyesstring

Example request

curl -X GET "https://app.foxcue.com/api/v1/video-claims/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

Library

GET /library/templates

Search listed Library templates (q, category); mine=true lists every template this workspace submitted with its checks

Scope: library:read.

Parameters

NameInRequiredTypeRules
qquerynostringmaxLength 120
categoryquerynostringone of launch, product-explainer, dashboard, kinetic-type, captions, presenter, social-hook, transition, other
minequerynostringone of true, false
limitquerynointegerminimum 1; maximum 100
offsetquerynointegerminimum 0; maximum 100000

Example request

curl -X GET "https://app.foxcue.com/api/v1/library/templates?q=example&category=example&mine=example&limit=example&offset=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

GET /library/templates/{id}

Read a listed template, or one this workspace submitted with its checks and revisions

Scope: library:read.

Parameters

NameInRequiredTypeRules
idpathyesstring

Example request

curl -X GET "https://app.foxcue.com/api/v1/library/templates/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 /library/submissions

Submit a Style folder (file map), its credits and review material (breakdown, side-by-side frames). Runs the automatic checks; a passing template waits for FoxCue review. entry_id adds a revision to your own submission

Scope: library:write.

Example request

{
  "entry_id": "example",
  "slug": "example",
  "name": "example",
  "summary": "example",
  "category": "launch",
  "files": {},
  "credits": {
    "source_url": "example",
    "creator": "example",
    "creator_handle": "example",
    "note": "example"
  },
  "review": {
    "breakdown": "example",
    "comparison": [
      {
        "at_s": 0,
        "reference": "example",
        "foxcue": "example",
        "note": "example"
      }
    ],
    "verdict": "example"
  },
  "idea_id": "example",
  "change_summary": "example"
}

Required fields: name, files.

curl -X POST "https://app.foxcue.com/api/v1/library/submissions" \
  -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
entryJSON
revisionJSON
replayedboolean
{
  "entry": "example",
  "revision": "example",
  "replayed": false
}
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 /library/submissions/{id}

Read a submission: status (draft, checked, listed, parked), check issues and warnings, park reason, revisions

Scope: library:read.

Parameters

NameInRequiredTypeRules
idpathyesstring

Example request

curl -X GET "https://app.foxcue.com/api/v1/library/submissions/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

GET /library/ideas

List reference ideas this workspace logged

Scope: library:read.

Parameters

NameInRequiredTypeRules
qquerynostringmaxLength 120
categoryquerynostringone of launch, product-explainer, dashboard, kinetic-type, captions, presenter, social-hook, transition, other
minequerynostringone of true, false
limitquerynointegerminimum 1; maximum 100
offsetquerynointegerminimum 0; maximum 100000

Example request

curl -X GET "https://app.foxcue.com/api/v1/library/ideas?q=example&category=example&mine=example&limit=example&offset=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 /library/ideas

Log a reference idea (source URL, creator, why, breakdown) before building; the same source URL returns the existing idea

Scope: library:write.

Example request

{
  "source_url": "example",
  "creator": "example",
  "title": "example",
  "why": "example",
  "kind": "launch",
  "breakdown": {}
}

Required fields: source_url, title.

curl -X POST "https://app.foxcue.com/api/v1/library/ideas" \
  -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
ideaJSON
replayedboolean
{
  "idea": "example",
  "replayed": false
}
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

PATCH /library/ideas/{id}

Mark an idea building or dismissed

Scope: library:write.

Parameters

NameInRequiredTypeRules
idpathyesstring

Example request

{
  "status": "new"
}

Required fields: status.

curl -X PATCH "https://app.foxcue.com/api/v1/library/ideas/example" \
  -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

YouTube publishing

GET /publishing/drafts/{id}/metadata-context

Read original keyword targets, angle and script/Brand context provenance

Scope: publishing:read.

Parameters

NameInRequiredTypeRules
idpathyesstring

Example request

curl -X GET "https://app.foxcue.com/api/v1/publishing/drafts/example/metadata-context" \
  -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 /publishing/drafts/{id}/metadata-generations

Generate editable title, description, tags and thumbnail headline; also requires publishing:read and generation:write, never publishes

Scope: publishing:write.

Parameters

NameInRequiredTypeRules
idpathyesstring

Example request

{
  "expected_revision": 1,
  "expected_context_hash": "example",
  "idempotency_key": "example-"
}

Required fields: expected_revision, expected_context_hash, idempotency_key.

curl -X POST "https://app.foxcue.com/api/v1/publishing/drafts/example/metadata-generations" \
  -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 /publishing/drafts/{id}/metadata-generations/{generationId}

Read a metadata generation receipt without making another model request

Scope: publishing:read.

Parameters

NameInRequiredTypeRules
idpathyesstring
generationIdpathyesstring

Example request

curl -X GET "https://app.foxcue.com/api/v1/publishing/drafts/example/metadata-generations/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 /publishing/drafts/{id}/thumbnails

Generate one OpenAI thumbnail using Brand and video context; also requires publishing:read, generation:write and media:write, never publishes

Scope: publishing:write.

Parameters

NameInRequiredTypeRules
idpathyesstring

Example request

{
  "expected_revision": 1,
  "idempotency_key": "example-",
  "title": "example",
  "description": "example",
  "headline": "example",
  "direction": "example",
  "style": "bold_curiosity"
}

Required fields: expected_revision, idempotency_key, title.

curl -X POST "https://app.foxcue.com/api/v1/publishing/drafts/example/thumbnails" \
  -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 /publishing/drafts/{id}/thumbnails

Read saved thumbnail candidates for a scoped publishing draft

Scope: publishing:read.

Parameters

NameInRequiredTypeRules
idpathyesstring

Example request

curl -X GET "https://app.foxcue.com/api/v1/publishing/drafts/example/thumbnails" \
  -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

GET /publishing/drafts/{id}/thumbnails/{generationId}

Read a thumbnail generation receipt; never makes another image request

Scope: publishing:read.

Parameters

NameInRequiredTypeRules
idpathyesstring
generationIdpathyesstring

Example request

curl -X GET "https://app.foxcue.com/api/v1/publishing/drafts/example/thumbnails/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

GET /publishing/capabilities

Read Brand channel publishing capabilities without external writes

Scope: publishing:read.

Parameters

NameInRequiredTypeRules
project_idquerynostringminLength 1; maxLength 128; pattern ^[a-zA-Z0-9_-]+$
artifact_idquerynostringminLength 1; maxLength 128; pattern ^[a-zA-Z0-9_-]+$

Example request

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

Response

The body is a JSON object with these fields.

FieldType
thumbnail_generatorJSON
project_idnull
needs_brandboolean
enabledJSON
can_submitJSON
outputnull
connectionsarray
{
  "thumbnail_generator": "example",
  "project_id": null,
  "needs_brand": false,
  "enabled": "example",
  "can_submit": "example",
  "output": null,
  "connections": []
}
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 /publishing/drafts

Prepare a same-brand completed output for explicit later publication

Scope: publishing:write.

Example request

{
  "project_id": "example",
  "artifact_id": "example",
  "video_id": "example",
  "connection_id": "example"
}

Required fields: project_id, artifact_id, connection_id.

curl -X POST "https://app.foxcue.com/api/v1/publishing/drafts" \
  -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

PATCH /publishing/drafts/{id}

Edit a publishing draft using its current revision; never publishes

Scope: publishing:write.

Parameters

NameInRequiredTypeRules
idpathyesstring

Example request

{
  "expected_revision": 1,
  "metadata": {
    "title": "example",
    "description": "example",
    "tags": [
      "example"
    ],
    "category_id": "example",
    "made_for_kids": true,
    "contains_synthetic_media": true,
    "visibility": "private",
    "default_language": "example",
    "thumbnail_artifact_id": "example",
    "thumbnail_media_id": "example"
  }
}

Required fields: expected_revision, metadata.

curl -X PATCH "https://app.foxcue.com/api/v1/publishing/drafts/example" \
  -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 /publishing/drafts/{id}/submit

Explicitly approve and queue this exact reviewed draft for external YouTube publication

Scope: publishing:publish.

Parameters

NameInRequiredTypeRules
idpathyesstring

Example request

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

Required fields: expected_revision, idempotency_key.

curl -X POST "https://app.foxcue.com/api/v1/publishing/drafts/example/submit" \
  -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 /publishing/deliveries

List scoped durable publishing deliveries

Scope: publishing:read.

Parameters

NameInRequiredTypeRules
project_idquerynostringminLength 1; maxLength 128; pattern ^[a-zA-Z0-9_-]+$
composition_idquerynostringminLength 1; maxLength 128; pattern ^[a-zA-Z0-9_-]+$
connection_idquerynostringminLength 1; maxLength 128; pattern ^[a-zA-Z0-9_-]+$
artifact_idquerynostringminLength 1; maxLength 128; pattern ^[a-zA-Z0-9_-]+$
statequerynostringmaxLength 30
limitquerynointegerminimum 1; maximum 100
offsetquerynointegerminimum 0; maximum 100000

Example request

curl -X GET "https://app.foxcue.com/api/v1/publishing/deliveries?project_id=example&composition_id=example&connection_id=example&artifact_id=example&state=example&limit=example" \
  -H "Authorization: Bearer <workspace API key>"

Response

The body is a JSON object with these fields.

FieldType
itemsarray
has_moreboolean
limitnumber
offsetnumber
{
  "items": [],
  "has_more": false,
  "limit": 0,
  "offset": 0
}
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

GET /publishing/deliveries/{id}

Read safe progress, confirmed URL and events; never credentials

Scope: publishing:read.

Parameters

NameInRequiredTypeRules
idpathyesstring

Example request

curl -X GET "https://app.foxcue.com/api/v1/publishing/deliveries/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 /publishing/deliveries/{id}/cancel

Cancel delivery and verify any native schedule is cleared; never deletes a remote video

Scope: publishing:publish.

Parameters

NameInRequiredTypeRules
idpathyesstring

Example request

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

Required fields: expected_revision, idempotency_key.

curl -X POST "https://app.foxcue.com/api/v1/publishing/deliveries/example/cancel" \
  -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

POST /publishing/deliveries/{id}/retry

Explicitly repair or reapprove a delivery while preserving provider identity

Scope: publishing:publish.

Parameters

NameInRequiredTypeRules
idpathyesstring

Example request

{
  "expected_revision": 1,
  "idempotency_key": "example-",
  "action": "resume",
  "release_at": "example",
  "timezone": "example",
  "expected_connection_generation": 1
}

Required fields: expected_revision, idempotency_key, action.

curl -X POST "https://app.foxcue.com/api/v1/publishing/deliveries/example/retry" \
  -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

Recordings and media download and director media and more

Previous Page

Workflows

Next Page

On this page

Video claimsPOST /video-claims/previewExample requestResponsePOST /video-claimsParametersExample requestResponseGET /video-claims/{id}ParametersExample requestResponseLibraryGET /library/templatesParametersExample requestResponseGET /library/templates/{id}ParametersExample requestResponsePOST /library/submissionsExample requestResponseGET /library/submissions/{id}ParametersExample requestResponseGET /library/ideasParametersExample requestResponsePOST /library/ideasExample requestResponsePATCH /library/ideas/{id}ParametersExample requestResponseYouTube publishingGET /publishing/drafts/{id}/metadata-contextParametersExample requestResponsePOST /publishing/drafts/{id}/metadata-generationsParametersExample requestResponseGET /publishing/drafts/{id}/metadata-generations/{generationId}ParametersExample requestResponsePOST /publishing/drafts/{id}/thumbnailsParametersExample requestResponseGET /publishing/drafts/{id}/thumbnailsParametersExample requestResponseGET /publishing/drafts/{id}/thumbnails/{generationId}ParametersExample requestResponseGET /publishing/capabilitiesParametersExample requestResponsePOST /publishing/draftsExample requestResponsePATCH /publishing/drafts/{id}ParametersExample requestResponsePOST /publishing/drafts/{id}/submitParametersExample requestResponseGET /publishing/deliveriesParametersExample requestResponseGET /publishing/deliveries/{id}ParametersExample requestResponsePOST /publishing/deliveries/{id}/cancelParametersExample requestResponsePOST /publishing/deliveries/{id}/retryParametersExample requestResponseRelated articles