--- title: "Patch an authored component" method: PATCH path: "/v1/components/{id}" tags: ["components"] --- # Patch an authored component `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` 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. ## Path parameters - `id` string, required ## Request body - ComponentPatchRequest: PATCH /components/:id body, RFC 7396 merge: a field you omit is left exactly as it was. Org/user are server-resolved; never accepted from the body. - `componentId` string: 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. - `name` string - `description` string - `category` 'text' | 'effects' | 'transitions' | 'layouts' | 'backgrounds' | 'ui-blocks' | 'scenes' - `propSchema` object - `origin` 'customer-owned' | 'server-native' - `ejectedFrom` string - `tokens` object - `examples` object[]: 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. - `durationInFrames` number - `source` object - `version` 4, required - `componentId` string, required - `template` string, required - `manifest` object, required - `version` 4, required - `runtime` 'hyperframes', required - `hfContract` 1, required - `kind` 'scene', required - `sceneShot` object - `version` 2, required - `assets` object, required - `graphics` object, required - `api` 'canvas2d' | 'webgl' | 'webgl2' | 'webgpu', required - `required` true, required - `accelerationPreference` 'hardware-preferred' | 'software-allowed', required - `alphaPolicy` 'requires-transparency' | 'allows-opaque', required - `definition` object, required - `inputSchema` object, required - `defaults` object, required - `brandBindings` object[], required - `propPath` string, required - `cssVar` string, required - `fallback` string - `brandKitPath` string - `timing` object, required - `defaultDuration` object, required - `frames` integer, required - `fps` number, required - `minDurationSec` number - `maxDurationSec` number - `capabilities` union[], required - union - object - `kind` 'clip', required - object - `kind` 'cut-transition', required - `protocol` 'per-child', required - object - `kind` 'content-slots', required - `slots` object[], required - … - object - `kind` 'clip-wrapper', required - `ordering` 'any' | 'innermost', required - `acceptsWrappedTargets` boolean, required - object - `kind` 'global-wrapper', required - `scope` 'media-lanes', required - `ordering` 'any' | 'innermost', required - `acceptsWrappedTargets` boolean, required - `mediaBindings` object[] - `name` string, required - `propPath` string[], required - `kind` 'image' | 'video' | 'visual', required - `collection` 'scalar' | 'array', required - `cardinality` object, required - `min` integer, required - `max` integer - `mimeTypes` string[] - `mediaDemand` union - object - `mode` 'original', required - object - `mode` 'tier', required - `tier` union, required - … - object - `mode` 'auto', required - `maxProjectedWidthRatio` number, required - `maxProjectedHeightRatio` number, required - `minVisibleSourceWidthRatio` number, required - `minVisibleSourceHeightRatio` number, required - `preview` object - `params` object - `format` Format - `aspectRatio` '16:9' | '9:16' | '1:1' | '4:5', required - `fps` union - 24 - 25 - 30 - 60 - `resolution` 'hd' | 'fhd' | '4k' - `platform` string - `assets` object - `mediaBindings` object - `projectId` string: A project whose explicitly named composition moves its placements atomically with the source write. Requires compositionId and concurrency. - `compositionId` string: The exact composition observed by the caller. Required with projectId and concurrency. - `concurrency` union - object - `mode` 'exact', required - `expectedRevision` integer, required - object - `mode` 'guarded', required - `compositionId` string - `observedRevision` integer, required - `basis` object[], required - `key` string, required - `token` string, required ## Response `200` Component updated. - ComponentUpdateResponse: Updated component entry plus where its placements point. - `name` string, required - `description` string, required - `category` 'text' | 'effects' | 'transitions' | 'layouts' | 'backgrounds' | 'ui-blocks' | 'scenes', required - `propSchema` object, required - `origin` 'customer-owned' | 'server-native' - `ejectedFrom` string - `tokens` object - `examples` object[]: 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. - `durationInFrames` number - `manifest` union - ComponentManifestV4 - `version` 4, required - `runtime` 'hyperframes', required - `hfContract` 1, required - `kind` 'scene', required - `sceneShot` object - `version` 2, required - `assets` object, required - `graphics` object, required - `api` 'canvas2d' | 'webgl' | 'webgl2' | 'webgpu', required - `required` true, required - `accelerationPreference` 'hardware-preferred' | 'software-allowed', required - `alphaPolicy` 'requires-transparency' | 'allows-opaque', required - ComponentManifestV2 - `version` 2, required - `assets` object, required - `graphics` object, required - `api` 'canvas2d' | 'webgl' | 'webgl2' | 'webgpu', required - `required` true, required - `accelerationPreference` 'hardware-preferred' | 'software-allowed', required - `alphaPolicy` 'requires-transparency' | 'allows-opaque', required - `sceneShot` object - `version` 2, required - `visualMedia` object - `version` 1, required - `id` string, 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. - `version` string, 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). - `propDefaults` object - `textParam` string, nullable: The param field that carries this primitive's primary text; null = no single text slot. - `subtextParam` string, nullable: The param field for secondary text (subtitle/byline); null = none. - `format` Format - `aspectRatio` '16:9' | '9:16' | '1:1' | '4:5', required - `fps` union - 24 - 25 - 30 - 60 - `resolution` 'hd' | 'fhd' | '4k' - `platform` string - `intent` string: Selection signal: a verb naming what this primitive accomplishes (e.g. 'product-trailer'). Match it to the beat you are authoring. - `useWhen` string: When to use this — AND when not to. The negative guidance is load-bearing; read it before picking. - `pairsWith` string[]: Authoring guidance: ids of primitives that COMPOSE well with this one in the same edit. - `avoidWith` string[]: Authoring guidance: ids of primitives that CONFLICT with this one — do not place together. - `tags` string[]: Free-text search keywords. - `mood` string[]: 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. - `useCase` string[]: The edit ROLE(s) this primitive fills — the dimension to filter by for a beat (e.g. 'intro', 'title-over-footage', 'grade'). - `fixedCopy` string[]: 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. - `brandBindings` object[]: Params that can follow the project brand kit. Each {param, brandToken} says: set `param` to `brandToken` (a `$brand:` ref, e.g. '$brand:colors.accent') to track the brand instead of a literal. See the list response's `brandTokens` for the full ref vocabulary. Omitted when nothing is brand-bound. - `param` string, required - `brandToken` string, required - `placement` ComponentPlacement, required - `clipSourceKind` 'overlay' | 'effect' | 'component', required: The ClipSource `kind` to author this entry as: 'overlay' (built-in text/ui/scene/background/layout), 'effect' (built-in effect/transition), or 'component' (an org-INSTALLED custom component). - `refField` 'primitiveId' | 'componentId', required: Which id field keys the ClipSource: 'primitiveId' for built-ins (source:'default'), 'componentId' for installed components (source:'installed'). Using the wrong field will NOT resolve at render. - `warnings` string[]: 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. - `repinned` object: Present when the update named `projectId`: the composition whose placements moved to the new version. - `compositionId` string, required - `pins` integer, required: Placements in that composition moved from the previous version to this one, nested scene surfaces included. - `etag` string, nullable, required: The composition's ETag after the move; null when no pin moved. - `placementsPinnedToPrevious` integer, 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. ## Other responses - `400`: Bad request — validation_error / invalid_cursor / invalid_query. - `401`: Missing or invalid Authorization header. - `402`: Payment required. Returned when the caller presents no API key on a priced operation: the body AND the `Payment-Required` header carry the x402 v2 challenge (accepted scheme, network, USDC asset, amount, payTo). Sign the EIP-3009 authorization and retry with a `PAYMENT-SIGNATURE` header. A KEYED caller sees this status instead when their plan lacks or has exhausted the feature (`billing_required`). - `403`: Forbidden — permission insufficient. - `404`: Resource not found. - `422`: Unprocessable — invalid_composition / media_in_use / session_in_use / render_not_cancellable. - `429`: Rate limited. Retry-After header present. - `500`: Internal error. --- [API](https://skmtc.dev/cueframe/apis/cueframe-api.md) · [All operations](https://skmtc.dev/cueframe/apis/cueframe-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cueframe/apis/cueframe-api/revisions/8f9bfe362b4a?raw)