Cube 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).
OpenAPI Specification
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: Production API 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 c4cf3e59-9b4c-4cbf-b627-2feaf9fa7ddf 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:
RollupTypeEnum:
enum:
- SUM
- AVERAGE
- BALANCE
- BEGINNING_BALANCE
type: string
description: '* `SUM` - Sum
* `AVERAGE` - Average
* `BALANCE` - Ending Balance
* `BEGINNING_BALANCE` - Beginning Balance'
IntegrationSourceEnum:
enum:
- METABASE
- QUICKBOOKS
- XERO
- NETSUITE
- SALESFORCE
- SAGE_INTACCT
- RILLET
- CAMPFIRE
- CHARTHOP
- GOOGLE
- OKTA
- BOOMI
- SAML
- OPEN_EXCHANGE_RATES
- NETSUITE_RATES
- MERGE
type: string
description: '* `METABASE` - Metabase
* `QUICKBOOKS` - QuickBooks
* `XERO` - Xero
* `NETSUITE` - NetSuite
* `SALESFORCE` - Salesforce
* `SAGE_INTACCT` - Sage Intacct
* `RILLET` - Rillet
* `CAMPFIRE` - Campfire
* `CHARTHOP` - ChartHop
* `GOOGLE` - Google SSO
* `OKTA` - Okta (OIDC)
* `BOOMI` - Boomi
* `SAML` - SAML
* `OPEN_EXCHANGE_RATES` - Open Exchange Rates
* `NETSUITE_RATES` - NetSuite Saved Search
* `MERGE` - Cube Universal Connect'
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
NullEnum:
enum:
- null
ScheduleCadenceEnum:
enum:
- WEEKLY
- DAILY
type: string
description: '* `WEEKLY` - Weekly
* `DAILY` - Daily'
ScheduleDataTableImportRequest:
type: object
properties:
day_of_week:
type: string
hour_of_day:
type: integer
schedule_cadence:
type: string
start_time_dimension_id:
type: integer
end_time_dimension_id:
type: integer
tld_default_dimensions:
type: object
additionalProperties: {}
required:
- day_of_week
- end_time_dimension_id
- hour_of_day
- schedule_cadence
- start_time_dimension_id
- tld_default_dimensions
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
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/Ati
# --- truncated at 32 KB (87 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cubesoftware/refs/heads/main/openapi/cubesoftware-data-tables-api-openapi.yml