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

# Replace scene content

`PUT /api/v1/scenes/{sceneId}/content`

Replace the complete content of a scene with the supplied elements, files, and app state.

    This endpoint allows you to:
    - Replace all scene elements with new ones
    - Update or add files to the scene
    - Modify scene settings and app state
    - Force connected editors to reload the scene after an authoritative full replacement

    <Callout type="warn">
    This is an authoritative full replacement. Any existing elements not included in the request will be removed from the scene, connected editors will be forced to reload instead of reconciling the change incrementally, and any `sceneVersion` value in the request body will be ignored because the server always recomputes it from the submitted content. If you only want to add or update specific elements, files, or app-state fields without replacing the whole scene, use `PATCH /scenes/:sceneId/content` instead.
    </Callout>

    **Use cases:**
    - Restoring scene from backup
    - Replacing a scene from an external system of record
    - Correcting a scene even while editors are currently open
    - Programmatic scene generation

## Path parameters

- `sceneId` string, required

## Request body

- object
  - `type` 'excalidraw', required
  - `version` number, required
  - `source` string, required
  - `appState` unknown, required
  - `elements` unknown, required
  - `sceneVersion` string
  - `files` object, required
  - `filesFailedToEmbed` string[] — Ignored on write requests. Present so GET responses can be reused as PUT/PATCH inputs.

## Response `200`

This response returns the replaced content for the scene.

- object — This response returns the replaced content for the scene.
  - `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)