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: trueto 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.
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.
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
Authorization
apiKey The API will use the Authorization: Bearer <your-key> header for requests.
In: header
Path Parameters
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X PATCH "https://api.excalidraw.com/api/v1/scenes/string/content" \ -H "Content-Type: application/json" \ -d '{}'{
"type": "excalidraw",
"version": 0,
"source": "string",
"appState": {
"viewBackgroundColor": "string",
"lockedMultiSelections": {
"property1": true,
"property2": true
}
},
"elements": [
null
],
"sceneVersion": "string",
"files": {
"property1": {
"mimeType": "string",
"id": "string",
"created": 9007199254740991,
"lastRetrieved": 9007199254740991,
"version": 9007199254740991,
"dataURL": "string"
},
"property2": {
"mimeType": "string",
"id": "string",
"created": 9007199254740991,
"lastRetrieved": 9007199254740991,
"version": 9007199254740991,
"dataURL": "string"
}
}
}{
"statusCode": 400,
"error": "Bad Request",
"message": "string"
}{
"statusCode": 401,
"error": "Unauthorized",
"message": "string"
}{
"statusCode": 403,
"error": "Forbidden",
"message": "string"
}{
"statusCode": 404,
"error": "Not Found",
"message": "string"
}Last updated on
