---
title: "Combine Segment Endpoint"
method: POST
path: "/segments/{segment_id}/combine"
tags: ["segments"]
---

# Combine Segment Endpoint

`POST /segments/{segment_id}/combine`

## Request

- Base URL: `https://api.framesail.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.framesail.com/segments/{segment_id}/combine`
- Auth: HTTP bearer

Combine this segment with an adjacent segment.

## Path parameters

- `segment_id` string, required

## Request body

- CombineSegmentRequest: Combine this segment with an adjacent segment.
  - `dry_run` boolean: Preview the operation's consequences (assets kept / staled / recreated / deleted, jobs cancelled, rendered assets lost) without applying it.
  - `with_segment_id` string, required: ID of the adjacent segment to merge with.
  - `keep` 'this' | 'other': Which segment's creative data survives. 'this' = the segment in the URL, 'other' = with_segment_id.

## Response `200`

Successful Response

- SegmentOperationResponse: Response for all segment operations. A dry_run returns `preview` with an empty `segments` list; a real run returns the mutated segments.
  - `segments` object[], required
  - `warning` string, nullable
  - `preview` TransitionPreview: dry_run disclosure for a destructive segment operation — one payload shape for every op and every surface (storyboard UI, editor, MCP).
    - `kept` integer, required
    - `stale` integer, required
    - `recreated` integer, required
    - `deleted` integer, required
    - `jobs_cancelled` integer, required
    - `rendered_assets_lost` string[]: What each already-rendered asset this operation destroys is (image, clip, real photo, ...), named by generation.roles.asset_label.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/framesail/apis/framesail-api.md) · [All operations](https://skmtc.dev/framesail/apis/framesail-api/llms.txt) · [OpenAPI document](https://skmtc.dev/framesail/apis/framesail-api/revisions/12602eae0820?raw)