Cube Planning Data Tables API
Data Tables are a generic way to organize the source dimensions, mappings, uploads, and imports from an outside source into Cube (e.g. ERP connections, imported flat files, spreadsheet updates, employee rosters, etc).
Data Tables are a generic way to organize the source dimensions, mappings, uploads, and imports from an outside source into Cube (e.g. ERP connections, imported flat files, spreadsheet updates, employee rosters, etc).
openapi: 3.0.3
info:
title: Cube Agents Data Tables 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: Data Tables
description: "Data Tables are a generic way to organize the source dimensions, mappings, uploads,\n and imports from an outside source into Cube (e.g. ERP connections, imported flat files, spreadsheet\n updates, employee rosters, etc).\n "
paths:
/data-tables:
get:
operationId: list
description: "List all data tables for a company.\n\nData Tables are a generic way to organize the source dimensions, mappings, uploads, and imports\nfrom an outside source into Cube (source system connections, imported flat files and employee rosters, etc).\n \n "
summary: Retrieve Company Data Tables
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
tags:
- Data Tables
security:
- OAuth2: []
- {}
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/SourceDataTable'
description: The data table object
/data-tables/{data_table_id}:
get:
operationId: retrieve_3
description: "Retrieve a single data table for a company.\n\nData Tables are a generic way to organize the source dimensions, mappings, uploads, and imports\nfrom an outside source into Cube (source system connections, imported flat files and employee rosters, etc).\n \n "
summary: Retrieve a Data Table
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
- in: path
name: data_table_id
schema:
type: string
format: uuid
description: The ID of the data table
required: true
tags:
- Data Tables
security:
- OAuth2: []
- {}
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/SourceDataTable'
description: The data table object
post:
operationId: data_tables_create
description: "Allows updating a data table. This currently supports modifying\n settings for data tables tied to Salesforce connections and name, description fields for all data tables.\n "
summary: Update a Data Table
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
- in: path
name: data_table_id
schema:
type: string
format: uuid
required: true
tags:
- Data Tables
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SourceDataTable'
examples:
UpdateSOQLDataTableSetting:
value:
soql_query: SELECT Id, Name FROM Opportunity
name: Salesforce
summary: Update SOQL Data Table Setting
description: "| **Parameter** | **Default** | **Description** |\n|---|---|---|\n| name | none | The name to use for the data table |\n| settings | {} | A dictionary of table settings |\n "
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/SourceDataTable'
multipart/form-data:
schema:
$ref: '#/components/schemas/SourceDataTable'
required: true
security:
- OAuth2: []
- {}
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/SourceDataTable'
description: The data table object
patch:
operationId: data_tables_partial_update
description: This class exists to have a standard rate limit across all authenticated API endpoints
parameters:
- in: path
name: data_table_id
schema:
type: string
format: uuid
required: true
tags:
- Data Tables
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PatchedSourceDataTable'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/PatchedSourceDataTable'
multipart/form-data:
schema:
$ref: '#/components/schemas/PatchedSourceDataTable'
security:
- OAuth2: []
- {}
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/SourceDataTable'
description: ''
/data-tables/{data_table_id}/dimensions:
get:
operationId: data_tables_dimensions_retrieve
description: Lists all of the dimensions associated with a given data table
summary: Retrieve Data Table Dimensions
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
- in: path
name: data_table_id
schema:
type: string
format: uuid
required: true
- in: query
name: only_tlds
schema:
type: boolean
description: Whether to only return Top-Level Dimensions
- in: query
name: order_tree
schema:
type: boolean
description: Whether the dimension tree needs to be ordered
- in: query
name: tld_id
schema:
type: integer
description: The ID of the Top-Level Dimension restricting this request
tags:
- Data Tables
security:
- OAuth2: []
- {}
responses:
'200':
description: The listing of dimensions in tree form
post:
operationId: data_tables_dimensions_create
description: Creates and modifies dimensions tied to a data table
summary: Update Data Table Dimensions
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
- in: path
name: data_table_id
schema:
type: string
format: uuid
required: true
- in: query
name: flat
schema:
type: boolean
default: false
description: Whether or not the POSTed body contains a nested or flat dimensional structure
examples:
ListOfDimensionsAsAFlatArrayWith"parentId"KeysSpecified:
value: 'true'
summary: List of dimensions as a flat array with "parent_id" keys specified
ListOfDimensionsWithA"children"KeyWithChildrenDimensions:
value: 'false'
summary: List of dimensions with a "children" key with children dimensions
- in: query
name: full_list
schema:
type: boolean
default: true
description: Whether or not the full list is provided, if set to True any dimensions not in this list will be marked as disabled
examples:
ReplaceAllDimensions:
value: 'true'
summary: Replace all dimensions
UpdateExistingDimensions/AddNewDimensions:
value: 'false'
summary: Update existing dimensions / add new dimensions
- in: query
name: tld_name
schema:
type: string
description: A TLD name to associate all the provided dimensions with
examples:
UpdateCustomerDimensions:
value: Customer
summary: Update Customer dimensions
tags:
- Data Tables
requestBody:
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/SourceDimensionTree'
examples:
DimensionsWithFlat=True:
value:
- - name: Account
id: 1
parent_id: null
- name: Income
id: 2
parent_id: 1
- name: Expense
id: 3
parent_id: 1
- name: Assets
rollup_type: BALANCE
id: 6
parent_id: 1
- name: Department
id: 4
parent_id: null
- name: Engineering
id: 5
parent_id: 4
summary: Dimensions with flat=True
description: "| **Parameter** | **Type** | **Required** | **Description** |\n|---|---|---|--|\n| name | string | True | The name to use for the dimension\n| children | list | False | A list of child dimensions, defaults to empty\n| id | string | False | This dimension's unique ID from the source system (i.e. third party ID)\n| parent_id | string | False | The ID of this dimension's parent, only use when `flat=true`\n| number | string | False | Account number\n| active | bool | True | Whether this dimension is enabled or not\n| description | string | False | A brief description of the dimension\n| rollup_type | string | None | The rollup type for this dimension\n "
DimensionsWithFlat=False:
value:
- - name: Account
id: 1
children:
- name: Income
id: 2
- name: Expense
id: 3
- name: Assets
rollup_type: BALANCE
id: 6
- name: Department
id: 4
children:
- name: Engineering
id: 5
summary: Dimensions with flat=False
description: "| **Parameter** | **Type** | **Required** | **Description** |\n|---|---|---|--|\n| name | string | True | The name to use for the dimension\n| children | list | False | A list of child dimensions, defaults to empty\n| id | string | False | This dimension's unique ID from the source system (i.e. third party ID)\n| parent_id | string | False | The ID of this dimension's parent, only use when `flat=true`\n| number | string | False | Account number\n| active | bool | True | Whether this dimension is enabled or not\n| description | string | False | A brief description of the dimension\n| rollup_type | string | None | The rollup type for this dimension\n "
application/x-www-form-urlencoded:
schema:
type: array
items:
$ref: '#/components/schemas/SourceDimensionTree'
multipart/form-data:
schema:
type: array
items:
$ref: '#/components/schemas/SourceDimensionTree'
required: true
security:
- OAuth2: []
- {}
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/SourceDimensionTree'
description: ''
/data-tables/{data_table_id}/dimensions/mappings/rules:
get:
operationId: data_tables_dimensions_mappings_rules_list
description: Lists all of the auto mapping rules from a data table.
summary: Retrieve AutoMappingRules for a Data Table
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
- in: path
name: data_table_id
schema:
type: string
format: uuid
description: The ID of the data table the auto-mapping rules belong to
required: true
tags:
- Data Tables
security:
- OAuth2: []
- {}
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/AutoMappingRule'
description: ''
post:
operationId: data_tables_dimensions_mappings_rules_create
description: Create and modify auto mapping rules for a data table.
summary: Create and Modify AutoMappingRules for a Data Table
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
- in: path
name: data_table_id
schema:
type: string
format: uuid
description: The ID of the data table the auto-mapping rules belong to
required: true
tags:
- Data Tables
requestBody:
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/AutoMappingDoc'
application/x-www-form-urlencoded:
schema:
type: array
items:
$ref: '#/components/schemas/AutoMappingDoc'
multipart/form-data:
schema:
type: array
items:
$ref: '#/components/schemas/AutoMappingDoc'
required: true
security:
- OAuth2: []
- {}
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/AutoMappingRule'
description: ''
/data-tables/{data_table_id}/mappings:
get:
operationId: data_tables_mappings_retrieve
description: "Lists all of the dimension mappings from a data table's dimensions to a\ncompany's dimensions in Cube. These mappings are used when running an import against source data.\n "
summary: Retrieve Mappings for a Data Table
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
- in: path
name: data_table_id
schema:
type: string
format: uuid
description: The ID of the data table the mappings are for
required: true
- in: query
name: source_tld_id
schema:
type: integer
description: The ID of the Top-Level Source Dimension restricting this request
tags:
- Data Tables
security:
- OAuth2: []
- {}
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/DimensionMappingNested'
description: The mappings for the data table
post:
operationId: data_tables_mappings_create
description: "Lists all of the dimension mappings from a data table's dimensions to a\ncompany's dimensions in Cube. These mappings are used when running an import against source data.\n "
summary: Update Mappings for a Data Table
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
- in: path
name: data_table_id
schema:
type: string
format: uuid
description: The ID of the data table the mappings are for
required: true
tags:
- Data Tables
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DimensionMappingNested'
examples:
UpdateMappingsUsingDimensionIDs:
value:
- dimension_id: 1
source_dimension_id: 100
summary: Update mappings using dimension IDs
UpdateMappingsUsingDimensionPaths:
value:
- dimension_path: Account:Income Statement:Expenses:Travel and Entertainment
source_dimension_path: Account:Expenses:Flights
summary: Update mappings using dimension paths
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/DimensionMappingNested'
multipart/form-data:
schema:
$ref: '#/components/schemas/DimensionMappingNested'
required: true
security:
- OAuth2: []
- {}
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/DimensionMapping'
description: "The results from updating the mappings for the data table. Mapping updates are\n handled in a partial manner meaning successful mapping changes will be updated accordingly and failed ones\n will report back why they failed. Furthermore, altered vs deleted mappings will also be shown in the response.\n\n Mappings can either be done in realtime or backgrounded depending on how much data needs to be moved for the mapping update.\n\n `errors` - A list of error strings for any mappings that failed.\n\n `altered` - A list of any mappings that were altered with this update.\n\n `code` - Will be `MAPPING_BACKGROUNDED` or `MAPPING_COMPLETED` depending on if the update is being handled via a background worker task.\n "
/data-tables/{data_table_id}/schedule-import:
post:
operationId: data_tables_schedule_import_create
description: Schedule and Update a data table import. A single endpoint that either creates a scheduled data import if one doesn’t already exist, OR updates an existing scheduled data import.
summary: Schedule and Update a Data Table Import
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
- in: path
name: data_table_id
schema:
type: string
format: uuid
required: true
tags:
- Data Tables
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ScheduleDataTableImportRequest'
examples:
ScheduleAnImport:
value:
start_time_dimension_id: 1
end_time_dimension_id: 2
day_of_week: MONDAY
hour_of_day: 23
schedule_cadence: WEEKLY
tld_default_dimensions:
Account: 7
Department: 12
summary: Schedule an Import
description: "| **Parameter** | **Type** | **Description** |\n |---|---|--|\n | start_time_dimension_id | int | The start time dimension ID |\n | end_time_dimension_id | int | The end time dimension ID |\n | day_of_week | string | The day of the week (UTC). Accepted Values: SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY |\n | hour_of_day | int | The hour of the day (UTC) for scheduling. Value must be 0-23. |\n | schedule_cadence | string | The cadence for scheduling. This can either be WEEKLY or DAILY |\n | tld_default_dimensions | dictionary | The TLD to default dimension ID mapping (i.e. {'Account': 7, 'Department': 12, 'Custom TLD': 18})\n "
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/ScheduleDataTableImportRequest'
multipart/form-data:
schema:
$ref: '#/components/schemas/ScheduleDataTableImportRequest'
required: true
security:
- OAuth2: []
- {}
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ScheduledSourceDataTableImports'
description: ''
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ScheduledSourceDataTableImports'
examples:
ScheduleCadenceFailedValidation:
value:
data: {}
metadata:
status: 400
error: true
message: 'Field "schedule_cadence" must be a string and be one of the following values: WEEKLY,DAILY'
code: FIELD_VALIDATION_ERROR
summary: Schedule Cadence Failed Validation
DayOfWeekFailedValidation:
value:
data: {}
metadata:
status: 400
error: true
message: 'Field "day_of_week" must be a string and be one of the following values: SUNDAY,MONDAY,TUESDAY,WEDNESDAY,THURSDAY,FRIDAY,SATURDAY'
code: FIELD_VALIDATION_ERROR
summary: Day of Week Failed Validation
HourOfDayFailedValidation:
value:
data: {}
metadata:
status: 400
error: true
message: 'Field "hour_of_day" must be a integer and be one of the following values: 0-23'
code: FIELD_VALIDATION_ERROR
summary: Hour of Day Failed Validation
ScheduledImportAlreadyExistsForTimePeriod:
value:
data: {}
metadata:
status: 400
error: true
message: '"Other Data Table" is already scheduled this hour of the day, please make a different selection.'
code: SCHEDULED_IMPORT_EXISTS
summary: Scheduled Import already exists for time period
SpecificFieldRequired:
value:
data: {}
metadata:
status: 400
error: true
message: Field "day_of_week" is required.
code: FIELD_REQUIRED_ERROR
summary: Specific field required
description: ''
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/ScheduledSourceDataTableImports'
examples:
DataTableDoesNotExist:
value:
data: {}
metadata:
status: 404
error: true
message: Data table with ID 907731d1-f5e0-44b3-8753-8423da86ca2b does not exist.
code: DATA_TABLE_DOES_NOT_EXIST
summary: Data Table does not exist
description: ''
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ScheduledSourceDataTableImports'
examples:
UserIsNotAtLeastAFinanceUser:
value:
data: {}
metadata:
status: 403
error: true
message: Permission denied
code: PERMISSION_DENIED
summary: User is not at least a finance user
description: ''
delete:
operationId: data_tables_schedule_import_destroy
description: Deletes an import schedule for a given data table
summary: Delete the Schedule for a Data Table Import
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
- in: path
name: data_table_id
schema:
type: string
format: uuid
required: true
tags:
- Data Tables
security:
- OAuth2: []
- {}
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ScheduledSourceDataTableImports'
description: ''
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ScheduledSourceDataTableImports'
description: ''
/data-tables/scheduled-imports:
get:
operationId: data_tables_scheduled_imports_retrieve
description: List all scheduled data table imports for a company. The response can also be filtered by data_table_id.
summary: Retrieve Scheduled Data Table Imports
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
- in: query
name: data_table_id
schema:
type: string
format: uuid
description: Filter imports related to a specific data table
tags:
- Data Tables
security:
- OAuth2: []
- {}
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ScheduledSourceDataTableImports'
description: ''
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ScheduledSourceDataTableImports'
description: ''
components:
schemas:
Integration:
type: object
properties:
id:
type: integer
readOnly: true
source:
$ref: '#/components/schemas/IntegrationSourceEnum'
category:
$ref: '#/components/schemas/CategoryEnum'
name:
type: string
maxLength: 100
logo_url:
type: string
nullable: true
readOnly: true
required:
- category
- id
- logo_url
- name
- source
Type95aEnum:
enum:
- BASIC
- FORMULA
- TAG
type: string
description: '* `BASIC` - Basic
* `FORMULA` - Formula
* `TAG` - Tag'
DimensionMapping:
type: object
properties:
dimension_id:
type: integer
nullable: true
readOnly: true
source_dimension_id:
type: integer
readOnly: true
automapped:
type: boolean
created_at:
type: string
format: date-time
readOnly: true
modified_at:
type: string
format: date-time
readOnly: true
required:
- created_at
- dimension_id
- modified_at
- source_dimension_id
AutoMappingRule:
type: object
properties:
id:
type: integer
readOnly: true
data_table_id:
type: string
format: uuid
tld_id:
type: integer
minimum: 1
rule:
$ref: '#/components/schemas/RuleEnum'
dimension_id:
type: integer
minimum: 1
nullable: true
required:
- data_table_id
- id
- rule
- tld_id
AutoMappingDoc:
type: object
properties:
tld_id:
type: integer
minimum: 1
rule:
$ref: '#/components/schemas/RuleEnum'
dimension_id:
type: integer
minimum: 1
nullable: true
required:
- rule
- tld_id
ScheduledSourceDataTableImports:
type: object
properties:
schedule_cadence:
$ref: '#/components/schemas/ScheduleCadenceEnum'
day_of_week:
nullable: true
oneOf:
- $ref: '#/components/schemas/DayOfWeekEnum'
- $ref: '#/components/schemas/NullEnum'
hour_of_day:
type: integer
maximum: 23
minimum: 0
source_data_table:
allOf:
- $ref: '#/components/schemas/SourceDataTable'
readOnly: true
start_time_dimension:
type: integer
nullable: true
end_time_dimension:
type: integer
nullable: true
num_prior_time:
type: integer
maximum: 2147483647
minimum: 0
nullable: true
prior_time_unit:
nullable: true
oneOf:
- $ref: '#/components/schemas/PriorTimeUnitEnum'
- $ref: '#/components/schemas/BlankEnum'
- $ref: '#/components/schemas/NullEnum'
tld_default_dimensions:
type: object
additionalProperties:
type: integer
readOnly: true
created_at:
type: string
format: date-time
readOnly: true
created_by:
type: integer
modified_at:
type: string
format: date-time
readOnly: true
modified_by:
type: integer
nullable: true
required:
- created_at
- created_by
- hour_of_day
- modified_at
- source_data_table
- tld_default_dimensions
Dimension:
type: object
properties:
id:
type: integer
readOnly: true
parent_id:
type: integer
nullable: true
readOnly: true
name:
type: string
maxLength: 255
active:
type: boolean
readOnly: true
status:
$ref: '#/components/schemas/Status2c8Enum'
type:
$ref: '#/components/schemas/Type95aEnum'
rollup_type:
nullable: true
oneOf:
- $ref: '#/components/schemas/RollupTypeEnum'
- $ref: '#/components/schemas/BlankEnum'
- $ref: '#/components/schemas/NullEnum'
formula:
type: string
readOnly: true
write_protection:
$ref: '#/components/schemas/WriteProtectionEnum'
position:
type: integer
maximum: 9223372036854775807
minimum: -9223372036854775808
format: int64
special_case_id:
type: string
nullable: true
maxLength: 100
date:
# --- truncated at 32 KB (87 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cube-planning/refs/heads/main/openapi/cube-planning-data-tables-api-openapi.yml