latestOpenAPI 3.0.02026-08-08270135.7 KB

c1404d1545ba

scenes
scene-content

Patch scene content

Patch scene content by merging supplied fields into the existing scene instead of replacing it.

Unlike the PUT endpoint which replaces all content, PATCH performs a server-side merge:
- **Elements**: Merged by element ID using version-based reconciliation. Higher version wins; equal versions are resolved by versionNonce tie-breaking. Elements not included in the request are preserved. Send elements with `isDeleted: true` to soft-delete them.
- **App State**: Shallow merge of provided fields over existing state.
- **Files**: New files are added; existing files are preserved unless replaced by a file with the same ID.

<Callout type="info">
PATCH accepts a partial scene-content object. You may provide any subset of `elements`, `appState`, and `files`, but at least one of them must be present. This endpoint does not perform an authoritative replacement and does not force connected editors to reload. It writes a merged scene using the current stored content as the base. If the scene is modified concurrently, the merge result may temporarily diverge until the next editor save/reconciliation cycle. If you want to replace the entire scene with a new authoritative version, use `PUT /scenes/:sceneId/content` instead.
</Callout>

**Use cases:**
- Adding or updating specific elements without affecting others
- Updating background color without touching elements
- Programmatically adding images/files to an existing scene
- Building integrations that modify scenes without full content replacement
patch/api/v1/scenes/{sceneId}/content

Path parameters

sceneIdstring required

Request body

{"stackTrail":"paths:/api/v1/scenes/{sceneId}/content:patch:requestBody:content:application/json:schema:properties:elements","oasType":"schema","type":"unknown"}
filesobject
filesFailedToEmbedstring[]

Ignored on write requests. Present so GET responses can be reused as PUT/PATCH inputs.

Response

This response returns the merged content of the scene after applying the patch.

type'excalidraw' required
versionnumber required
sourcestring required
sceneVersionstring required
filesobject required