---
title: "Create an empty canvas asset in the Plans section"
method: POST
path: "/v1/projects/{projectId}/plans/assets/canvases"
tags: ["Project Sections"]
---

# Create an empty canvas asset in the Plans section

`POST /v1/projects/{projectId}/plans/assets/canvases`

## Path parameters

- `projectId` string, required

## Request body

- CreateCanvasAssetDto
  - `name` string — Display name; defaults to "Untitled Canvas"
  - `folderId` string, uuid — Folder to create the canvas in, omit for root

## Response `201`

Canvas asset created successfully

- ExpandedAssetApiResponseDto
  - `success` boolean, required — Indicates if the request was successful
  - `message` string, required — Human readable message
  - `data` union, required — Response data
    - object
      - `id` string, uuid, required — Unique identifier of the asset
      - `collectionId` string, uuid, required — ID of the collection this asset belongs to
      - `folderId` string, uuid, nullable — ID of the folder this asset belongs to
      - `name` string, required — Name of the asset
      - `type` 'image', required
      - `thumbnailUrls` string[], required — Ordered preview thumbnail URLs
      - `metadata` object, nullable, required — Asset metadata JSON
        - `sourceAssetId` string — Set on project-level copies; the original artifact
        - `recognizer` object
          - `upload` union, required — Original upload descriptor (kind, asset ids, pdf page numbers)
            - object
              - …
            - object
              - …
            - object
              - …
          - `preprocessedAssetIds` string[], required — Pre-processed B&W blueprint image asset ids
          - `preprocessedHelperAssetIds` string[], required — Optional colored segmentation helper image asset ids
          - `scaleSource` 'printed_dimensions' | 'user_annotation' | 'target_dimensions' | 'fallback', required
          - `scaleConfidence` number, required — Scale calibration confidence, 0..1
          - `floorplanType` object, nullable, required
            - `category` 'residential' | 'commercial' | 'mixed_use' | 'unknown', required
            - `displayLabel` string, required
            - `confidence` number, required — Classifier confidence, 0..1
          - `completedAt` string, date-time, required — ISO timestamp when recognition completed
        - `adminUpload` object — Set on admin /upload-sibling uploads; write-once by convention, not by the DB
          - `sourceAssetId` string, required — The floorplan, image or document the upload was delivered against
          - `uploadedAt` string, date-time, required — Captured server-side at insert time
          - `uploadedByUserId` string — Absent for API-key callers
        - `generation` object
          - `status` 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled', required
          - `intent` 'reference' | 'concept-plan', required
          - `sourceTreatment` 'text-only' | 'edit' | 'inspiration', required
          - `requestedByUserId` string, uuid, required
          - `requestedInChatId` string, uuid, required
          - `clientRequestId` string, required
          - `prompt` string, required
          - `brief` string
          - `aspectRatio` '1:1' | '2:3' | '3:2' | '3:4' | '4:3' | '4:5' | '9:16' | '16:9' | '21:9', required
          - `referenceAssetIds` string[], required — What the user pointed at
          - `replacesAssetId` string, uuid — Whose spot on the canvas this result takes
          - `sourceAssetIds` string[], required — References resolved to assets with real files; the model input
          - `fallbackAssetId` string, uuid — What the canvas draws while waiting, resolved from replacesAssetId alone
          - `creditLockId` string, uuid, required — One lock per image, never per batch
          - `batch` object
            - `position` integer, required
            - `count` integer, required
          - `tuning` object
            - `reasoningEffort` 'low' | 'medium' | 'high' | 'xhigh' | 'max'
            - `imageQuality` 'low' | 'medium' | 'high' | 'auto'
          - `billingOutcome` 'committed' | 'released'
          - `attempt` integer, required
          - `provider` 'openai-responses'
          - `errorCode` string
          - `failureKind` 'application_deadline' | 'transport_timeout' | 'provider_error'
          - `latencyMs` integer
          - `queuedAt` string, date-time, required
          - `startedAt` string, date-time
          - `providerStartedAt` string, date-time
          - `finishedAt` string, date-time
      - `lockedAt` unknown, required
      - `isLocked` boolean, required — Whether the asset is currently locked (computed from lockedAt and TTL)
      - `deletedAt` unknown
      - `createdAt` unknown, required
      - `updatedAt` unknown, required
      - `details` object, required
        - `mimeType` string, required — Mimetype of the storage file
        - `fileUrl` string, uri, required — URL using file's storage key
        - `sizeInBytes` integer, required — Storage file size
    - object
      - `id` string, uuid, required — Unique identifier of the asset
      - `collectionId` string, uuid, required — ID of the collection this asset belongs to
      - `folderId` string, uuid, nullable — ID of the folder this asset belongs to
      - `name` string, required — Name of the asset
      - `type` 'document', required
      - `thumbnailUrls` string[], required — Ordered preview thumbnail URLs
      - `metadata` object, nullable, required — Asset metadata JSON
        - `sourceAssetId` string — Set on project-level copies; the original artifact
        - `recognizer` object
          - `upload` union, required — Original upload descriptor (kind, asset ids, pdf page numbers)
            - object
              - …
            - object
              - …
            - object
              - …
          - `preprocessedAssetIds` string[], required — Pre-processed B&W blueprint image asset ids
          - `preprocessedHelperAssetIds` string[], required — Optional colored segmentation helper image asset ids
          - `scaleSource` 'printed_dimensions' | 'user_annotation' | 'target_dimensions' | 'fallback', required
          - `scaleConfidence` number, required — Scale calibration confidence, 0..1
          - `floorplanType` object, nullable, required
            - `category` 'residential' | 'commercial' | 'mixed_use' | 'unknown', required
            - `displayLabel` string, required
            - `confidence` number, required — Classifier confidence, 0..1
          - `completedAt` string, date-time, required — ISO timestamp when recognition completed
        - `adminUpload` object — Set on admin /upload-sibling uploads; write-once by convention, not by the DB
          - `sourceAssetId` string, required — The floorplan, image or document the upload was delivered against
          - `uploadedAt` string, date-time, required — Captured server-side at insert time
          - `uploadedByUserId` string — Absent for API-key callers
        - `generation` object
          - `status` 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled', required
          - `intent` 'reference' | 'concept-plan', required
          - `sourceTreatment` 'text-only' | 'edit' | 'inspiration', required
          - `requestedByUserId` string, uuid, required
          - `requestedInChatId` string, uuid, required
          - `clientRequestId` string, required
          - `prompt` string, required
          - `brief` string
          - `aspectRatio` '1:1' | '2:3' | '3:2' | '3:4' | '4:3' | '4:5' | '9:16' | '16:9' | '21:9', required
          - `referenceAssetIds` string[], required — What the user pointed at
          - `replacesAssetId` string, uuid — Whose spot on the canvas this result takes
          - `sourceAssetIds` string[], required — References resolved to assets with real files; the model input
          - `fallbackAssetId` string, uuid — What the canvas draws while waiting, resolved from replacesAssetId alone
          - `creditLockId` string, uuid, required — One lock per image, never per batch
          - `batch` object
            - `position` integer, required
            - `count` integer, required
          - `tuning` object
            - `reasoningEffort` 'low' | 'medium' | 'high' | 'xhigh' | 'max'
            - `imageQuality` 'low' | 'medium' | 'high' | 'auto'
          - `billingOutcome` 'committed' | 'released'
          - `attempt` integer, required
          - `provider` 'openai-responses'
          - `errorCode` string
          - `failureKind` 'application_deadline' | 'transport_timeout' | 'provider_error'
          - `latencyMs` integer
          - `queuedAt` string, date-time, required
          - `startedAt` string, date-time
          - `providerStartedAt` string, date-time
          - `finishedAt` string, date-time
      - `lockedAt` unknown, required
      - `isLocked` boolean, required — Whether the asset is currently locked (computed from lockedAt and TTL)
      - `deletedAt` unknown
      - `createdAt` unknown, required
      - `updatedAt` unknown, required
      - `details` object, required
        - `mimeType` string, required — Mimetype of the storage file
        - `fileUrl` string, uri, required — URL using file's storage key
        - `sizeInBytes` integer, required — Storage file size
    - object
      - `id` string, uuid, required — Unique identifier of the asset
      - `collectionId` string, uuid, required — ID of the collection this asset belongs to
      - `folderId` string, uuid, nullable — ID of the folder this asset belongs to
      - `name` string, required — Name of the asset
      - `type` 'floorplan', required
      - `thumbnailUrls` string[], required — Ordered preview thumbnail URLs
      - `metadata` object, nullable, required — Asset metadata JSON
        - `sourceAssetId` string — Set on project-level copies; the original artifact
        - `recognizer` object
          - `upload` union, required — Original upload descriptor (kind, asset ids, pdf page numbers)
            - object
              - …
            - object
              - …
            - object
              - …
          - `preprocessedAssetIds` string[], required — Pre-processed B&W blueprint image asset ids
          - `preprocessedHelperAssetIds` string[], required — Optional colored segmentation helper image asset ids
          - `scaleSource` 'printed_dimensions' | 'user_annotation' | 'target_dimensions' | 'fallback', required
          - `scaleConfidence` number, required — Scale calibration confidence, 0..1
          - `floorplanType` object, nullable, required
            - `category` 'residential' | 'commercial' | 'mixed_use' | 'unknown', required
            - `displayLabel` string, required
            - `confidence` number, required — Classifier confidence, 0..1
          - `completedAt` string, date-time, required — ISO timestamp when recognition completed
        - `adminUpload` object — Set on admin /upload-sibling uploads; write-once by convention, not by the DB
          - `sourceAssetId` string, required — The floorplan, image or document the upload was delivered against
          - `uploadedAt` string, date-time, required — Captured server-side at insert time
          - `uploadedByUserId` string — Absent for API-key callers
        - `generation` object
          - `status` 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled', required
          - `intent` 'reference' | 'concept-plan', required
          - `sourceTreatment` 'text-only' | 'edit' | 'inspiration', required
          - `requestedByUserId` string, uuid, required
          - `requestedInChatId` string, uuid, required
          - `clientRequestId` string, required
          - `prompt` string, required
          - `brief` string
          - `aspectRatio` '1:1' | '2:3' | '3:2' | '3:4' | '4:3' | '4:5' | '9:16' | '16:9' | '21:9', required
          - `referenceAssetIds` string[], required — What the user pointed at
          - `replacesAssetId` string, uuid — Whose spot on the canvas this result takes
          - `sourceAssetIds` string[], required — References resolved to assets with real files; the model input
          - `fallbackAssetId` string, uuid — What the canvas draws while waiting, resolved from replacesAssetId alone
          - `creditLockId` string, uuid, required — One lock per image, never per batch
          - `batch` object
            - `position` integer, required
            - `count` integer, required
          - `tuning` object
            - `reasoningEffort` 'low' | 'medium' | 'high' | 'xhigh' | 'max'
            - `imageQuality` 'low' | 'medium' | 'high' | 'auto'
          - `billingOutcome` 'committed' | 'released'
          - `attempt` integer, required
          - `provider` 'openai-responses'
          - `errorCode` string
          - `failureKind` 'application_deadline' | 'transport_timeout' | 'provider_error'
          - `latencyMs` integer
          - `queuedAt` string, date-time, required
          - `startedAt` string, date-time
          - `providerStartedAt` string, date-time
          - `finishedAt` string, date-time
      - `lockedAt` unknown, required
      - `isLocked` boolean, required — Whether the asset is currently locked (computed from lockedAt and TTL)
      - `deletedAt` unknown
      - `createdAt` unknown, required
      - `updatedAt` unknown, required
      - `details` object[], required — Array of floor entities
        - `level` integer, required — Level of floor
        - `origin` 'generated' | 'drawn' | 'uploaded' | 'recognized', nullable, required — How this floor was created; null for legacy pre-column floors
        - `floorplanData` object, required — Floorplan data JSON
          - `unit` 'cm', required
          - `version` 'https://maket.ai/spec/mex/0.2', required
          - `floorNumber` integer, required
          - `floorName` string
          - `Vertices` object[], required
            - `uid` string, required
            - `coord` union[], required
              - …
            - `height` number, required
            - `edges` string[], required
          - `Edges` object[], required
            - `uid` string, required
            - `isWall` boolean, required
            - `thickness` number, required
            - `openings` union[], required
              - …
            - `vertices` union[], required
              - …
            - `faces` string[], required
          - `Faces` object[], required
            - `uid` string, required
            - `type` 'bedroom' | 'master_bedroom' | 'secondary_bedroom' | 'full_bathroom' | 'half_bathroom' | 'living_room' | 'family_room' | 'game_room' | 'recreation_room' | 'kitchen' | 'dining_room' | 'office' | 'home_gym' | 'walk_in' | 'closet' | 'pantry' | 'laundry' | 'mechanical_room' | 'entry' | 'mudroom' | 'corridor' | 'stair' | 'garage' | 'front_porch' | 'deck' | 'balcony' | 'outdoor' | 'any', required
            - `name` string
            - `edges` string[], required
            - `edgeSenses` boolean[], required
            - `innerRings` object[]
              - …
          - `Fixtures` object[], required
            - `uid` string, required
            - `fixtureAssetId` string, uuid, required
            - `position` union[], required
              - …
            - `rotation` number, required
            - `mirrorX` boolean
            - `mirrorY` boolean
            - `dimensions` object
          - `UnattachedOpenings` union[]
            - union
              - …
        - `visualizerStyleBindings` object[], required — Visualizer style bindings for the floor
          - `elementUid` string, uuid, required
          - `elementType` 'all' | 'floor' | 'room' | 'wall' | 'door' | 'window' | 'fixture' | 'ceiling' | 'exterior_wall', required
          - `category` 'general_floor' | 'bathroom_floor' | 'wall' | 'door' | 'window' | 'hard_furniture' | 'soft_furniture' | 'kitchen_countertops' | 'kitchen_cabinets' | 'bathroom_countertops' | 'bathroom_cabinets' | 'rugs' | 'plants' | 'appliances' | 'plumbing_fixtures' | 'waterproof' | 'outdoor_furniture' | 'upholstered' | 'ceiling' | 'deck' | 'balcony' | 'front_porch' | 'gym_equipment' | 'pool_table' | 'ping_pong' | 'yoga_mat' | 'garage_floor', nullable
          - `selectedStyleId` string, uuid, nullable, required
          - `selectedMaterialIds` string[], required
          - `selectedInspirationalImageAssetIds` string[]
          - `selectedColor` string, nullable, required
          - `llmPrompt` string, nullable
          - `inherits` boolean
        - `ceilingHeightMeters` number, required — Height of ceiling in meters
        - `createdAt` unknown, required
        - `updatedAt` unknown, required
        - `cameras` object[], required
          - `id` string, uuid, required — Camera ID
          - `level` integer, required — Level of floor the camera is on
          - `name` string, required — Name of camera
          - `heightRelative` number, required
          - `position` union[], required — Position of camera
            - union
              - …
          - `rotation` number, required — Rotation of camera
          - `pitch` number, required — Camera pitch in degrees; 0 is level, positive looks down
          - `fov` number, required — Field of view of camera
          - `aspectRatio` '1:1' | '4:3' | '3:2' | '16:9' | '2:3' | '4:5' | '9:16', required — Aspect ratio for generated renders
          - `active` boolean, required — Camera active status
          - `llmPrompt` string, nullable, required
          - `inspirationImageAssetIds` string[], required — Asset IDs of inspiration images attached to this camera (max 4)
          - `renderCount` integer, required — Number of renders for this camera
          - `createdAt` unknown, required
          - `updatedAt` unknown, required
    - object
      - `id` string, uuid, required — Unique identifier of the asset
      - `collectionId` string, uuid, required — ID of the collection this asset belongs to
      - `folderId` string, uuid, nullable — ID of the folder this asset belongs to
      - `name` string, required — Name of the asset
      - `type` 'canvas', required
      - `thumbnailUrls` string[], required — Ordered preview thumbnail URLs
      - `metadata` object, nullable, required — Asset metadata JSON
        - `sourceAssetId` string — Set on project-level copies; the original artifact
        - `recognizer` object
          - `upload` union, required — Original upload descriptor (kind, asset ids, pdf page numbers)
            - object
              - …
            - object
              - …
            - object
              - …
          - `preprocessedAssetIds` string[], required — Pre-processed B&W blueprint image asset ids
          - `preprocessedHelperAssetIds` string[], required — Optional colored segmentation helper image asset ids
          - `scaleSource` 'printed_dimensions' | 'user_annotation' | 'target_dimensions' | 'fallback', required
          - `scaleConfidence` number, required — Scale calibration confidence, 0..1
          - `floorplanType` object, nullable, required
            - `category` 'residential' | 'commercial' | 'mixed_use' | 'unknown', required
            - `displayLabel` string, required
            - `confidence` number, required — Classifier confidence, 0..1
          - `completedAt` string, date-time, required — ISO timestamp when recognition completed
        - `adminUpload` object — Set on admin /upload-sibling uploads; write-once by convention, not by the DB
          - `sourceAssetId` string, required — The floorplan, image or document the upload was delivered against
          - `uploadedAt` string, date-time, required — Captured server-side at insert time
          - `uploadedByUserId` string — Absent for API-key callers
        - `generation` object
          - `status` 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled', required
          - `intent` 'reference' | 'concept-plan', required
          - `sourceTreatment` 'text-only' | 'edit' | 'inspiration', required
          - `requestedByUserId` string, uuid, required
          - `requestedInChatId` string, uuid, required
          - `clientRequestId` string, required
          - `prompt` string, required
          - `brief` string
          - `aspectRatio` '1:1' | '2:3' | '3:2' | '3:4' | '4:3' | '4:5' | '9:16' | '16:9' | '21:9', required
          - `referenceAssetIds` string[], required — What the user pointed at
          - `replacesAssetId` string, uuid — Whose spot on the canvas this result takes
          - `sourceAssetIds` string[], required — References resolved to assets with real files; the model input
          - `fallbackAssetId` string, uuid — What the canvas draws while waiting, resolved from replacesAssetId alone
          - `creditLockId` string, uuid, required — One lock per image, never per batch
          - `batch` object
            - `position` integer, required
            - `count` integer, required
          - `tuning` object
            - `reasoningEffort` 'low' | 'medium' | 'high' | 'xhigh' | 'max'
            - `imageQuality` 'low' | 'medium' | 'high' | 'auto'
          - `billingOutcome` 'committed' | 'released'
          - `attempt` integer, required
          - `provider` 'openai-responses'
          - `errorCode` string
          - `failureKind` 'application_deadline' | 'transport_timeout' | 'provider_error'
          - `latencyMs` integer
          - `queuedAt` string, date-time, required
          - `startedAt` string, date-time
          - `providerStartedAt` string, date-time
          - `finishedAt` string, date-time
      - `lockedAt` unknown, required
      - `isLocked` boolean, required — Whether the asset is currently locked (computed from lockedAt and TTL)
      - `deletedAt` unknown
      - `createdAt` unknown, required
      - `updatedAt` unknown, required
      - `details` object, required — The canvas document — placement only
        - `version` 'https://maket.ai/spec/canvas/0.1', required
        - `elements` union[], required
          - union
            - object
              - …
            - object
              - …
  - `timestamp` string, date-time, required — Timestamp of the response

## Changes

- **2026-09-23** `b92f36c3da65` — 1 warning, 1 info
  - added the new `garage_floor` enum value to the `data/oneOf[subschema #3]/details/items/visualizerStyleBindings/items/category` response property for the response status `201`
  - added the optional property `data/oneOf[subschema #3]/details/items/floorplanData/Faces/items/innerRings` to the response with the `201` status
- **2026-09-19** `28c2b3b6b3b4` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/maket/apis/virtual-architect-api/changes/v1/projects/:projectId/plans/assets/canvases/post.md)

---

[API](https://skmtc.dev/maket/apis/virtual-architect-api.md) · [All operations](https://skmtc.dev/maket/apis/virtual-architect-api/llms.txt) · [OpenAPI document](https://skmtc.dev/maket/apis/virtual-architect-api/revisions/ad71cae36f29?raw)