Create new scene
Create a new empty scene with specified metadata in a collection.
This endpoint creates a scene with:
- Basic metadata (name, pinned status)
- Assignment to a specific collection
- Empty content (no drawing elements)
- Default sharing settings
This endpoint only creates the scene structure and metadata. To add content (drawings, shapes, text), use the content endpoints after creation.
The scene will be created with default permissions based on your workspace settings. Sharing links can be created separately using the links endpoints.
Use cases:
- Creating scenes programmatically for templates
- Bulk scene creation for projects
- Integration with external project management tools
- Automated scene setup for teams
Authorization
apiKey AuthorizationBearer <token>
The API will use the Authorization: Bearer <your-key> header for requests.
In: header
Request Body
application/json
name*string
Length
1 <= lengthpinned?boolean
collectionId?|
[key: string]?never
Response Body
application/json
application/json
application/json
application/json
curl -X POST "https://api.excalidraw.com/api/v1/scenes" \ -H "Content-Type: application/json" \ -d '{ "name": "string" }'{
"metadata": {
"workspace": "string",
"name": "string",
"created": "string",
"updated": "string",
"previewUrl": "string",
"previewFilename": "string",
"previewBackground": "string",
"isDeleted": true,
"creator": "string",
"updater": "string",
"sceneVersion": "string",
"lastAcknowledgedVersion": -9007199254740991,
"linkSharing": 0,
"collection": "string",
"updateCount": 0,
"revisionCount": 0,
"lastRevision": "string",
"totalElements": 0,
"deletedElements": 0,
"pinned": true,
"hasNonDeletedFrames": true,
"isWelcomeScene": true,
"id": "string"
},
"readOnlyLinks": [
{
"id": "string",
"scene": "string",
"workspace": "string",
"created": "string",
"updated": "string",
"updatedBy": "string",
"creator": "string",
"preview": "string",
"previewPath": "string",
"type": "readonly",
"status": "active",
"name": "string",
"data": {
"showTitle": true,
"showMenu": true,
"darkMode": true,
"disableInteraction": true,
"showDarkModeToggle": true,
"showFrameOutlines": true,
"x": 0,
"y": 0,
"width": 0,
"height": 0
}
}
],
"sharedSlidesLinks": [
{
"id": "string",
"scene": "string",
"workspace": "string",
"created": "string",
"updated": "string",
"updatedBy": "string",
"creator": "string",
"preview": "string",
"previewPath": "string",
"isActive": true,
"type": "slides",
"data": {
"name": "string",
"showSlideTitle": true,
"animateSlides": true,
"disallowDownload": true,
"autoPlaySlides": 100
}
}
]
}{
"statusCode": 400,
"error": "Bad Request",
"message": "string"
}{
"statusCode": 401,
"error": "Unauthorized",
"message": "string"
}{
"statusCode": 403,
"error": "Forbidden",
"message": "string"
}