Apply one operation to a project's composition
Required permission: projects:write
API key auth. Prefix cf_live_ for production orgs, cf_test_ for sandbox.
In: header
Path Parameters
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
One scoped composition operation. Discriminated by type — clip.add / clip.remove / clip.update patch clips across any family; the rest cover markers, reframe, effects, captions, format, tracks, and the server-authoritative ripple recomputes. Validated strictly server-side against the runtime CompositionOp vocabulary.
Add a clip to the timeline. The clip self-routes to a track by FAMILY (clip.kind, else derived from source.kind, else the target track) — a media clip MUST carry kind (video|audio|image) or a trackId, else it is rejected as ambiguous. trackId targets an existing SAME-family track; newTrack:true (with optional pinned newTrackId) creates a fresh track of that family.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/projects/string/composition/ops" \ -H "Content-Type: application/json" \ -d '{ "type": "clip.add", "clip": { "id": "string", "startTime": 0, "duration": 1, "source": { "kind": "media", "mediaId": "string" } } }'{ "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null } }}{ "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null } }}{ "x402Version": 2, "accepts": [ {} ], "error": "string"}{ "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null } }}{ "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null } }}{ "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null } }}{ "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null } }}{ "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null } }}{ "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null } }}Apply a batch of operations to a project's composition (or dry-run validate) POST
Atomically applies an array of CompositionOps. All ops succeed or none do (transactional). Pass `if_match` for optimistic-concurrency control (409 stale_etag on mismatch). Pass `dry_run: true` to validate the batch — runs the same apply + projection accept/reject guards WITHOUT persisting, returning `{ valid, errors }` with `locator.op_index` on the first failing op. Both modes may carry `warnings[]` — non-fatal authoring advisories (e.g. a card whose html reads a CSS custom property no token defines). Warnings never block.
Delete a composition DELETE
Delete a composition and its version history. REFUSES the project's ACTIVE composition (409 composition_active) — make another one active first, or delete the project.