--- title: "Apply Canvas Edit" method: POST path: "/canvases/{canvas_ref}/edit/apply" tags: ["canvas-actions"] --- # Apply Canvas Edit `POST /canvases/{canvas_ref}/edit/apply` ## Request - Base URL: `https://api.moda.app/v1` - URL: `https://api.moda.app/v1/canvases/{canvas_ref}/edit/apply` - Auth: HTTP bearer Atomically apply Edit operations — composition and uploaded-media clips, visual and audio tracks — through the shared runtime validator. ## Path parameters - `canvas_ref` string, required ## Headers - `Moda-Version` '2026-04-12' | '2026-05-01' ## Request body - EditApplyRequest - `operations` union[], required - union - EditInsertClipRequest: Insert one clip. Visual sources (``composition``/``media``) go on a visual track and optionally ripple later clips right; audio sources (``media-stream``/ ``composition-audio``) go on an audio track created with ``create_track``. - `op` 'insert_clip', required - `track_id` string, required - `clip` EditClipRequest, required: Clip envelope. Audio-clip fields (``gain_db``/``pan``/``channel_map``/ ``preserve_pitch``/``fade_in``/``fade_out``) and the ``audio`` policy are not valid on ``composition`` clips — ``apply`` refuses them with a typed ``unsupported_edit_capability`` error, and ``validate`` reports an ``unsupported_capability`` diagnostic. - `id` string, required - `source` union, required - EditCompositionSourceRequest: A canvas page (composition) as a visual clip source. - … - EditMediaSourceRequest: An uploaded video file as a visual clip source. ``asset_id`` is the file's public id (``file_...``, as returned by the uploads endpoints) or its bare UUID; the host authorizes every referenced asset per call (team access, a video mime type, and duration metadata are required) and refuses unauthorized or unknown assets with a typed ``invalid_media_reference`` error. - … - EditMediaStreamSourceRequest: One audio stream of an uploaded audio file as a standalone audio clip source, placed on an audio track (see ``EditCreateTrackRequest``). Only stream index 0 of an audio asset is supported today; the host authorizes the asset per call the same way as ``media`` sources. - … - EditCompositionAudioSourceRequest: A composition's audio as a standalone audio clip source, placed on an audio track (see ``EditCreateTrackRequest``). - … - `start` EditTimeValueRequest, required - `value` string, required: Exact integer numerator encoded as a bounded decimal string. - `timescale` integer, required - `duration` EditTimeValueRequest, required - `value` string, required: Exact integer numerator encoded as a bounded decimal string. - `timescale` integer, required - `source_start` EditTimeValueRequest - `value` string, required: Exact integer numerator encoded as a bounded decimal string. - `timescale` integer, required - `rate` EditPlaybackRateRequest - `numerator` integer, required - `denominator` integer, required - `end_behavior` 'hold' | 'loop' | 'transparent' | 'stop', nullable - `enabled` boolean, nullable - `name` string, nullable - `audio` EditAudioPolicyRequest - `mode` 'follow-source' | 'muted' | 'detached', required - `gain_db` number, nullable - `preserve_pitch` boolean, nullable - `preserve_pitch` boolean, nullable - `gain_db` number, nullable - `pan` number, nullable - `channel_map` 'stereo' | 'left' | 'right' | 'mono', nullable - `fade_in` EditFadeRequest - `duration` EditTimeValueRequest, required - … - `curve` 'linear' | 'equal-power' | 'ease-in' | 'ease-out', nullable - `fade_out` EditFadeRequest - `duration` EditTimeValueRequest, required - … - `curve` 'linear' | 'equal-power' | 'ease-in' | 'ease-out', nullable - `ripple` boolean, nullable: Visual operations only: shift later clips to make room (true, the default) or place at the exact time (false). Audio operations must omit it. - EditMoveClipRequest - `op` 'move_clip', required - `clip_id` string, required - `track_id` string, required - `start` EditTimeValueRequest, required - `value` string, required: Exact integer numerator encoded as a bounded decimal string. - `timescale` integer, required - `ripple` boolean, nullable: Visual clips only: shift later clips (true, the default when omitted) or keep every other placement fixed (false). Must be omitted for audio clips. - EditTrimClipRequest - `op` 'trim_clip', required - `clip_id` string, required - `edge` 'start' | 'end', required - `time` EditTimeValueRequest, required - `value` string, required: Exact integer numerator encoded as a bounded decimal string. - `timescale` integer, required - `ripple` boolean, nullable: Visual clips only: shift later clips (true, the default when omitted) or keep every other placement fixed (false). Must be omitted for audio clips. - EditRemoveClipRequest - `op` 'remove_clip', required - `clip_id` string, required - `ripple` boolean, nullable: Visual clips only: shift later clips (true, the default when omitted) or keep every other placement fixed (false). Must be omitted for audio clips. - EditReorderClipRequest - `op` 'reorder_clip', required - `track_id` string, required - `clip_id` string, required - `before_clip_id` string, nullable - EditSplitClipRequest: Split one clip at an Edit-time position into two placements; the tail keeps playing from the split point and takes ``new_clip_id``. - `op` 'split_clip', required - `clip_id` string, required - `at` EditTimeValueRequest, required - `value` string, required: Exact integer numerator encoded as a bounded decimal string. - `timescale` integer, required - `new_clip_id` string, required - EditSetClipAudioRequest: Adjust source audio on an existing placement: mute/unmute and/or gain. At least one of ``muted``/``gain_db`` is required. - `op` 'set_clip_audio', required - `clip_id` string, required - `muted` boolean, nullable - `gain_db` number, nullable - EditCreateTrackRequest: Append an audio or visual track. Later visual tracks composite above earlier ones. - `op` 'create_track', required - `track` union, required - EditAudioTrackRequest - `id` string, required - `kind` 'audio', required - `name` string, nullable - `role` 'dialogue' | 'music' | 'sfx' | 'ambience', nullable - EditVisualTrackRequest - `id` string, required - `kind` 'visual', required - `name` string, nullable - EditRemoveTrackRequest: Remove a track and its clips. The Main Edit must retain one visual track. - `op` 'remove_track', required - `track_id` string, required - EditSetTransitionRequest: Create a transition at an adjacent cut using source handles, or bind/update an existing overlap. Visual transitions never add audio fades automatically. - `op` 'set_transition', required - `transition` EditTransitionDefinitionRequest, required - `id` string, required - `type` 'dissolve' | 'dipToBlack' | 'push' | 'slideOver', required - `from_clip_id` string, required - `to_clip_id` string, required - `easing` 'linear' | 'easeIn' | 'easeOut' | 'easeInOut' | 'easeOutCubic' | 'easeInCubic' | 'easeInOutCubic' | 'easeOutQuint' | 'easeInOutQuint' | 'easeOutBounce', nullable - `direction` 'left' | 'right' | 'up' | 'down', nullable - `placement` union, required - EditTransitionAtCutRequest - `kind` 'at_cut', required - `in_offset` EditTimeValueRequest, required - … - `out_offset` EditTimeValueRequest, required - … - EditTransitionOverlapRequest - `kind` 'overlap', required - `in_offset` EditTimeValueRequest - … - EditRemoveTransitionRequest: Remove a supported transition and trim both clips back to its saved cut. - `op` 'remove_transition', required - `transition_id` string, required - `expected_revision` string, required: Revision token from an Edit read or validation response. - `idempotency_key` string, nullable ## Response `200` Successful Response - object ## Other responses - `401`: Authentication required. - `402`: Insufficient credits for a metered operation. - `403`: Permission denied for this scope. - `404`: Resource not found. - `409`: Conflict (idempotency / resource state). - `422`: Request validation failed. - `429`: Rate limit exceeded. - `500`: Internal error. ## Changes - **2026-11-03** `9ac6a3abc0f8`: 1 info - endpoint added [Operation history](https://skmtc.dev/moda/apis/moda-public-api/changes/canvases/:canvas_ref/edit/apply/post.md) --- [API](https://skmtc.dev/moda/apis/moda-public-api.md) - [All operations](https://skmtc.dev/moda/apis/moda-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/moda/apis/moda-public-api/revisions/9ac6a3abc0f8?raw)