Skip to main content

Visit Later

N/a

General Notes

  • New canvas is assigned displayOrder = Date.now() (monotonically increasing, race-safe) unless SUPER_ADMIN provides an explicit value
  • Default widgetLimit is 10
  • SUPER_ADMIN must provide userId to specify the target user and can optionally set displayOrder, widgetLimit, and isDefault
  • AE/CIO body accepts name only — Cerbos blocks restricted fields via additionalProperties: false
  • SUPER_ADMIN verifies the target user exists before creating the canvas
  • Per-user canvas limit (configurable via CANVAS_LIMIT_PER_USER SSM param, default 15) — enforced atomically inside a MongoDB transaction. Only active canvases (deletedAt is null) count. SUPER_ADMIN's own canvases are exempt, but limit applies to target user when creating on behalf of another user

Flow

Mermaid editor

Test cases

Method & URL

POST v1/canvases

Request

Headers

authorization
  - Required
  - Type : <string>
  - Bearer session token

Query


Body (AE/CIO)

name
  - Required
  - Type : <string>
  - Display name for the new canvas
  - Min length: 1, Max length: 100

Body (SUPER_ADMIN)

name
  - Required
  - Type : <string>
  - Display name for the new canvas
  - Min length: 1, Max length: 100

userId
  - Required
  - Type : <string>
  - The target user to create the canvas for

displayOrder
  - Optional
  - Type : <number>
  - Minimum: 0
  - Defaults to Date.now() if omitted

widgetLimit
  - Optional
  - Type : <number>
  - Minimum: 1
  - Defaults to 10 if omitted

isDefault
  - Optional
  - Type : <boolean>
  - Defaults to false if omitted

Path parameter


Response

201

success
  - Type : true (boolean)
  - This indicates that request was executed successfully

message
  - Type : <string> | null
  - null on success

data
  - Type : <object>

data.canvas
  - Type : <object>
  - The newly created canvas

data.canvas.id
  - Type : <string>

data.canvas.name
  - Type : <string>

data.canvas.displayOrder
  - Type : <number>

data.canvas.isDefault
  - Type : false (boolean)

data.canvas.widgetLimit
  - Type : <number>

400

success
  - Type : false (boolean)

message
  - Type : <string>
  - "Tab name is required." (name missing)
  - "Tab name cannot be empty." (empty name)
  - "Tab name cannot exceed 100 characters." (name too long)
  - "You can have up to {N} tabs. Delete an existing tab to create a new one." (canvas limit reached)
  - "Something went wrong. We're on it." (invalid userId, target user not found, or other system errors)