---
title: "Patch scene content"
method: PATCH
path: "/api/v1/scenes/{sceneId}/content"
tags: ["scenes", "scene-content"]
---

# Patch scene content

`PATCH /api/v1/scenes/{sceneId}/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

## Path parameters

- `sceneId` string, required

## Request body

- object
  - `elements` unknown
  - `appState` object
    - `viewBackgroundColor` string
    - `lockedMultiSelections` object
  - `files` object
  - `filesFailedToEmbed` string[] — Ignored on write requests. Present so GET responses can be reused as PUT/PATCH inputs.

## Response `200`

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

- object — This response returns the merged content of the scene after applying the patch.
  - `type` 'excalidraw', required
  - `version` number, required
  - `source` string, required
  - `appState` object, required
    - `viewBackgroundColor` string, required
    - `lockedMultiSelections` object
  - `elements` unknown[], required
    - unknown
  - `sceneVersion` string, required
  - `files` object, required

## Other responses

- `400` — This response indicates that the request was malformed or contained invalid parameters.
- `401` — This response indicates that the client must authenticate to access the requested resource.
- `403` — This response indicates that the client does not have permission to access the requested resource.
- `404` — This response indicates that the requested resource could not be found.

---

[API](https://skmtc.net/excalidraw/apis/excalidraw-api.md) · [All operations](https://skmtc.net/excalidraw/apis/excalidraw-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/excalidraw/excalidraw-api/revisions/c1404d1545ba/schema)