Atomically apply an array of CompositionOps to a project composition. All ops succeed or none do (transactional). Call describe_composition_ops without type for the compact operation list, then with a type for its exact JSON Schema. For negotiated component execution, read get_composition with componentExecutionVersions=["3","4"] and includeDependencies="true", then send componentExecutionVersions:[3,4] and that exact expectedBrandIdentity. A changed brand refuses the command; never refresh the witness to conceal a conflict. Explicit builtinSources selectors attach only the approved exact source pins referenced by the final composition. The additive `concurrency` envelope requires an endpoint confirmed to enforce guardedCompositionV1; unsupported hosted endpoints refuse it with unsupported_concurrency. Obtain dependency expectations from the observed composition; never rebuild a stale basis from current state. Every committing call REQUIRES `if_match`, the composition ETag from a fresh get_composition, or the `concurrency` envelope; a call with neither is refused with 428 precondition_required. On 409 stale_etag, read get_composition again and reconsider the batch against what changed; never copy the error's currentEtag into a retry without that read. `dry_run: true` validates without persisting. For negotiated component execution, EVERY dry-run and commit must still carry the observed `composition_id`, `concurrency:{mode:"exact",expectedRevision:<observed project revision>}` (or supported guarded dependency expectations), `componentExecutionVersions` and exact `expectedBrandIdentity`; retain the observed `if_match` too. Only non-negotiated legacy dry-runs may omit revision preconditions. Ops land on the project's ACTIVE composition unless you pass `composition_id` (mutually exclusive with `session_id`), which targets a specific one — that is how you author a second composition minted with new_composition and run an A/B. Use this to seed a composition (add media clips) or make targeted edits (set a crop intent, reorder clips, set the format). CAPTIONS FOR EDITED TIMELINES: after saving all clip edits, call again with {type:"captions.fromComposition", trackId} to build captions from every audible clip on that track, honoring trims, exclusions and placement. Clips must have duration matching playable source duration divided by playbackRate; unsupported timing fails explicitly. Re-run it after later timeline edits; captions do not update automatically. {type:"captions.fromTranscript", mediaId, window?} instead replaces all captions from one media transcript, rebased to zero; it does not follow a montage. Style with {type:"setCaptionStyle", style}; or set explicit words with {type:"setCaptions", segments, style?} (e.g. translations or your own VO timings). Brand is NOT set here — it lives on the project (create_project / update_project with brandKitId — or PATCH /projects/:id over REST). CARDS: a {kind:"card", html, tokens} clip projects each `tokens` KEY `x` to the CSS custom property `--cf-x`, so the html must read it as `var(--cf-x)` — write `tokens:{"plate":"#0af"}` + `background:var(--cf-plate)`. Do NOT put dashes in the key: `"--plate"` becomes `--cf---plate` and your `var(--plate)` then resolves to NOTHING, which CSS silently degrades to a transparent background and black text. Responses carry `warnings[]` when a card reads a var nothing defines. SCENE SHOTS: for a 3D product shot — a tilted page screenshot, a lit laptop/phone showing a real screenshot, two-colour type, a colour-field backdrop, focus/grain/vignette and a camera move — use {type:"scene.add", clipId, newTrack|trackId, startTime, duration, scene, assets} and revise it with {type:"scene.update", clipId, scene?, assets?, startTime?, duration?}. You author a scene SPEC, never wrapper TSX; the server registers the component for you. There is NO built-in scene primitive in list_catalog — READ cueframe://scene-shot first for the JSON schema, the canonical V2 world-objects recipe with nested groups, slabs, pages, phones, laptops, world/screen text, admitted surfaces, camera motion, lighting, and the current resource limits.
View input schema
{
"type": "object",
"properties": {
"projectId": {
"type": "string",
"description": "projectId (path)."
},
"response": {
"description": "MCP response view. Default compact omits repeated source bodies. Full returns the complete backend receipt or requested sources. This does not change the saved composition.",
"$ref": "#/$defs/__schema0"
},
"body": {
"type": "object",
"properties": {
"ops": {
"type": "array",
"minItems": 1,
"items": {},
"description": "Call describe_composition_ops for the operation list, then with a type for its exact JSON Schema."
},
"componentExecutionVersions": {
"$ref": "#/$defs/__schema300"
},
"builtinSources": {
"$ref": "#/$defs/__schema304"
},
"expectedBrandIdentity": {
"$ref": "#/$defs/__schema306"
},
"concurrency": {
"$ref": "#/$defs/__schema307"
},
"if_match": {
"$ref": "#/$defs/__schema311"
},
"dry_run": {
"$ref": "#/$defs/__schema312"
},
"composition_id": {
"$ref": "#/$defs/__schema313"
},
"session_id": {
"$ref": "#/$defs/__schema314"
}
},
"required": [
"ops"
],
"additionalProperties": false,
"description": "POST /projects/:id/composition/apply body — a batch of CompositionOps."
},
"commandId": {
"description": "Retry identity. A call repeated with the same commandId returns the first result instead of acting twice.",
"$ref": "#/$defs/__schema315"
}
},
"required": [
"projectId",
"body"
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$defs": {
"__schema0": {
"type": "string",
"enum": [
"compact",
"full"
]
},
"__schema300": {
"anyOf": [
{
"type": "array",
"prefixItems": [
{
"$ref": "#/$defs/__schema301"
}
],
"items": false,
"minItems": 1,
"maxItems": 1
},
{
"type": "array",
"prefixItems": [
{
"$ref": "#/$defs/__schema302"
},
{
"$ref": "#/$defs/__schema303"
}
],
"items": false,
"minItems": 2,
"maxItems": 2
}
]
},
"__schema301": {
"type": "number",
"const": 3
},
"__schema302": {
"type": "number",
"const": 3
},
"__schema303": {
"type": "number",
"const": 4
},
"__schema304": {
"minItems": 1,
"maxItems": 512,
"type": "array",
"items": {
"$ref": "#/$defs/__schema305"
}
},
"__schema305": {
"type": "object",
"properties": {
"scope": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "builtin"
},
"collection": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"kind",
"collection"
],
"additionalProperties": false
},
"componentId": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"sourceVersionId": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"sourceVersion": {
"anyOf": [
{
"type": "number",
"const": 3
},
{
"type": "number",
"const": 4
}
]
}
},
"required": [
"scope",
"componentId",
"sourceVersionId",
"sourceVersion"
],
"additionalProperties": false
},
"__schema306": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"__schema307": {
"oneOf": [
{
"$ref": "#/$defs/__schema308"
},
{
"$ref": "#/$defs/__schema309"
}
],
"description": "Version 1 shared dependency admission. Guarded requests must name the observed immutable composition with composition_id or concurrency.compositionId; changed or missing dependencies refuse the entire batch."
},
"__schema308": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"const": "exact"
},
"expectedRevision": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"mode",
"expectedRevision"
],
"additionalProperties": false
},
"__schema309": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"const": "guarded"
},
"compositionId": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"observedRevision": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"basis": {
"maxItems": 2048,
"type": "array",
"items": {
"$ref": "#/$defs/__schema310"
}
}
},
"required": [
"mode",
"observedRevision",
"basis"
],
"additionalProperties": false
},
"__schema310": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"token": {
"type": "string",
"maxLength": 65536
}
},
"required": [
"key",
"token"
],
"additionalProperties": false
},
"__schema311": {
"type": "string",
"description": "OCC precondition: the strong etag (`\"<hex>\"`) the caller last saw. Required unless `concurrency` is sent or `dry_run` is true; a write with neither is refused with 428 precondition_required. On mismatch the batch is rejected (409 stale_etag) before any op applies."
},
"__schema312": {
"type": "boolean",
"description": "When true, validate the batch (apply + projection accept/reject guards) WITHOUT persisting. Returns `{ valid, errors }` instead of applying."
},
"__schema313": {
"type": "string",
"description": "Target a SPECIFIC composition instead of the project's active one. Omit it and the project's active composition is edited, which is the default and the common case. `preview_frame` and `create_render` already accept a compositionId; this closes the gap so a second composition minted with `new_composition` can actually be authored into — build variant A, mint B, edit B, preview both. Mutually exclusive with `session_id`, which targets the session's scratch."
},
"__schema314": {
"type": "string",
"description": "Optional compose-session id. When present, the ops target the session's SCRATCH composition (a derived sibling) instead of the project's active composition — the server never mutates active until commit."
},
"__schema315": {
"type": "string",
"minLength": 1,
"maxLength": 128
}
}
}