> ## Documentation Index > Fetch the complete documentation index at: https://docs.upsolve.ai/llms.txt > Use this file to discover all available pages before exploring further. # List Canvas Versions > List saved canvas versions ## OpenAPI ````yaml get /v2/api/projects/{projectId}/workspaces/{workspaceId}/canvases/{canvasId}/versions openapi: 3.1.0 info: title: Upsolve API version: 1.5.0 servers: - url: https://api.upsolve.ai security: [] tags: [] paths: /v2/api/projects/{projectId}/workspaces/{workspaceId}/canvases/{canvasId}/versions: get: summary: List saved canvas versions description: List saved canvas versions operationId: GetV2ApiProjectsProjectIdWorkspacesWorkspaceIdCanvasesCanvasIdVersions parameters: - name: apiKey in: query required: false description: >- Upsolve API key, generated under Account → Developer settings in the Upsolve Hub. Keys are user-scoped: pass organizationId alongside the key to select which org to act on. schema: description: >- Upsolve API key, generated under Account → Developer settings in the Upsolve Hub. Keys are user-scoped: pass organizationId alongside the key to select which org to act on. type: string minLength: 1 - name: organizationId in: query required: false description: >- The ID of the organization. Required when using Supabase JWT authentication. schema: type: string description: >- The ID of the organization. Required when using Supabase JWT authentication. - name: connectionId in: query required: false description: The ID of the connection a guest has access to schema: type: string description: The ID of the connection a guest has access to - name: projectId in: path required: true description: The project in the URL. The caller's project user is read from it. schema: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$ description: The project in the URL. The caller's project user is read from it. - name: workspaceId in: path required: true description: >- GET /v2/api/projects/:projectId/workspaces/:workspaceId/canvases/:canvasId/versions Parameter schema: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$ - name: canvasId in: path required: true description: >- GET /v2/api/projects/:projectId/workspaces/:workspaceId/canvases/:canvasId/versions Parameter schema: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$ responses: '200': description: >- GET /v2/api/projects/:projectId/workspaces/:workspaceId/canvases/:canvasId/versions Positive response content: application/json: schema: type: object properties: status: type: string const: success data: type: object properties: versions: type: array items: type: object properties: id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$ canvas_id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$ version: type: integer minimum: -9007199254740991 maximum: 9007199254740991 display_mode: type: string enum: - live - snapshot created_by: type: - string - 'null' created_at: {} design_file: description: >- The canvas's design file as it was when this version was saved, or null. type: - string - 'null' items: type: array items: type: object properties: id: type: string favorite_id: type: string x: type: integer minimum: -9007199254740991 maximum: 9007199254740991 'y': type: integer minimum: -9007199254740991 maximum: 9007199254740991 w: type: integer minimum: -9007199254740991 maximum: 9007199254740991 h: type: integer minimum: -9007199254740991 maximum: 9007199254740991 favorite: type: - object - 'null' properties: id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$ organization_id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$ created_by_project_user_id: type: - string - 'null' format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$ type: type: string enum: - sql - chart - tool name: type: string thread_id: type: - string - 'null' chart_config: type: - object - 'null' propertyNames: type: string additionalProperties: {} chart: type: object properties: v: type: number const: 3 required: - v additionalProperties: {} description: >- The chart as v3 (query, shape, render): its stored v3 chart, or its chartsV2 config converted connection_id: type: - string - 'null' format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$ thumbnail_url: type: - string - 'null' sql: type: - string - 'null' snapshot_data: type: - array - 'null' items: type: object propertyNames: type: string additionalProperties: {} is_archived: type: boolean copied_from_favorite_id: description: >- For a canvas tile's own chart: the saved favorite it was copied from, if any type: - string - 'null' format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$ tool_call: description: >- For a tool tile (type tool): the API connector operation it calls (connectorKind, connectorId, toolName, pinnedArgs) type: - object - 'null' properties: connectorKind: type: string enum: - mcp - api toolName: type: string required: - connectorKind - toolName additionalProperties: {} row_transform: description: >- For a tool tile: the BODY of the JavaScript function `transform(payload)` that turns the API's response into the tile's rows (a complete `function transform(payload) { ... }` is accepted too) type: - string - 'null' row_columns: description: >- For a tool tile: the columns its transform returns type: - array - 'null' items: type: object properties: name: type: string type: type: string required: - name - type additionalProperties: {} created_at: {} updated_at: {} workspace_id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$ required: - id - organization_id - created_by_project_user_id - type - name - thread_id - chart_config - chart - connection_id - thumbnail_url - sql - snapshot_data - is_archived - created_at - updated_at - workspace_id additionalProperties: false required: - id - favorite_id - x - 'y' - w - h additionalProperties: false filters: type: - array - 'null' items: type: object properties: id: type: string filter_config: allOf: - oneOf: - type: object properties: filterType: type: string const: Input filterSubType: type: string enum: - Input Equals - Input Starts with - Input Ends with - Input Contains description: Subtype of the input filter. filterRestrictions: type: 'null' description: >- No specific restrictions for the input filter. displayName: type: string description: User-driven display name for the filter. controlKey: description: >- User-driven key to identify the filter when controlled externally. type: string layout: type: object properties: i: type: string description: >- Component key or uses the index of components if not provided. x: type: number description: X position in grid units. 'y': type: number description: Y position in grid units. w: type: number description: Width in grid units. h: type: number description: Height in grid units. minW: description: Minimum width in grid units. type: number maxW: description: Maximum width in grid units. type: number minH: description: Minimum height in grid units. type: number maxH: description: Maximum height in grid units. type: number moved: description: Set by DragEvents and ResizeEvents. type: boolean static: description: >- If true, equal to `isDraggable: false` and `isResizable: false`. type: boolean isDraggable: description: >- If false, will not be draggable. Overrides `static`. type: boolean isResizable: description: >- If false, will not be resizable. Overrides `static`. type: boolean resizeHandles: description: Array of resize handles. type: array items: type: string enum: - s - w - e - 'n' - sw - nw - se - ne isBounded: description: >- If true and draggable, item will be moved only within the grid. type: boolean required: - i - x - 'y' - w - h additionalProperties: false description: >- User-driven layout configuration for the filter. required: - filterType - filterSubType - filterRestrictions - displayName - layout additionalProperties: false - type: object properties: filterType: type: string const: Select filterSubType: type: string enum: - Select Single - Select Multi description: Subtype of the select filter. filterRestrictions: description: Allowed values for the select filter. type: - object - 'null' properties: values: type: array items: type: string description: An array of allowed string values. required: - values additionalProperties: false filterRestrictionMethod: description: >- Method to compute the restrictions for this Select filter. Defaults to {filterType: 'Scan'} to scan the column it is pointing at oneOf: - type: object properties: filterType: type: string const: Manual options: type: array items: type: string description: >- User provided options for this select filter required: - filterType - options additionalProperties: false - type: object properties: filterType: type: string const: Query query: type: string description: >- Query to run to populate this select filter required: - filterType - query additionalProperties: false - type: object properties: filterType: type: string const: Scan required: - filterType additionalProperties: false discriminator: propertyName: filterType defaultValue: description: The default value for the filter. type: string displayName: type: string description: User-driven display name for the filter. controlKey: description: >- User-driven key to identify the filter when controlled externally. type: string layout: type: object properties: i: type: string description: >- Component key or uses the index of components if not provided. x: type: number description: X position in grid units. 'y': type: number description: Y position in grid units. w: type: number description: Width in grid units. h: type: number description: Height in grid units. minW: description: Minimum width in grid units. type: number maxW: description: Maximum width in grid units. type: number minH: description: Minimum height in grid units. type: number maxH: description: Maximum height in grid units. type: number moved: description: Set by DragEvents and ResizeEvents. type: boolean static: description: >- If true, equal to `isDraggable: false` and `isResizable: false`. type: boolean isDraggable: description: >- If false, will not be draggable. Overrides `static`. type: boolean isResizable: description: >- If false, will not be resizable. Overrides `static`. type: boolean resizeHandles: description: Array of resize handles. type: array items: type: string enum: - s - w - e - 'n' - sw - nw - se - ne isBounded: description: >- If true and draggable, item will be moved only within the grid. type: boolean required: - i - x - 'y' - w - h additionalProperties: false description: >- User-driven layout configuration for the filter. required: - filterType - filterSubType - displayName - layout additionalProperties: false - type: object properties: filterType: type: string const: Number filterSubType: type: string enum: - Number Greater than - Number Greater than or equal to - Number Less than - Number Less than or equal to - Number Equal to description: Subtype of the number filter. filterRestrictions: description: >- Allowed numeric range for the number filter. type: - object - 'null' properties: min: type: number description: The minimum allowed number. max: type: number description: The maximum allowed number. required: - min - max additionalProperties: false displayName: type: string description: User-driven display name for the filter. controlKey: description: >- User-driven key to identify the filter when controlled externally. type: string layout: type: object properties: i: type: string description: >- Component key or uses the index of components if not provided. x: type: number description: X position in grid units. 'y': type: number description: Y position in grid units. w: type: number description: Width in grid units. h: type: number description: Height in grid units. minW: description: Minimum width in grid units. type: number maxW: description: Maximum width in grid units. type: number minH: description: Minimum height in grid units. type: number maxH: description: Maximum height in grid units. type: number moved: description: Set by DragEvents and ResizeEvents. type: boolean static: description: >- If true, equal to `isDraggable: false` and `isResizable: false`. type: boolean isDraggable: description: >- If false, will not be draggable. Overrides `static`. type: boolean isResizable: description: >- If false, will not be resizable. Overrides `static`. type: boolean resizeHandles: description: Array of resize handles. type: array items: type: string enum: - s - w - e - 'n' - sw - nw - se - ne isBounded: description: >- If true and draggable, item will be moved only within the grid. type: boolean required: - i - x - 'y' - w - h additionalProperties: false description: >- User-driven layout configuration for the filter. required: - filterType - filterSubType - displayName - layout additionalProperties: false - type: object properties: filterType: type: string const: Date filterSubType: type: string enum: - Date Single - Date Range - Date Range (No Timestamp) - Date After - Date Before description: Subtype of the date filter. filterRestrictions: description: Allowed date range for the date filter. type: - object - 'null' properties: min: type: string description: The minimum allowed date. max: type: string description: The maximum allowed date. required: - min - max additionalProperties: false displayName: type: string description: User-driven display name for the filter. controlKey: description: >- User-driven key to identify the filter when controlled externally. type: string layout: type: object properties: i: type: string description: >- Component key or uses the index of components if not provided. x: type: number description: X position in grid units. 'y': type: number description: Y position in grid units. w: type: number description: Width in grid units. h: type: number description: Height in grid units. minW: description: Minimum width in grid units. type: number maxW: description: Maximum width in grid units. type: number minH: description: Minimum height in grid units. type: number maxH: description: Maximum height in grid units. type: number moved: description: Set by DragEvents and ResizeEvents. type: boolean static: description: >- If true, equal to `isDraggable: false` and `isResizable: false`. type: boolean isDraggable: description: >- If false, will not be draggable. Overrides `static`. type: boolean isResizable: description: >- If false, will not be resizable. Overrides `static`. type: boolean resizeHandles: description: Array of resize handles. type: array items: type: string enum: - s - w - e - 'n' - sw - nw - se - ne isBounded: description: >- If true and draggable, item will be moved only within the grid. type: boolean required: - i - x - 'y' - w - h additionalProperties: false description: >- User-driven layout configuration for the filter. required: - filterType - filterSubType - displayName - layout additionalProperties: false - type: object properties: filterType: type: string const: Toggle filterSubType: type: 'null' description: >- No specific subtype for the toggle filter. filterRestrictions: type: 'null' description: >- No specific restrictions for the toggle filter. displayName: type: string description: User-driven display name for the filter. controlKey: description: >- User-driven key to identify the filter when controlled externally. type: string layout: type: object properties: i: type: string description: >- Component key or uses the index of components if not provided. x: type: number description: X position in grid units. 'y': type: number description: Y position in grid units. w: type: number description: Width in grid units. h: type: number description: Height in grid units. minW: description: Minimum width in grid units. type: number maxW: description: Maximum width in grid units. type: number minH: description: Minimum height in grid units. type: number maxH: description: Maximum height in grid units. type: number moved: description: Set by DragEvents and ResizeEvents. type: boolean static: description: >- If true, equal to `isDraggable: false` and `isResizable: false`. type: boolean isDraggable: description: >- If false, will not be draggable. Overrides `static`. type: boolean isResizable: description: >- If false, will not be resizable. Overrides `static`. type: boolean resizeHandles: description: Array of resize handles. type: array items: type: string enum: - s - w - e - 'n' - sw - nw - se - ne isBounded: description: >- If true and draggable, item will be moved only within the grid. type: boolean required: - i - x - 'y' - w - h additionalProperties: false description: >- User-driven layout configuration for the filter. required: - filterType - filterSubType - filterRestrictions - displayName - layout additionalProperties: false discriminator: propertyName: filterType - type: object properties: globalFilterColumns: description: Array of targeted filter configurations. type: array items: type: string description: Global column name to filter on filterTargets: type: array items: allOf: - oneOf: - type: object properties: type: type: string const: Before logic columns: type: array items: type: object properties: type: type: string enum: - string - number - boolean - date - mixed - json description: The data type of the column. columnName: type: string description: The name of the column. columnMetadata: description: >- The description of the column used for AI. type: string columnSummary: description: >- An object that summarizes the data in the column. Is only ever provided if dataIsVisibleToAi is set to true. type: object properties: values: type: array items: {} description: >- An array of example values summarizing the contents of the column isExhaustive: type: boolean description: >- This is set to true if the values array is an exhaustive summary of the available values in the column. If it's set to false it represents just some examples. required: - values - isExhaustive additionalProperties: false required: - type - columnName additionalProperties: false description: >- List of simple columns for 'Before logic'. targetTable: description: Name of the target table. type: string chartId: type: string description: Identifier of the target chart. required: - type - columns - chartId additionalProperties: false - type: object properties: type: type: string const: After logic columns: type: array items: type: object properties: type: type: string enum: - string - number - boolean - date - mixed - json description: The data type of the column. columnName: type: string description: The name of the column. columnMetadata: description: >- The description of the column used for AI. type: string columnSummary: description: >- An object that summarizes the data in the column. Is only ever provided if dataIsVisibleToAi is set to true. type: object properties: values: type: array items: {} description: >- An array of example values summarizing the contents of the column isExhaustive: type: boolean description: >- This is set to true if the values array is an exhaustive summary of the available values in the column. If it's set to false it represents just some examples. required: - values - isExhaustive additionalProperties: false required: - type - columnName additionalProperties: false description: >- List of simple columns for 'After logic'. targetTable: type: 'null' description: >- No target table needed for filters after logic. chartId: type: string description: Identifier of the target chart. required: - type - columns - targetTable - chartId additionalProperties: false discriminator: propertyName: type - type: object properties: targetColumn: description: >- User-driven target column for the filter. type: string additionalProperties: false description: Array of targeted filter configurations. selectedValue: anyOf: - anyOf: - type: string - type: number - {} - type: boolean - type: 'null' - type: array items: anyOf: - type: string - type: number - {} - type: boolean - type: 'null' description: >- An array is used when multiple values are selected, as with the date range filter, or with a multi-select filter. required: - filterTargets additionalProperties: false - type: object properties: fieldKey: description: >- The catalog field this filter was created from. type: string fieldRef: description: >- On a filter whose fieldKey is not a `col:` key: the one table column ('raw') or tile result column ('output') it filters. Ignore it on a `col:` key. type: object properties: kind: type: string enum: - raw - output table: type: - string - 'null' column: type: string columnType: type: string enum: - string - number - date - boolean description: >- The column's data type, which decides the filter types it accepts. required: - kind - table - column additionalProperties: false itemIds: description: >- Tiles the filter is restricted to, when it was restricted. type: array items: type: string fieldKeys: description: >- On a filter made from a custom filter: its columns, in order. Each tile filters on the first that applies there. With filtersEveryTable, tables picked under one name, each tile filtered on every one it reads. type: array items: type: string tileColumns: description: >- On a filter made from a custom filter: the tiles given columns of their own, each filtered on every one of them. type: object propertyNames: type: string additionalProperties: type: array items: type: string customFilterId: description: >- The custom filter this filter was made from. Its columns, tiles and name follow that custom filter. type: string filtersEveryTable: description: >- True on a filter over tables picked under one column name (`fieldKeys`): each tile is filtered on every one of them it reads, or not at all. type: boolean additionalProperties: false sort_order: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - id - filter_config - sort_order additionalProperties: false required: - id - canvas_id - version - display_mode - created_by - created_at - items additionalProperties: false description: >- The canvas's saved versions, oldest first. Empty for someone who reads the canvas through the workspace while a version is promoted: they are shown that version and cannot switch. promotedVersion: type: - integer - 'null' minimum: -9007199254740991 maximum: 9007199254740991 unsavedChanges: type: boolean description: >- Whether the canvas has changed since its latest saved version (its tiles, their places, its design file, filters or time zone). Always false for someone who reads a promoted version. required: - versions - promotedVersion - unsavedChanges additionalProperties: false required: - status - data additionalProperties: false '400': description: >- GET /v2/api/projects/:projectId/workspaces/:workspaceId/canvases/:canvasId/versions Negative response content: application/json: schema: type: object properties: status: type: string const: error error: type: object properties: message: type: string code: type: string details: type: object propertyNames: type: string additionalProperties: {} required: - message additionalProperties: false required: - status - error additionalProperties: false security: - APIKEY_3: [] components: securitySchemes: APIKEY_3: type: apiKey in: header name: authorization ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.