REST API to access underlying Cube functionality — data tables, dimensions, formulas, Cube Data exports, connections, and company administration. Secured with OAuth 2.0 (authorization code + PKCE); most operations require an X-Company-ID header.
openapi: 3.0.3
info:
title: Cube API
version: 1.0.0 (1.0)
description: |
#### General Description
An API to access underlying Cube functionality. These endpoints are the same endpoints
that support Cube's universal add-ons and a plethora of integrations meaning you'll be able to interact with your
Cube 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)
for more usage guides on how you can use this API to integrate with Cube to accomplish various tasks!
#### Versioning
All requests to the API require a version to be configured via an `Accept` Header. The value of this Header should look like this:
```
Accept: application/json; version=1.0
```
Note that the version number may differ depending on which version of the endpoint is needed.
#### Response Structure
The general response structure of Cube's API endpoints will contain a `"data"` and `"metadata"` root level key:
```json
{
"data": { ... object data or list of objects ... },
"metadata": {
"status": 200,
"message": "Potential message with additional context",
"error": false,
"code": ""
}
}
```
#### Rate Limiting
All endpoints have a rate limit configured, most of them default to 5/s.
When the rate limit is encountered, a 429 HTTP code will be returned.
#### Error Handling
In the event an error occurs, the response will typically look like this:
```json
{
"data": {},
"metadata": {
"status": 400,
"message": "Some error message",
"error": true,
"code": "SOME_ERROR_CODE"
}
}
```
termsOfService: https://www.cubesoftware.com/terms-of-service
paths:
/action-items:
get:
operationId: action_items_list
description: |-
Retrieve a list of all action items created by the authenticated user within their company.
Items are returned ordered by position (ascending).
summary: List action items
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
tags:
- Taskflow
security:
- OAuth2: []
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ActionItem'
description: ''
'401':
description: Unauthorized - authentication credentials not provided or invalid
'403':
description: Forbidden - insufficient permissions
post:
operationId: action_items_create
description: |-
Create a new action item. The action item name must be unique within the company.
The position field is automatically set to the end of the list (count of existing items). Position is 0-indexed and maintains a continuous sequence with no gaps.
summary: Create an action item
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
tags:
- Taskflow
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ActionItem'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/ActionItem'
multipart/form-data:
schema:
$ref: '#/components/schemas/ActionItem'
required: true
security:
- OAuth2: []
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/ActionItem'
description: ''
'400':
description: Invalid input - action item name must be unique or exceeds
max length
'401':
description: Unauthorized - authentication credentials not provided or invalid
'403':
description: Forbidden - insufficient permissions
/action-items/{id}:
get:
operationId: action_items_retrieve
description: Retrieve details of a specific action item by ID. Users can only
retrieve action items they created.
summary: Retrieve an action item
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
- in: path
name: id
schema:
type: string
required: true
tags:
- Taskflow
security:
- OAuth2: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ActionItem'
description: ''
'401':
description: Unauthorized - authentication credentials not provided or invalid
'403':
description: Forbidden - insufficient permissions
'404':
description: Action item not found or not owned by user
patch:
operationId: action_items_partial_update
description: |-
Partially update an action item. Only include fields to be updated.
- Set "completed" to true to mark as completed, or false to mark as incomplete.
- Update "position" to reorder the item (0-indexed). Other items will automatically shift to maintain continuous sequence.
- Users can only update action items they created.
summary: Update an action item
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
- in: path
name: id
schema:
type: string
required: true
tags:
- Taskflow
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PatchedActionItem'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/PatchedActionItem'
multipart/form-data:
schema:
$ref: '#/components/schemas/PatchedActionItem'
security:
- OAuth2: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ActionItem'
description: ''
'400':
description: Invalid input - action item name must be unique, exceeds max
length, or position is invalid
'401':
description: Unauthorized - authentication credentials not provided or invalid
'403':
description: Forbidden - insufficient permissions
'404':
description: Action item not found or not owned by user
delete:
operationId: action_items_destroy
description: |-
Delete an action item by ID. Users can only delete action items they created.
When an item is deleted, all items with higher positions are automatically shifted down to close the gap and maintain a continuous sequence.
summary: Delete an action item
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
- in: path
name: id
schema:
type: string
required: true
tags:
- Taskflow
security:
- OAuth2: []
responses:
'204':
description: Action item successfully deleted
'401':
description: Unauthorized - authentication credentials not provided or invalid
'403':
description: Forbidden - insufficient permissions
'404':
description: Action item not found or not owned by user
/agents/categories:
get:
operationId: agents_categories_list
description: Returns agent categories with nested prompts.
summary: List agent categories.
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
tags:
- Agents
security:
- OAuth2: []
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/AgentCategory'
description: Agent categories with nested prompts.
/agents/categories/{slug}:
get:
operationId: agents_categories_retrieve
description: Returns a single agent category with nested prompts.
summary: Retrieve a single agent category by slug.
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
- in: path
name: slug
schema:
type: string
required: true
tags:
- Agents
security:
- OAuth2: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/AgentCategory'
description: A single agent category with nested prompts.
/agents/chat/messages:
get:
operationId: agents_chat_messages_retrieve
description: List chat messages for a specific session. Supports filtering by
session ID using the "session" query parameter.
summary: List Chat Messages
tags:
- ChatMessages
security:
- OAuth2: []
responses:
'200':
description: No response body
post:
operationId: agents_chat_messages_create
description: Create a new chat message in a session
summary: Create Chat Message
tags:
- ChatMessages
security:
- OAuth2: []
responses:
'201':
description: No response body
/agents/chat/messages/{id}:
get:
operationId: agents_chat_messages_retrieve_2
description: Retrieve a specific chat message by ID
summary: Retrieve Chat Message
parameters:
- in: path
name: id
schema:
type: string
required: true
tags:
- ChatMessages
security:
- OAuth2: []
responses:
'200':
description: No response body
/agents/chat/sessions:
get:
operationId: agents_chat_sessions_list
description: List chat sessions for the current user
summary: List Chat Sessions
parameters:
- in: query
name: data_table_id
schema:
type: string
description: When listing sessions with session_type=DATA_TABLE_MANAGEMENT,
filter to sessions scoped to this source data table UUID.
- in: query
name: limit
schema:
type: integer
description: 'Number of items per page (default: 50)'
- in: query
name: page
schema:
type: integer
description: 'Page number (default: 1)'
- in: query
name: session_type
schema:
type: string
description: 'Filter by session type (default: CHAT). One of: CHAT, PLANNER,
DATA_TABLE_MANAGEMENT, WIDGET_BUILDER'
tags:
- ChatSessions
security:
- OAuth2: []
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ChatSession'
description: ''
'400':
description: Invalid pagination parameters
'401':
description: Unauthorized
'403':
description: Permission denied
post:
operationId: agents_chat_sessions_create
description: Create a new chat session
summary: Create Chat Session
tags:
- ChatSessions
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ChatSession'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/ChatSession'
multipart/form-data:
schema:
$ref: '#/components/schemas/ChatSession'
security:
- OAuth2: []
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/ChatSession'
description: ''
/agents/chat/sessions/{id}:
get:
operationId: agents_chat_sessions_retrieve
description: Retrieve a specific chat session by ID
summary: Retrieve Chat Session
parameters:
- in: path
name: id
schema:
type: string
required: true
tags:
- ChatSessions
security:
- OAuth2: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ChatSession'
description: ''
/agents/credits/usage:
get:
operationId: agents_credits_usage_list
description: Returns paginated per-user credit usage for the current billing
period.
summary: List credit usage by user
parameters:
- name: limit
required: false
in: query
description: Number of results to return per page.
schema:
type: integer
- name: page
required: false
in: query
description: A page number within the paginated result set.
schema:
type: integer
tags:
- Agents
security:
- OAuth2: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedCreditUsageByUserList'
description: ''
/agents/credits/usage/{id}:
get:
operationId: agents_credits_usage_retrieve
description: Returns credit usage for a specific user company in the current
billing period.
summary: Get credit usage for a user
parameters:
- in: path
name: id
schema:
type: string
pattern: ^\d+$
required: true
tags:
- Agents
security:
- OAuth2: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CreditUsageByUser'
description: ''
/agents/credits/usage/me:
get:
operationId: agents_credits_usage_me_retrieve
description: Returns credit usage for the current user company for the billing
period.
summary: Own credit usage
tags:
- Agents
security:
- OAuth2: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CreditUsageByUser'
description: ''
/agents/credits/usage/summary:
get:
operationId: agents_credits_usage_summary_retrieve
description: Returns the current credit allocation and usage broken down by
Ask, Build, and MCP tiers.
summary: Credit usage summary
tags:
- Agents
security:
- OAuth2: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CreditUsageSummary'
description: ''
/agents/planner/plan-mode-sessions:
get:
operationId: agents_planner_plan_mode_sessions_list
description: Returns plan mode sessions for the current user company. Each row
includes the linked chat session id and the parent scenario dimension (DimensionSerializer
shape; plan-mode scenario dimensions do not include list-only formula rollup
fields).
summary: List Plan Mode Sessions
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
tags:
- PlanModeSessions
security:
- OAuth2: []
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PlanModeSessionList'
description: Plan mode sessions for the current user company
/agents/settings:
get:
operationId: agents_settings_retrieve
description: Default authenticated ViewSet with standard rate limit (DEFAULT_API_RATE_LIMIT).
tags:
- ChatSettings
security:
- OAuth2: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ChatSettings'
description: ''
put:
operationId: agents_settings_update
description: Default authenticated ViewSet with standard rate limit (DEFAULT_API_RATE_LIMIT).
tags:
- ChatSettings
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ChatSettings'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/ChatSettings'
multipart/form-data:
schema:
$ref: '#/components/schemas/ChatSettings'
security:
- OAuth2: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ChatSettings'
description: ''
patch:
operationId: agents_settings_partial_update
description: Default authenticated ViewSet with standard rate limit (DEFAULT_API_RATE_LIMIT).
tags:
- ChatSettings
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PatchedChatSettings'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/PatchedChatSettings'
multipart/form-data:
schema:
$ref: '#/components/schemas/PatchedChatSettings'
security:
- OAuth2: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ChatSettings'
description: ''
/agents/widget-builder:
post:
operationId: agents_widget_builder_create
description: Build a widget definition using AI based on a natural language
prompt. The widget is created in memory and returned without being saved to
the database. The prompt and agent response are saved as ChatMessages in the
specified session.
summary: Build Widget with AI
tags:
- Agents
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/WidgetBuilderRequest'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/WidgetBuilderRequest'
multipart/form-data:
schema:
$ref: '#/components/schemas/WidgetBuilderRequest'
required: true
security:
- OAuth2: []
responses:
'200':
content:
application/json:
schema:
type: object
properties:
widget:
type: object
description: The built widget definition (unsaved, id is null)
message:
type: object
description: The agent response ChatMessage
description: Successfully built widget
'400':
description: Bad Request - Invalid prompt or chat_session_id
'401':
description: Unauthorized
'403':
description: Forbidden - Chat session does not belong to user
/attributes:
get:
operationId: attributes_retrieve
description: "This endpoint retrieves all the attributes of a company. To filter\
\ attributes to a specific\n data table, use the table query parameter.\n\
\ "
summary: Get Company's Attributes
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
- in: query
name: table
schema:
type: string
description: The ID of an attribute table to limit results to
required: true
tags:
- Attributes
security:
- OAuth2: []
- {}
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/AttributeResponse'
examples:
FullExample:
value:
id: 1
name: Vendor
description: Name of vendor
table:
id: 156f1d7f-3364-42b4-bed5-d0d1e87327a1
name: My Data Table
settings: {}
created_at: '2021-03-09T19:21:20.656464+00:00'
created_at: '2021-03-09T19:21:20.766168+00:00'
summary: Full Example
description: ''
x-codeSamples:
- lang: curl
source: |-
curl -X \
GET \
-H 'Accept: application/json; version=1.0' \
-H 'Content-Type: application/json' \
-H 'X-Company-ID: <your-company-id>' \
'https://api.cubesoftware.com/attributes?table=156f1d7f-3364-42b4-bed5-d0d1e87327a1'
- lang: python
source: |-
import requests
headers = {
"Accept": "application/json; version=1.0",
"Content-Type": "application/json",
"X-Company-ID": "<your-company-id>"
}
url = 'https://api.cubesoftware.com/attributes?table=156f1d7f-3364-42b4-bed5-d0d1e87327a1'
response = requests.get(url, headers=headers)
print(response.json())
post:
operationId: attributes_create
description: "This endpoint creates and updates attributes for a given company.\
\ To create an attribute,\n don't include an ID in the payload. Including\
\ an ID implies updating an existing attribute.\n "
summary: Manage Company Attributes
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
tags:
- Attributes
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AttributeRequest'
examples:
FullExample:
value:
name: New Attribute
description: My new attribute
table_id: 156f1d7f-3364-42b4-bed5-d0d1e87327a1
summary: Full Example
description: "| **Parameter** | **Required** | **Description** |\n\
|---|---|---|\n| id | false | ID of existing attribute, for update\
\ |\n| name | true | The name of the attribute |\n| table_id | true\
\ | The data table for this attribute |\n| description | false |\
\ A brief description |\n "
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/AttributeRequest'
multipart/form-data:
schema:
$ref: '#/components/schemas/AttributeRequest'
required: true
security:
- OAuth2: []
- {}
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/AttributeResponse'
examples:
FullExample:
value:
id: 1
name: Vendor
description: Name of vendor
table:
id: 156f1d7f-3364-42b4-bed5-d0d1e87327a1
name: My Data Table
settings: {}
created_at: '2021-03-09T19:21:20.656464+00:00'
created_at: '2021-03-09T19:21:20.766168+00:00'
summary: Full Example
description: ''
x-codeSamples:
- lang: curl
source: |-
curl -X \
POST \
-H 'Accept: application/json; version=1.0' \
-H 'Content-Type: application/json' \
-H 'X-Company-ID: <your-company-id>' \
-d '{
"name": "New Attribute",
"description": "My new attribute",
"table_id": "156f1d7f-3364-42b4-bed5-d0d1e87327a1"
}' \
'https://api.cubesoftware.com/attributes'
- lang: python
source: |-
import requests
headers = {
"Accept": "application/json; version=1.0",
"Content-Type": "application/json",
"X-Company-ID": "<your-company-id>"
}
url = 'https://api.cubesoftware.com/attributes'
payload = {
"name": "New Attribute",
"description": "My new attribute",
"table_id": "156f1d7f-3364-42b4-bed5-d0d1e87327a1"
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
/auth/access_token:
post:
operationId: auth_access_token_create
description: Do not use this endpoint, use the standard OAuth 2.0 PKCE flow
instead
summary: Get an Access Token
tags:
- Authentication
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AuthTokenView'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/AuthTokenView'
multipart/form-data:
schema:
$ref: '#/components/schemas/AuthTokenView'
required: true
security:
- {}
deprecated: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/AuthTokenView'
description: ''
/auth/devices:
get:
operationId: auth_devices_list
description: Returns all confirmed multi-factor authentication devices for the
current user.
summary: List enabled MFA devices
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
tags:
- Auth
security:
- OAuth2: []
- {}
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/MfaDevice'
description: ''
/auth/embed-token:
post:
operationId: auth_embed_token_create
description: Creates a short-lived, single-use embed token for authenticating
embedded portal pages in iframes or headless browsers.
summary: Create an embed token
tags:
- Auth
security:
- OAuth2: []
- {}
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/EmbedTokenCreateResponse'
description: ''
/auth/embed-token/exchange:
post:
operationId: auth_embed_token_exchange_create
description: Exchanges a short-lived embed token for a standard OAuth2 access
token. Returns the same payload shape as the PKCE token endpoint.
summary: Exchange an embed token for an OAuth2 access token
tags:
- Auth
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EmbedTokenExchangeRequest'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/EmbedTokenExchangeRequest'
multipart/form-data:
schema:
$ref: '#/components/schemas/EmbedTokenExchangeRequest'
required: true
responses:
'200':
content:
application/json:
schema:
type: object
properties:
access_token:
type: string
token_type:
type: string
expires_in:
type: integer
scope:
type: string
company_id:
type: string
format: uuid
description: OAuth2 access token response
'401':
description: Invalid or expired embed token
/auth/permissions/{group_id}:
get:
operationId: auth_permissions_retrieve
description: Retrieves details for a given permissions group
summary: Retrieve a Permission Group
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
- in: path
name: group_id
schema:
type: integer
description: The ID of the permissions group
required: true
tags:
- Authentication
security:
- OAuth2: []
- {}
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/AuthGroupPermissions'
description: ''
/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 authenticate
# --- truncated at 32 KB (707 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cubesoftware/refs/heads/main/openapi/cubesoftware-openapi-original.yml