Versioning and compatibility
How Slicer versions its API — the version in the path, additive-only changes within v1, the specification number and rules for robust clients.
On this page
We want code written today to keep working a year from now. That's why the API has two levels of versions and strict rules about what may change within one version.
Version in the path
The major version is in the URL: https://api.slicer.media/v1. Within /v1, changes are additive only:
- new endpoints;
- new optional request fields and new response fields;
- new values at the end of enumerations (for example, a new publication status or a new font in the catalog);
- new webhook events and new error codes.
Removing or renaming a field, changing its meaning or type, making an optional field required — these are breaking
changes. They can only happen in /v2, and after it ships /v1 keeps working for at least 12 months.
Specification number
The API specification — GET /v1/openapi.json (opens in a new tab) (OpenAPI 3.1) — has its own
semver number in info.version. It is currently 1.10.0.
| Part | When it grows |
|---|---|
minor (1.1.0) | an endpoint, field, event or enumeration value was added |
patch (1.0.1) | a description or behavior was fixed without changing the contract |
major (2.0.0) | together with the new /v2 path |
The MCP server uses the same number — its tools are built on the same contracts. Every API and MCP change is published in the changelog with the "API change" label: what changed in the specification and whether clients need to do anything.
Version history
All versions below are within /v1 and only add capabilities: a client written for 1.0.0 keeps working unchanged.
| Version | Date | What was added |
|---|---|---|
1.10.0 | 2026-10-28 | A montage produces one version, checked by the director: versionChoice is null after a montage and the project.version_ready event doesn't come. POST /v1/projects/{id}/versions/{versionId}/choose and MCP choose_version also make any version from the history with a file (hasFile) current — for example, the video from before a rebuild (Video versions) |
1.9.0 | 2026-10-27 | The Sound first transition: the jcut kind in the transitions of the tune_block and set_all_transitions operations, lasting from 0.15 to 1 s (Transitions) |
1.8.0 | 2026-10-19 | Captions: the pop, box and word designs and the pop template; in subtitles of the style (PATCH /v1/projects/{id}/style, MCP set_style) and of montage settings — the fields highlight (the spoken-word highlight), animation (the phrase entrance), words (words on screen), letterCase and speakerColors; subtitleOptions in the GET /v1/styles catalog. A partial subtitles change keeps the other fields; a new design without highlight, animation and words resets them to auto. position: "auto" places each phrase where the frame has the most free space (Style) |
1.7.0 | 2026-10-19 | Edits cover everything the timeline does: the cutting operations split_block, trim_block, duplicate_block, freeze_frame, set_hold, replace_source; free processing set_process and camera moves apply_keyframe_preset; music set_music, remove_music, fit_music, fit_to_beats; the voice track add_voice, move_voice, trim_voice, set_voice_volume, remove_voice; your own photos and videos over the video add_insert, update_insert, remove_insert; update_plaque, update_card, update_zoom, set_element_position, set_phrase_text, reset_phrase_text; the background field in tune_block, sounds and markers in move_element. Skip reasons block_or_source_not_found, audio_not_found, no_music_or_beats, recording_not_found, media_or_place_not_found, word_not_found. Captions from speech: POST /v1/projects/{id}/transcribe (at cost; without confirmCost — a Quote) and GET /v1/projects/{id}/transcribe — recognition jobs, the transcribe kind in POST /v1/estimate, the MCP tools transcribe_speech and get_transcribe_jobs. In MCP, create_project creates a project without the AI director by default (mode: "manual"). Your own director: POST /v1/projects/{id}/director/brief, GET /v1/projects/{id}/sources/{index}/frames, POST /v1/projects/{id}/director/plan — free, the MCP tools get_director_brief, get_frames, submit_director_plan and the direct_reel prompt |
1.6.0 | 2026-10-18 | Picture in picture: the set_pip operation — an insert as a window over the video or back to full frame (position, size, rotation, opacity, shape, corners, border, sound), the pip field of inserts in the edit document |
1.5.0 | 2026-10-18 | Frame and motion: the set_framing operation (including track — the frame follows the face), set_keyframe and remove_keyframe (rotation, opacity, easing), set_mask (position, rotation, inversion, animation), set_chromakey — chroma key, set_speed_curve — a footage speed curve, set_smooth — smooth slow motion, set_volume_keys — volume by points. Skip reasons block_not_footage, keyframe_not_found, block_not_found_or_no_face_data |
1.4.0 | 2026-10-17 | Colour: POST /v1/projects/{id}/auto-color and the MCP tool auto_color, adjust and lut in tune_block and set_all_color. Author sounds: the add_sound, update_sound, remove_sound operations |
1.3.0 | 2026-10-17 | Markers: the add_marker, update_marker, remove_marker operations and elements.markers in the video text. Fragment sound fade-in and fade-out (fadeIn, fadeOut in tune_block). The apply_look operation — one fragment's look on others, slip_block — slip the frames of a b-roll fragment, set_cover — a cover with a title. 12 new transition kinds |
1.2.0 | 2026-10-17 | Titles — free text layers: the add_title, update_title, remove_title operations and elements.titles. The add_source operation — put a project source into the video as a new fragment |
1.1.0 | 2026-10-17 | Projects without the AI director: mode: "manual" and format in POST /v1/projects, the mode field and the draft status of a project, the status=draft filter. Elements placed by video time (start, duration) where there is no speech, and the anchor placement in the video text. A single operation catalog: cut_silences, move_element, set_all_color, animations in tune_block, zoom scale and motion in add_zoom. The AI assistant and translation are priced at cost: estimate and atCost in Quote, costTokens in the response |
1.0.0 | 2026-10-16 | The first version: uploads, montage with price confirmation, three versions of a video, edit operations, AI assistant, translation, style, export and publishing, webhooks |
Details of each version are in the changelog.
Writing a robust client
- Ignore unknown fields in responses and webhooks — new fields appear without notice.
- Be ready for new enumeration values. If you get an unknown
statusor event type, treat it as "other" instead of crashing. An example is thedraftstatus added in1.1.0. - Don't rely on field order in JSON or on the exact
messagetext — only oncode. - Send only the fields you need. The server drops unknown fields in the request body; a typo in a field name won't cause an error but won't work either — check the reference.
- The edit document (
GET /v1/projects/{id}/document) is the internal model of the video; within v1 fields are only added to it as well. For edits, operations are more reliable: they don't depend on how the document is structured.
Generating a client
You can feed the specification to a client generator — for example, openapi-typescript for TypeScript or
openapi-python-client for Python:
npx openapi-typescript https://api.slicer.media/v1/openapi.json -o slicer-api.d.tsThe specification is available without a token. The reference in these docs is built from it too, so the docs and the server don't drift apart.