---
title: "Create new scene"
method: POST
path: "/api/v1/scenes"
tags: ["scenes"]
---

# Create new scene

`POST /api/v1/scenes`

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

    <Callout type="warn">
    This endpoint only creates the scene structure and metadata. To add content (drawings, shapes, text), use the content endpoints after creation.
    </Callout>

    <Callout type="info">
    The scene will be created with default permissions based on your workspace settings. Sharing links can be created separately using the links endpoints.
    </Callout>

    **Use cases:**
    - Creating scenes programmatically for templates
    - Bulk scene creation for projects
    - Integration with external project management tools
    - Automated scene setup for teams

## Request body

- object
  - `name` string, required
  - `pinned` boolean, required
  - `collectionId` string, required — Collection ID. Personal API keys may use 'private' for the key owner's virtual private collection. Workspace API keys cannot access private collections.

## Response `200`

This response returns the details of the newly created scene.

- object — This response returns the details of the newly created scene.
  - `metadata` object, required
    - `workspace` string, required
    - `name` string, required
    - `isUntitled` boolean
    - `created` string, required
    - `updated` string, required
    - `previewUrl` string, required
    - `previewFilename` string, required
    - `previewBackground` string, required
    - `isDeleted` boolean, required
    - `isPrivate` boolean, required
    - `creator` string, required
    - `updater` string, required
    - `sceneVersion` string, required
    - `contentEpoch` integer, required
    - `lastAcknowledgedVersion` integer
    - `linkSharing` union, required
      - 0
      - 1
      - 3
    - `readComments` boolean
    - `writeComments` boolean
    - `allowCalls` boolean
    - `collection` string, required
    - `updateCount` number, required
    - `revisionCount` number, required
    - `lastRevision` string, required
    - `totalElements` number, required
    - `deletedElements` number, required
    - `pinned` boolean, required
    - `hasNonDeletedFrames` boolean
    - `isSlidesSharingEnabled` boolean
    - `isWelcomeScene` boolean
    - `id` string, required
  - `readOnlyLinks` object[], required
    - `id` string, required
    - `scene` string, required
    - `workspace` string, required
    - `created` string, required
    - `updated` string, required
    - `updatedBy` string, required
    - `creator` string, required
    - `preview` string, required
    - `previewPath` string, required
    - `type` 'readonly', required
    - `status` union, required
      - 'active'
      - 'inactive'
    - `name` string, required
    - `data` object, required
      - `showTitle` boolean
      - `showMenu` boolean
      - `darkMode` boolean
      - `disableInteraction` boolean
      - `showDarkModeToggle` boolean
      - `showFrameOutlines` boolean
      - `x` number, required
      - `y` number, required
      - `width` number, required
      - `height` number, required
  - `sharedSlidesLinks` object[], required
    - `id` string, required
    - `scene` string, required
    - `workspace` string, required
    - `created` string, required
    - `updated` string, required
    - `updatedBy` string, required
    - `creator` string, required
    - `preview` string, required
    - `previewPath` string, required
    - `isActive` boolean, required
    - `type` 'slides', required
    - `data` object, required
      - `name` string, required
      - `showSlideTitle` boolean, required
      - `animateSlides` boolean, required
      - `disallowDownload` boolean
      - `autoPlaySlides` number

## 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)