components

Patch an authored component

RFC 7396 merge patch: send only the fields you are changing. Every field you omit keeps the value it already had. Identical in effect to PUT, which merges the same way. Every placed clip renders the exact version it pins. Send projectId, compositionId and caller-observed concurrency to move that composition's placements to the new version in the same write; repinned reports them. Other placements keep rendering the previous version, and placementsPinnedToPrevious counts them across the org. For a single placement, update the library without projectId, then use apply_composition clip.update to install that exact immutable source pin on the chosen clip under observed dependency guards. Atomic all-use repin requires exact revision admission; unsupported guarded mode and no matching placements refuse the whole write.

patch/v1/components/{id}

Request

  • Base URL: https://api.cueframe.ai
  • URL: https://api.cueframe.ai/v1/components/{id}
  • 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

Path parameters

idstring required

Request body

componentIdstring

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
descriptionstring
category'text' | 'effects' | 'transitions' | 'layouts' | 'backgrounds' | 'ui-blocks' | 'scenes'
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
projectIdstring

A project whose explicitly named composition moves its placements atomically with the source write. Requires compositionId and concurrency.

compositionIdstring

The exact composition observed by the caller. Required with projectId and concurrency.

Example request

{
  "name": "Renamed title"
}

Response

Component updated.

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.

placementsPinnedToPreviousinteger required

Placements across the org that still pin the previous version and will keep rendering it. Name projectId (and compositionId) on the update to move a composition's placements with it.

Changes

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