components

Author (create) a component

Required permission: projects:write

post/v1/components

Request

  • Base URL: https://api.cueframe.ai
  • URL: https://api.cueframe.ai/v1/components
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://api.cueframe.ai/api/auth/mcp/authorize, token URL https://api.cueframe.ai/api/auth/mcp/token, scopes: projects:write)
    • API key in header PAYMENT-SIGNATURE

Request body

componentIdstring required

Caller-chosen stable component id. On create it names the new component. On PUT/PATCH it is optional and, when present, must equal the id in the path; a mismatch is a 400 naming both.

namestring required
descriptionstring required
category'text' | 'effects' | 'transitions' | 'layouts' | 'backgrounds' | 'ui-blocks' | 'scenes' required
propSchemaobject
origin'customer-owned' | 'server-native'
ejectedFromstring
tokensobject
examplesobject[]

Usage examples, as authored. A built-in primitive projects {name, mood?, params?, description?}; an authored component's examples are whatever it wrote, which is why the item is open. One shape for both directions: what you write here is what you read back.

durationInFramesnumber

Response

Component created.

namestring required
descriptionstring required
category'text' | 'effects' | 'transitions' | 'layouts' | 'backgrounds' | 'ui-blocks' | 'scenes' required
propSchemaobject required
origin'customer-owned' | 'server-native'
ejectedFromstring
tokensobject
examplesobject[]

Usage examples, as authored. A built-in primitive projects {name, mood?, params?, description?}; an authored component's examples are whatever it wrote, which is why the item is open. One shape for both directions: what you write here is what you read back.

durationInFramesnumber
idstring required

The entry's id: a primitiveId for a built-in, a componentId for an installed component.

source'default' | 'installed' required

'default' = built-in primitive (place by primitiveId); 'installed' = org-authored component (place by componentId).

kind'component' | 'transition' | 'scene' required

RENDER kind (component | transition | scene). NOT the ClipSource variant — see placement for how to author it on the timeline.

versionstring required

The ENTRY's version: a semver string ('0.0.0' until an authored component is versioned). Distinct from manifest.version, which is the runtime contract version (4 native, 2 retired TSX).

propDefaultsobject
textParamstring nullable

The param field that carries this primitive's primary text; null = no single text slot.

subtextParamstring nullable

The param field for secondary text (subtitle/byline); null = none.

intentstring

Selection signal: a verb naming what this primitive accomplishes (e.g. 'product-trailer'). Match it to the beat you are authoring.

useWhenstring

When to use this — AND when not to. The negative guidance is load-bearing; read it before picking.

pairsWithstring[]

Authoring guidance: ids of primitives that COMPOSE well with this one in the same edit.

avoidWithstring[]

Authoring guidance: ids of primitives that CONFLICT with this one — do not place together.

tagsstring[]

Free-text search keywords.

moodstring[]

Vibe/tone tags (e.g. 'cinematic', 'minimal'). Filter to match the edit's mood.

tier'recommended' | 'standard' | 'niche'

Quality/applicability RANKING (a preference, not a flag). Prefer 'recommended'; reach for 'niche' only when its specific use-case is exactly the beat.

useCasestring[]

The edit ROLE(s) this primitive fills — the dimension to filter by for a beat (e.g. 'intro', 'title-over-footage', 'grade').

fixedCopystring[]

On-screen strings this primitive BAKES — the read-side counterpart to propSchema. These literals render REGARDLESS of params (no param can change them); fork the source via get_component_source to edit them. Use this to see at author time what fixed copy (someone-else's marketing text, faux-code, faux-data) will appear before you render.

warningsstring[]

Non-blocking save-time advisories — the create/update SUCCEEDED. Currently: a fontFamily string literal referencing a NON-vendored font (a bare CSS generic like 'serif', or an unknown named family like 'Arial') whose LIVE-lane pixels vary by render host — re-author with a vendored family or 'Georgia'. Omitted when there is nothing to flag; only present on the create/update responses.

Changes

No recorded changes to this operation across all 1 revision of this API.