Cube Canvases API
The Canvases API from Cube — 10 operation(s) for canvases.
The Canvases API from Cube — 10 operation(s) for canvases.
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: Production API 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: 4cb1b0a7-d716-4248-998d-01c46ca90457
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:28:02.193278+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: 4cb1b0a7-d716-4248-998d-01c46ca90457
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:28:02.193278+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: 4cb1b0a7-d716-4248-998d-01c46ca90457
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:28:02.193278+00:00
tabs:
- id: 36d35d99-0fe9-4622-97d0-d8e8ead2c475
name: Mystical Tab
position: 0
layout:
- layout_x: 8
layout_y: 0
height: 8
width: 4
widget:
id: 26474ad1-e1dc-46d6-943d-55ee2f9dfac9
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: 51c46118-f9a9-47d6-803d-adf0b1d266b3
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: 51c46118-f9a9-47d6-803d-adf0b1d266b3
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: 51c46118-f9a9-47d6-803d-adf0b1d266b3
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: 4cb1b0a7-d716-4248-998d-01c46ca90457
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:28:02.193278+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:
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'
error_response_serializer:
type: object
properties:
data:
type: object
additionalProperties: {}
metadata:
$ref: '#/components/schemas/metadata_serializer'
required:
- data
- metadata
NullEnum:
enum:
- null
TimezoneEnum:
enum:
- Africa/Abidjan
- Africa/Accra
- Africa/Addis_Ababa
- Africa/Algiers
- Africa/Asmara
- Africa/Asmera
- Africa/Bamako
- Africa/Bangui
- Africa/Banjul
- Africa/Bissau
- Africa/Blantyre
- Africa/Brazzaville
- Africa/Bujumbura
- Africa/Cairo
- Africa/Casablanca
- Africa/Ceuta
- Africa/Conakry
- Africa/Dakar
- Africa/Dar_es_Salaam
- Africa/Djibouti
- Africa/Douala
- Africa/El_Aaiun
- Africa/Freetown
- Africa/Gaborone
- Africa/Harare
- Africa/Johannesburg
- Africa/Juba
- Africa/Kampala
- Africa/Khartoum
- Africa/Kigali
- Africa/Kinshasa
- Africa/Lagos
- Africa/Libreville
- Africa/Lome
- Africa/Luanda
- Africa/Lubumbashi
- Africa/Lusaka
- Africa/Malabo
- Africa/Maputo
- Africa/Maseru
- Africa/Mbabane
- Africa/Mogadishu
- Africa/Monrovia
- Africa/Nairobi
- Africa/Ndjamena
- Africa/Niamey
- Africa/Nouakchott
- Africa/Ouagadougou
- Africa/Porto-Novo
- Africa/Sao_Tome
- Africa/Timbuktu
- Africa/Tripoli
- Africa/Tunis
- Africa/Windhoek
- America/Adak
- America/Anchorage
- America/Anguilla
- America/Antigua
- America/Araguaina
- America/Argentina/Buenos_Aires
- America/Argentina/Catamarca
- America/Argentina/ComodRivadavia
- America/Argentina/Cordoba
- America/Argentina/Jujuy
- America/Argentina/La_Rioja
- America/Argentina/Mendoza
- America/Argentina/Rio_Gallegos
- America/Argentina/Salta
- America/Argentina/San_Juan
- America/Argentina/San_Luis
- America/Argentina/Tucuman
- America/Argentina/Ushuaia
- America/Aruba
- America/Asuncion
- America/Atikokan
- America/Atka
- America/Bahia
- America/Bahia_Banderas
- America/Barbados
- America/Belem
- America/Belize
- America/Blanc-Sablon
- America/Boa_Vista
- America/Bogota
- America/Boise
- America/Buenos_Aires
- America/Cambridge_Bay
- America/Campo_Grande
- America/Cancun
- America/Caracas
- America/Catamarca
- America/Cayenne
- America/Cayman
- America/Chicago
- America/Chihuahua
- America/Ciudad_Juarez
- America/Coral_Harbour
- America/Cordoba
- America/Costa_Rica
- America/Coyhaique
- America/Creston
- America/Cuiaba
- America/Curacao
- America/Danmarkshavn
- America/Dawson
- America/Dawson_Creek
- America/Denver
- America/Detroit
- America/Dominica
- America/Edmonton
- America/Eirunepe
- America/El_Salvador
- America/Ensenada
- America/Fort_Nelson
- America/Fort_Wayne
- America/Fortaleza
- America/Glace_Bay
- America/Godthab
- America/Goose_Bay
- America/Grand_Turk
- America/Grenada
- America/Guadeloupe
- America/Guatemala
- America/Guayaquil
- America/Guyana
- America/Halifax
- America/Havana
- America/Hermosillo
- America/Indiana/Indianapolis
- America/Indiana/Knox
- America/Indiana/Marengo
- America/Indiana/Petersburg
- America/Indiana/Tell_City
- America/Indiana/Vevay
- America/Indiana/Vincennes
- America/Indiana/Winamac
- America/Indianapolis
- America/Inuvik
- America/Iqaluit
- America/Jamaica
- America/Jujuy
- America/Juneau
- America/Kentucky/Louisville
- America/Kentucky/Monticello
- America/Knox_IN
- America/Kralendijk
- America/La_Paz
- America/Lima
- America/Los_Angeles
- America/Louisville
- America/Lower_Princes
- America/Maceio
- America/Managua
- America/Manaus
- America/Marigot
- America/Martinique
- America/Matamoros
- America/Mazatlan
- America/Mendoza
- America/Menominee
- America/Merida
- America/Metlakatla
- America/Mexico_City
- America/Miquelon
- America/Moncton
- America/Monterrey
- America/Montevideo
- America/Montreal
- America/Montserrat
- America/Nassau
- America/New_York
- America/Nipigon
- America/Nome
- America/Noronha
- America/North_Dakota/Beulah
- America/North_Dakota/Center
- America/North_Dakota/New_Salem
- America/Nuuk
- America/Ojinaga
- America/Panama
- America/Pangnirtung
- America/Paramaribo
- America/Phoenix
- America/Port-au-Prince
- America/Port_of_Spain
- America/Porto_Acre
- America/Porto_Velho
- America/Puerto_Rico
- America/Punta_Arenas
- America/Rainy_River
- America/Rankin_Inlet
- America/Recife
- America/Regina
- America/Resolute
- America/Rio_Branco
- America/Rosario
- America/Santa_Isabel
- America/Santarem
- America/Santiago
- America/Santo_Domingo
- America/Sao_Paulo
- America/Scoresbysund
- America/Shiprock
- America/Sitka
- America/St_Barthelemy
- America/St_Johns
- America/St_Kitts
- America/St_Lucia
- America/St_Thomas
- America/St_Vincent
- America/Swift_Current
- America/Tegucigalpa
- America/Thule
- America/Thunder_Bay
- America/Tijuana
- America/Toronto
- America/Tortola
- America/Vancouver
- America/Virgin
- America/Whitehorse
- America/Winnipeg
- America/Yakutat
- America/Yellowknife
- Antarctica/Casey
- Antarctica/Davis
- Antarctica/DumontDUrville
- Antarctica/Macquarie
- Antarctica/Mawson
- Antarctica/McMurdo
- Antarctica/Palmer
- Antarctica/Rothera
- Antarctica/South_Pole
- Antarctica/Syowa
- Antarctica/Troll
- Antarctica/Vostok
- Arctic/Longyearbyen
- Asia/Aden
- Asia/Almaty
- Asia/Amman
- Asia/Anadyr
- A
# --- truncated at 32 KB (78 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cubesoftware/refs/heads/main/openapi/cubesoftware-canvases-api-openapi.yml