Cube Planning Canvases API
The Canvases API from Cube Planning — 10 operation(s) for canvases.
OpenAPI Specification
openapi: 3.0.3
info:
title: Cube Agents Canvases API
version: 1.0.0 (1.0)
description: "#### General Description\nAn API to access underlying Cube functionality. These endpoints are the same endpoints\nthat support Cube's universal add-ons and a plethora of integrations meaning you'll be able to interact with your\nCube data in many powerful ways. Visit the API section of Cube's [Help Center](https://help.cubesoftware.com/hc/en-us/sections/18205290556180-Custom-Integrations)\nfor more usage guides on how you can use this API to integrate with Cube to accomplish various tasks!\n\n#### Versioning\nAll requests to the API require a version to be configured via an `Accept` Header. The value of this Header should look like this:\n```\nAccept: application/json; version=1.0\n```\nNote that the version number may differ depending on which version of the endpoint is needed.\n\n#### Response Structure\nThe general response structure of Cube's API endpoints will contain a `\"data\"` and `\"metadata\"` root level key:\n```json\n{\n \"data\": { ... object data or list of objects ... },\n \"metadata\": {\n \"status\": 200,\n \"message\": \"Potential message with additional context\",\n \"error\": false,\n \"code\": \"\"\n }\n}\n```\n\n#### Rate Limiting\nAll endpoints have a rate limit configured, most of them default to 5/s.\nWhen the rate limit is encountered, a 429 HTTP code will be returned.\n\n#### Error Handling\nIn the event an error occurs, the response will typically look like this:\n```json\n{\n \"data\": {},\n \"metadata\": {\n \"status\": 400,\n \"message\": \"Some error message\",\n \"error\": true,\n \"code\": \"SOME_ERROR_CODE\"\n }\n}\n```\n"
termsOfService: https://www.cubesoftware.com/terms-of-service
servers:
- url: https://api.cubesoftware.com
description: Cube API Production URL
tags:
- name: Canvases
paths:
/canvases:
get:
operationId: canvases_list
description: 'List of all canvases available to the authenticated user company.
- Results are ordered by creation date, newest first.
- Each canvas includes basic metadata and an `is_liked` flag indicating whether the current user has liked it.
- For performance reasons, related fields such as `tabs` and `shared_with` are **not included** in list responses.'
summary: List all canvases.
parameters:
- in: query
name: source
schema:
type: string
enum:
- DECKS
- MCP
- PLAN_MODE
- WORKSPACE
description: 'Filters the results to canvases with the given source.
- By default, only `WORKSPACE` canvases are returned.
- Use `?source=DECKS` to list only Decks-created canvases.'
- in: query
name: widget_type
schema:
type: string
enum:
- RANGE
- TEMPLATE
- TEXT
description: 'Filters the results to canvases that include **at least one widget** of the given type.
- If omitted, no widget-type filtering is applied.'
tags:
- Canvases
security:
- OAuth2: []
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/CanvasListSchema'
examples:
ListCanvases:
value:
- id: 79fc999d-f145-47d7-a6a3-a5792ec1b262
name: One Big Beautiful Canvas
description: Best Canvas Ever
sharing_scheme: MANAGERS
is_liked: true
created_by:
id: 1
first_name: John
last_name: Frusciante
created_at: 2026-07-19 00:15:28.217428+00:00
default_currency_id: null
summary: List Canvases
description: ''
post:
operationId: canvases_create
description: 'Create a new canvas under the authenticated user company.
- Required fields typically include `name`, and optionally layout or metadata fields.
- The response includes the full representation of the newly created canvas.'
summary: Create a new canvas.
tags:
- Canvases
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Canvas'
examples:
CreateACanvas:
value:
name: One Big Beautiful Canvas
description: Best Canvas Ever
sharing_scheme: MANAGERS
summary: Create a Canvas
CreateACanvasWithTabs:
value:
name: One Big Beautiful Canvas
description: Best Canvas Ever
tabs:
- name: Mystical Tab
summary: Create a Canvas with Tabs
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/Canvas'
multipart/form-data:
schema:
$ref: '#/components/schemas/Canvas'
required: true
security:
- OAuth2: []
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/Canvas'
examples:
CanvasCreated:
value:
id: 79fc999d-f145-47d7-a6a3-a5792ec1b262
name: One Big Beautiful Canvas
description: Best Canvas Ever
sharing_scheme: MANAGERS
is_liked: true
created_by:
id: 1
first_name: John
last_name: Frusciante
created_at: 2026-07-19 00:15:28.217428+00:00
tabs: []
shared_with: []
default_currency_id: null
summary: Canvas Created
description: ''
/canvases/{canvas_pk}/tabs:
post:
operationId: canvases_tabs_create
description: Create a new canvas tab.
summary: Create a new canvas tab.
parameters:
- in: path
name: canvas_pk
schema:
type: string
required: true
tags:
- Canvases
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CanvasTab'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/CanvasTab'
multipart/form-data:
schema:
$ref: '#/components/schemas/CanvasTab'
required: true
security:
- OAuth2: []
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/CanvasTab'
description: ''
/canvases/{canvas_pk}/tabs/{id}:
patch:
operationId: canvases_tabs_partial_update
description: Update specific fields of a canvas tab.
summary: Update specific fields of a canvas tab.
parameters:
- in: path
name: canvas_pk
schema:
type: string
required: true
- in: path
name: id
schema:
type: string
required: true
tags:
- Canvases
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PatchedCanvasTab'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/PatchedCanvasTab'
multipart/form-data:
schema:
$ref: '#/components/schemas/PatchedCanvasTab'
security:
- OAuth2: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CanvasTab'
description: ''
delete:
operationId: canvases_tabs_destroy
description: Delete a canvas tab.
summary: Delete a canvas tab.
parameters:
- in: path
name: canvas_pk
schema:
type: string
required: true
- in: path
name: id
schema:
type: string
required: true
tags:
- Canvases
security:
- OAuth2: []
responses:
'204':
description: No response body
/canvases/{canvas_pk}/tabs/{id}/layout:
put:
operationId: canvases_tabs_layout_update
description: Associate widgets with a canvas tab.
summary: Associate widgets with a canvas tab.
parameters:
- in: path
name: canvas_pk
schema:
type: string
required: true
- in: path
name: id
schema:
type: string
required: true
tags:
- Canvases
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CanvasTab'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/CanvasTab'
multipart/form-data:
schema:
$ref: '#/components/schemas/CanvasTab'
required: true
security:
- OAuth2: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CanvasTab'
description: ''
/canvases/{id}:
get:
operationId: canvases_retrieve
description: 'Retrieve details of a specific canvas by ID.
- Includes all fields, including `tabs` and `shared_with` data.
- This endpoint is intended for viewing a single canvas along with its associated tabs and widgets.'
summary: Retrieve a specific canvas
parameters:
- in: path
name: id
schema:
type: string
required: true
tags:
- Canvases
security:
- OAuth2: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Canvas'
examples:
RetrieveACanvas:
value:
id: 79fc999d-f145-47d7-a6a3-a5792ec1b262
name: One Big Beautiful Canvas
description: Best Canvas Ever
sharing_scheme: MANAGERS
is_liked: true
created_by:
id: 1
first_name: John
last_name: Frusciante
created_at: 2026-07-19 00:15:28.217428+00:00
tabs:
- id: 905046b7-d66d-495e-bdb9-f30046199227
name: Mystical Tab
position: 0
layout:
- layout_x: 8
layout_y: 0
height: 8
width: 4
widget:
id: 450d6fd3-381f-4bd5-8ddb-b5df1665c7ea
name: Fabulous Range
settings:
name_visible: true
board_filter_exclusions: []
styles:
data_cells:
horizontal_alignment: right
row_headers:
horizontal_alignment: left
column_headers:
horizontal_alignment: center
type: RANGE
visual_type: LINE
data_sources:
- type: RANGE
object_id: '3'
settings:
content:
A1: Custom formula
A4: Total
formulas:
B2: =A1+A2
B4: =SUM(B2:B3)
C4: =SUM(B2:B3)
D4: =SUM(B2:B3)
shared_with: []
default_currency_id: null
summary: Retrieve a Canvas
description: ''
patch:
operationId: canvases_partial_update
description: 'Update one or more editable fields of an existing canvas.
- Only the provided fields will be modified.
- Non-editable fields (such as `id`, `company_id`, and timestamps) are ignored if included.
- Returns the updated canvas representation.'
summary: Partially update a canvas by ID.
parameters:
- in: path
name: id
schema:
type: string
required: true
tags:
- Canvases
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PatchedCanvas'
examples:
PatchACanvas:
value:
name: One Big Beautiful Canvas
description: Best Canvas Ever
summary: Patch a Canvas
PatchACanvasWithTabsAndLayout:
value:
tabs:
- name: Mystical Tab
position: 0
layout:
- widget:
id: 25dde14c-dbeb-47d4-a346-b33f6c5a7702
layout_x: 0
layout_y: 0
width: 4
height: 8
summary: Patch a Canvas with tabs and layout
description: Save the full tabs–widgets tree in one request.
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/PatchedCanvas'
examples:
PatchACanvas:
value:
name: One Big Beautiful Canvas
description: Best Canvas Ever
summary: Patch a Canvas
PatchACanvasWithTabsAndLayout:
value:
tabs:
- name: Mystical Tab
position: 0
layout:
- widget:
id: 25dde14c-dbeb-47d4-a346-b33f6c5a7702
layout_x: 0
layout_y: 0
width: 4
height: 8
summary: Patch a Canvas with tabs and layout
description: Save the full tabs–widgets tree in one request.
multipart/form-data:
schema:
$ref: '#/components/schemas/PatchedCanvas'
examples:
PatchACanvas:
value:
name: One Big Beautiful Canvas
description: Best Canvas Ever
summary: Patch a Canvas
PatchACanvasWithTabsAndLayout:
value:
tabs:
- name: Mystical Tab
position: 0
layout:
- widget:
id: 25dde14c-dbeb-47d4-a346-b33f6c5a7702
layout_x: 0
layout_y: 0
width: 4
height: 8
summary: Patch a Canvas with tabs and layout
description: Save the full tabs–widgets tree in one request.
security:
- OAuth2: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Canvas'
examples:
PatchedCanvas:
value:
id: 79fc999d-f145-47d7-a6a3-a5792ec1b262
name: One Big Beautiful Canvas
description: Best Canvas Ever
sharing_scheme: MANAGERS
is_liked: true
created_by:
id: 1
first_name: John
last_name: Frusciante
created_at: 2026-07-19 00:15:28.217428+00:00
tabs: []
shared_with: []
default_currency_id: null
summary: Patched Canvas
description: ''
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/error_response_serializer'
examples:
InvalidTabs:
value:
data: {}
metadata:
status: 400
error: true
message: Expected a list of items but got type "str".
code: ''
summary: Invalid tabs
description: Payload validation failed due to incorrect `tabs` structure in the request. Ensure that the tabs data conforms to the expected 2D array format.
description: ''
delete:
operationId: canvases_destroy
description: Permanently delete a canvas by ID.
summary: Delete a canvas.
parameters:
- in: path
name: id
schema:
type: string
required: true
tags:
- Canvases
security:
- OAuth2: []
responses:
'204':
description: No response body
/canvases/{id}/duplicate:
post:
operationId: canvases_duplicate_create
description: Duplicate a canvas. The new canvas will be created with a new name and a copy of the layout.
summary: Duplicate a canvas.
parameters:
- in: path
name: id
schema:
type: string
required: true
tags:
- Canvases
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Canvas'
examples:
DuplicateACanvas(emptyPayload):
value: {}
summary: Duplicate a Canvas (empty payload)
DuplicateACanvasWithTabs(nameSpecified):
value:
name: What-A-Canvas
summary: Duplicate a Canvas with Tabs (name specified)
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/Canvas'
multipart/form-data:
schema:
$ref: '#/components/schemas/Canvas'
required: true
security:
- OAuth2: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Canvas'
description: ''
/canvases/{id}/like:
post:
operationId: canvases_like_create
description: Like a canvas.
summary: Like a canvas
parameters:
- in: path
name: id
schema:
type: string
required: true
tags:
- Canvases
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Canvas'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/Canvas'
multipart/form-data:
schema:
$ref: '#/components/schemas/Canvas'
required: true
security:
- OAuth2: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Canvas'
description: ''
delete:
operationId: canvases_like_destroy
description: Undo a canvas like.
summary: Undo a canvas like.
parameters:
- in: path
name: id
schema:
type: string
required: true
tags:
- Canvases
security:
- OAuth2: []
responses:
'204':
description: No response body
/canvases/widgets:
get:
operationId: canvases_widgets_list
description: List all widgets.
summary: List all widgets.
tags:
- Canvases
security:
- OAuth2: []
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Widget'
description: ''
post:
operationId: canvases_widgets_create
description: Create a new widget.
summary: Create a new widget.
tags:
- Canvases
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Widget'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/Widget'
multipart/form-data:
schema:
$ref: '#/components/schemas/Widget'
required: true
security:
- OAuth2: []
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/Widget'
description: ''
/canvases/widgets/{id}:
get:
operationId: canvases_widgets_retrieve
description: Retrieve details of a specific widget.
summary: Retrieve details of a specific widget.
parameters:
- in: path
name: id
schema:
type: string
required: true
tags:
- Canvases
security:
- OAuth2: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Widget'
description: ''
patch:
operationId: canvases_widgets_partial_update
description: Update specific fields of a widget.
summary: Update specific fields of a widget.
parameters:
- in: path
name: id
schema:
type: string
required: true
tags:
- Canvases
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PatchedWidget'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/PatchedWidget'
multipart/form-data:
schema:
$ref: '#/components/schemas/PatchedWidget'
security:
- OAuth2: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Widget'
description: ''
delete:
operationId: canvases_widgets_destroy
description: 'This is a shortcut class that will include all 6 resourceful actions part of the DRF ViewSets:
- list()
- retrieve()
- create()
- update()
- partial_update()
- destroy()
If you do not want to expose all 6 of these in your ViewSet, then use the CubeAuthenticatedViewSet and add the
appropriate mixins to it (see rest_framework.mixins). This will allow the api to behave appropriately and block
requests to unprocessable endpoints. Furthermore, it will make the drf_spectacular documentation be generated more
easily.'
parameters:
- in: path
name: id
schema:
type: string
required: true
tags:
- Canvases
security:
- OAuth2: []
responses:
'204':
description: No response body
/canvases/widgets/{id}/render:
post:
operationId: canvases_widgets_render_create
description: 'Generates a PNG screenshot of the widget component by rendering it in a headless browser.
- The screenshot is uploaded to S3 for record keeping.
- Returns the PNG image directly.
- Optional rendering parameters can be provided in the request body.'
summary: Generate a screenshot of a widget component.
parameters:
- in: path
name: id
schema:
type: string
required: true
tags:
- Canvases
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/WidgetRenderRequest'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/WidgetRenderRequest'
multipart/form-data:
schema:
$ref: '#/components/schemas/WidgetRenderRequest'
security:
- OAuth2: []
responses:
'200':
content:
application/json:
schema:
type: object
properties:
image:
type: string
description: Base64-encoded PNG
description: Base64-encoded PNG image of the rendered widget component
'400':
description: Bad request - invalid parameters
'404':
description: Widget not found
'500':
description: Error generating screenshot
components:
schemas:
WidgetRenderRequest:
type: object
properties:
width:
type: integer
description: Viewport width in pixels
height:
type: integer
description: Viewport height in pixels
enable_branding:
type: boolean
description: Whether to show branding overlay on the widget
enable_filters:
type: boolean
description: Whether to show filters overlay on the widget
enable_timestamp:
type: boolean
description: Whether to show timestamp overlay on the widget
filters:
type: array
items:
$ref: '#/components/schemas/WidgetRenderFilter'
description: Dimension filters to apply at render time
PatchedWidget:
type: object
description: "A serializer that conditionally includes optional fields based on context.\n\nOptional fields should be listed in `Meta.read_optional_fields`. To include them\nin the output, pass a list via `context['include_fields']` (for top-level serializers)\nor `context[<nested_path>]['include_fields']` (for nested serializers).\n\nExamples:\n class ChildSerializer(IncludeOptionalFieldsSerializerMixin, serializers.ModelSerializer):\n extra = serializers.CharField()\n class Meta:\n model = Child\n fields = ['id', 'extra']\n read_optional_fields = ['extra']\n\n class ParentSerializer(IncludeOptionalFieldsSerializerMixin, serializers.ModelSerializer):\n child = ChildSerializer()\n expensive = serializers.CharField()\n class Meta:\n model = Parent\n fields = ['id', 'child', 'expensive']\n read_optional_fields = ['expensive']\n\n # Top-level usage (includes 'expensive' field)\n ParentSerializer(instance, context={'include_fields': ['expensive']}).data\n\n # Nested usage (includes 'extra' field inside child)\n ParentSerializer(\n instance,\n context={'child': {'include_fields': ['extra']}}\n ).data"
properties:
id:
type: string
format: uuid
readOnly: true
name:
type: string
maxLength: 255
type:
$ref: '#/components/schemas/WidgetTypeEnum'
visual_type:
$ref: '#/components/schemas/VisualTypeEnum'
settings: {}
data_sources:
type: array
items:
$ref: '#/components/schemas/WidgetDataSource'
PatchedCanvasTab:
type: object
description: Mixin to delegate create and update operations to a service class.
properties:
id:
type: string
format: uuid
readOnly: true
canvas_id:
type: string
format: uuid
readOnly: true
name:
type: string
maxLength: 255
position:
type: integer
maximum: 4294967295
minimum: 0
format: int64
layout:
type: array
items:
$ref: '#/components/schemas/CanvasTabWidget'
CanvasTabWidget:
type: object
properties:
widget:
type: string
format: uuid
layout_x:
type: integer
maximum: 4294967295
minimum: 0
format: int64
layout_y:
type: integer
maximum: 4294967295
minimum: 0
format: int64
width:
type: integer
maximum: 4294967295
minimum: 0
format: int64
height:
type: integer
maximum: 4294967295
minimum: 0
format: int64
required:
- layout_x
- layout_y
- widget
WidgetDataSource:
type: object
properties:
id:
type: integer
readOnly: true
widget_id:
type: string
format: uuid
readOnly: true
settings: {}
type:
type: string
writeOnly: true
object_id:
type: string
maxLength: 36
required:
- id
- object_id
- type
- widget_id
metadata_serializer:
type: object
properties:
status:
type: integer
error:
type: boolean
message:
type: string
code:
type: string
required:
- code
- error
- message
- status
PatchedCanvas:
type: object
description: Mixin to delegate create and update operations to a service class.
properties:
id:
type: string
format: uuid
readOnly: true
name:
type: string
maxLength: 50
description:
type: string
nullable: true
sharing_scheme:
$ref: '#/components/schemas/SharingScheme2f1Enum'
source:
$ref: '#/components/schemas/Source251Enum'
filters: {}
default_currency_id:
type: integer
nullable: true
shared_with:
type: array
items:
type: string
nullable: true
tabs:
type: array
items:
$ref: '#/components/schemas/CanvasTab'
is_liked:
type: boolean
readOnly: true
created_by:
allOf:
- $ref: '#/components/schemas/User'
readOnly: true
created_at:
type: string
format: date-time
readOnly: true
WidgetRenderFilter:
type: object
properties:
tld_id:
type: integer
description: Top-level dimension ID
value:
type: string
description: Dimension member ID to filter by
required:
- tld_id
- value
VisualTypeEnum:
enum:
- TEXT
- DATA_TABLE
- LINE
- BAR
- ROW
- COMBO
- PIE
- DONUT
- METRIC
- TREND
- WATERFALL
type: string
description: '* `TEXT` - Text
* `DATA_TABLE` - Data Table
* `LINE` - Line Chart
* `BAR` - Bar Chart
* `ROW` - Row Chart
* `COMBO` - Combo Chart
* `PIE` - Pie Chart
* `DONUT` - Donut Chart
* `METRIC` - Metric
* `TREND` - Trend
* `WATERFALL` - Waterfall Chart'
CanvasTab:
type: object
description: Mixin to delegate create and update operations to a service class.
properties:
id:
type: string
format: uuid
readOnly: true
name:
type: string
maxLength: 255
position:
type: integer
maximum: 4294967295
minimum: 0
format: int64
layout:
type: array
items:
$ref: '#/components/schemas/CanvasTabWidget'
required:
- id
- name
CanvasListSchema:
type: object
properties:
name:
type: string
maxLength: 50
filters: {}
default_currency_id:
type: intege
# --- truncated at 32 KB (78 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cube-planning/refs/heads/main/openapi/cube-planning-canvases-api-openapi.yml