Dimensions store the organizational hierarchy for a company and outline how their data is structured. All companies have top level dimensions called Account, Scenario, Department, and Time. They also can have additional custom top level dimensions (i.e. Product, Entity).
openapi: 3.0.3
info:
title: Cube Agents Dimensions 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: Dimensions
description: "Dimensions store the organizational hierarchy for a company and outline how their data is\n structured. All companies have top level dimensions called Account, Scenario, Department, and Time. They also\n can have additional custom top level dimensions (i.e. Product, Entity).\n "
paths:
/dimensions:
get:
operationId: DimensionList
description: This endpoint lists all dimensions accessible to the user in a flat list.
summary: Get All Dimensions
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
- in: query
name: can_be_mapped
schema:
type: boolean
description: Limit to dimensions that can be mapped to source systems.
- in: query
name: inactive
schema:
type: boolean
description: Include inactive dimensions.
- in: query
name: include_tags
schema:
type: boolean
description: Include TAG-type dimensions.
- in: query
name: tld_id
schema:
type: integer
description: Limit to dimensions under this top-level dimension.
tags:
- Dimensions
security:
- OAuth2: []
- {}
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/DimensionList'
description: The list of dimensions
post:
operationId: DimensionCreate
description: This endpoint creates a dimension.
summary: Create a Dimension
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
- in: query
name: can_be_mapped
schema:
type: boolean
description: Limit to dimensions that can be mapped to source systems.
- in: query
name: inactive
schema:
type: boolean
description: Include inactive dimensions.
- in: query
name: include_tags
schema:
type: boolean
description: Include TAG-type dimensions.
- in: query
name: tld_id
schema:
type: integer
description: Limit to dimensions under this top-level dimension.
tags:
- Dimensions
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DimensionListApiDocAttributes_2'
examples:
CreateADimensionAndSpecifyParentDimensionViaID:
value:
name: My Dimension
parent_id: 11
write_protection: NONE
summary: Create a dimension and specify parent dimension via ID
CreateADimensionAndSpecifyParentDimensionViaName:
value:
name: My Dimension
parent_name: My Parent Dimension
write_protection: NONE
summary: Create a dimension and specify parent dimension via name
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/DimensionListApiDocAttributes_2'
multipart/form-data:
schema:
$ref: '#/components/schemas/DimensionListApiDocAttributes_2'
required: true
security:
- OAuth2: []
- {}
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/DimensionList'
description: The list of dimensions
/dimensions/{dimension_id}:
get:
operationId: DimensionRetrieve
description: Get a single dimension by it's ID
summary: Get Dimension by ID
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
- in: path
name: dimension_id
schema:
type: integer
description: The ID of the dimension
required: true
examples:
ExampleDimensionID:
value: 1
summary: Example Dimension ID
tags:
- Dimensions
security:
- OAuth2: []
- {}
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Dimension'
description: The requested dimension
post:
operationId: DimensionUpdate
description: "Update individual fields of a dimension model.\n NOTE: A dimension can NOT be enabled and disabled via this endpoint. Instead see the Dimension Status endpoint.\n "
summary: Update Dimension By ID
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
- in: path
name: dimension_id
schema:
type: integer
description: The ID of the dimension
required: true
examples:
ExampleDimensionID:
value: 1
summary: Example Dimension ID
tags:
- Dimensions
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Dimension'
examples:
CreateDimensionExample:
value:
parent_id: 11
name: '2026'
active: true
status: ENABLED
type: BASIC
rollup_type: null
formula: null
write_protection: NONE
position: 2026
special_case_id: null
date: '2026-07-19'
has_children: true
write_block_reason: Dimension with name "2026" is a parent dimension and cannot be written to
metadata: null
summary: Create Dimension Example
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/Dimension'
multipart/form-data:
schema:
$ref: '#/components/schemas/Dimension'
required: true
security:
- OAuth2: []
- {}
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Dimension'
description: The requested dimension
/dimensions/{dimension_id}/duplicate:
post:
operationId: dimensions_duplicate_create
description: This endpoint duplicates a dimension. Note that this is only possible for Scenario Dimensions.
summary: Duplicate a Dimension
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
- in: path
name: dimension_id
schema:
type: integer
description: The ID of the dimension
required: true
examples:
ExampleDimensionID:
value: 1
summary: Example Dimension ID
tags:
- Dimensions
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DimensionDuplicateApiDocAttributes_1'
examples:
DuplicateDimensionExample:
value:
name: New Duplicated Dimension Name
summary: Duplicate Dimension Example
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/DimensionDuplicateApiDocAttributes_1'
multipart/form-data:
schema:
$ref: '#/components/schemas/DimensionDuplicateApiDocAttributes_1'
required: true
security:
- OAuth2: []
- {}
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/duplicate_message_serializer_message_serializer'
description: Message
/dimensions/{dimension_id}/mappings:
get:
operationId: dimensions_mappings_retrieve_2
description: Get the mappings for a given dimension ID to data tables
summary: Get Dimension Mappings for Source Data Tables
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
- in: path
name: dimension_id
schema:
type: integer
description: The ID of the dimension
required: true
examples:
ExampleDimensionID:
value: 1
summary: Example Dimension ID
tags:
- Dimensions
security:
- OAuth2: []
- {}
responses:
'200':
description: Dimension Mappings
/dimensions/{dimension_id}/options:
get:
operationId: dimensions_options_retrieve
description: "List the options for acceptable changes to a given dimension, such as possible parents, write\n protection options, and rollup type options. For new dimensions, passing 0 as the ID gets default options.\n "
summary: Get Dimension Options
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
- in: path
name: dimension_id
schema:
type: integer
description: The ID of the dimension
required: true
examples:
ExampleDimensionID:
value: 1
summary: Example Dimension ID
tags:
- Dimensions
security:
- OAuth2: []
- {}
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/dimension_options_serializer'
description: Dimension Options
/dimensions/{dimension_id}/status:
post:
operationId: dimensions_status_create
description: You can use this endpoint to disable or re-enable a dimension
summary: Enable or Disable a Dimension
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
- in: path
name: dimension_id
schema:
type: integer
description: The ID of the dimension
required: true
examples:
ExampleDimensionID:
value: 1
summary: Example Dimension ID
tags:
- Dimensions
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DimensionStatusApiDocAttributes_1'
examples:
EnableADimension:
value:
disable: false
summary: Enable a Dimension
DisableADimension:
value:
disable: true
summary: Disable a Dimension
DimensionExample:
value:
id: 1
parent_id: 11
name: '2026'
active: true
status: ENABLED
type: BASIC
rollup_type: null
formula: null
write_protection: NONE
position: 2026
special_case_id: null
date: '2026-07-19'
has_children: true
write_block_reason: Dimension with name "2026" is a parent dimension and cannot be written to
metadata: null
summary: Dimension Example
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/DimensionStatusApiDocAttributes_1'
multipart/form-data:
schema:
$ref: '#/components/schemas/DimensionStatusApiDocAttributes_1'
required: true
security:
- OAuth2: []
- {}
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Dimension'
examples:
DimensionExample:
value:
id: 1
parent_id: 11
name: '2026'
active: true
status: ENABLED
type: BASIC
rollup_type: null
formula: null
write_protection: NONE
position: 2026
special_case_id: null
date: '2026-07-19'
has_children: true
write_block_reason: Dimension with name "2026" is a parent dimension and cannot be written to
metadata: null
summary: Dimension Example
description: The modified dimension
/dimensions/bulk:
post:
operationId: dimensions_bulk_create
description: This endpoint bulk updates dimensions.
summary: Bulk Update Dimensions
tags:
- Dimensions
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BulkDimensionUpdateRequest'
examples:
BulkUpdateRequest:
value:
batch_id: batch_12345
tld_id: 1
summary: Bulk Update Request
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/BulkDimensionUpdateRequest'
multipart/form-data:
schema:
$ref: '#/components/schemas/BulkDimensionUpdateRequest'
required: true
security:
- OAuth2: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Dimension'
examples:
SuccessResponse:
value:
data:
message: Bulk update request accepted and queued for processing
metadata:
status: 200
error: false
message: null
code: ''
summary: Success Response
ValidationError:
value:
data: {}
metadata:
status: 400
error: true
message: Invalid top-level dimension ID
code: VALIDATION_ERROR
summary: Validation Error
PermissionDenied:
value:
data: {}
metadata:
status: 403
error: true
message: User not allowed to modify dimensions under this top-level dimension
code: PERMISSION_DENIED
summary: Permission Denied
description: Bulk update request accepted and queued for processing
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/error_response_serializer'
description: Invalid request - validation error
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/error_response_serializer'
description: Permission denied - user not allowed to modify dimensions under this TLD
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/error_response_serializer'
description: Top-level dimension not found
/dimensions/deepest:
get:
operationId: dimensions_deepest_retrieve
description: This endpoint retrieves all the deepest level dimensions
summary: Get Deepest Dimensions
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
tags:
- Dimensions
security:
- OAuth2: []
- {}
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Dimension'
description: The Dimension
/dimensions/download:
get:
operationId: dimensions_download_list
description: Download an Excel file containing dimension data for the specified TLD IDs.
summary: Download Dimensions Excel File
parameters:
- in: query
name: enable_reparenting
schema:
type: string
description: Whether to enable reparenting functionality
- in: query
name: for_upload
schema:
type: string
description: Whether to include the updated name column for upload
- in: query
name: tld_ids
schema:
type: string
description: Comma-separated list of TLD IDs to include in the export
required: true
tags:
- Dimensions
security:
- OAuth2: []
responses:
'200':
description: Excel file download
'400':
description: Invalid TLD IDs provided
'403':
description: Permission denied
/dimensions/mappings:
get:
operationId: dimensions_mappings_retrieve
description: Get the mappings for all dimensions to data tables
summary: Get all Dimension Mappings for Source Data Tables
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
tags:
- Dimensions
security:
- OAuth2: []
- {}
responses:
'200':
description: Dimension Mappings
/dimensions/merge:
get:
operationId: dimensions_merge_retrieve
description: "List previous merge scenarios. You can filter this list by destination dimension ID and/or\n merge request status\n "
summary: List previous merge scenarios
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
- in: query
name: destination_dimension
schema:
type: integer
description: The dimension ID of the destination dimension to filter on.
- in: query
name: limit
schema:
type: integer
default: 50
description: The limit for the paginated response.
- in: query
name: offset
schema:
type: integer
default: 0
description: The number of results to skip from 0.
- in: query
name: status
schema:
type: string
enum:
- ''
- BACKLOG
- FAILED
- IN_PROGRESS
- SUCCESS
default: ''
description: The status of the merge request you'd like to filter by
tags:
- Dimensions
security:
- OAuth2: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/data'
description: The merge scenario was triggered and a message was sent in the metadata.
post:
operationId: dimensions_merge_create
description: "Create a request to merge data from one or more source Scenario dimensions in to a destination\n Scenario. This can be limited by time periods based on Time dimensions. If successful, a background worker\n will start to move the data and the caller will be emailed with the results.\n "
summary: Merge one or more Scenario to a destination Scenario based on Time dimensions
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
tags:
- Dimensions
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/MergeScenarioApi'
examples:
MergeDataFromASingleScenarioWithAGivenTimeFrameIntoASingleDestinationScenario:
value:
to_scenario_request:
to_scenario_dimension_id: 1
from_scenario_requests:
- from_dimension_id: 9
start_time_dimension_id: 33
end_time_dimension_id: 34
summary: Merge data from a single Scenario with a given time frame into a single destination Scenario
description: "| **Parameter** | **Description** |\n|---|---|\n| to_scenario_dimension_id | The Dimension ID of the Scenario Dimension that we will be merging data into |\n| from_scenario_requests | A list of scenario dimensions and Time dimensions to retrieve data from |\n| from_dimension_id | The Dimension ID of a Scenario to get data from |\n| start_time_dimension_id | The Dimension ID of the starting Time dimension |\n| end_time_dimension_id | The Dimension ID of the ending Time dimension |\n "
MergeDataFromMultipleScenariosWithGivenTimeFramesIntoASingleDestinationScenario:
value:
to_scenario_request:
to_scenario_dimension_id: 1
from_scenario_requests:
- from_dimension_id: 9
start_time_dimension_id: 33
end_time_dimension_id: 34
- from_dimension_id: 10
start_time_dimension_id: 34
end_time_dimension_id: 35
summary: Merge data from multiple Scenarios with given time frames into a single destination Scenario
description: "| **Parameter** | **Description** |\n|---|---|\n| to_scenario_dimension_id | The Dimension ID of the Scenario Dimension that we will be merging data into |\n| from_scenario_requests | A list of scenario dimensions and Time dimensions to retrieve data from |\n| from_dimension_id | The Dimension ID of a Scenario to get data from |\n| start_time_dimension_id | The Dimension ID of the starting Time dimension |\n| end_time_dimension_id | The Dimension ID of the ending Time dimension |\n "
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/MergeScenarioApi'
multipart/form-data:
schema:
$ref: '#/components/schemas/MergeScenarioApi'
required: true
security:
- OAuth2: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/data'
description: The merge scenario was triggered and a message was sent in the metadata.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/data'
description: The merge scenario was not triggered and an error message is included in the metadata.
/dimensions/order:
post:
operationId: dimensions_order_create
description: Re-orders dimensions when showing in a list.
summary: Reorder Dimensions
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
tags:
- Dimensions
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DimensionOrderApiDocAttributes_1'
examples:
Place"BalanceSheet"(268)AheadOf"IncomeStatement"(267):
value:
order:
- 268
- 267
summary: Place "Balance Sheet" (268) ahead of "Income Statement" (267)
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/DimensionOrderApiDocAttributes_1'
multipart/form-data:
schema:
$ref: '#/components/schemas/DimensionOrderApiDocAttributes_1'
required: true
security:
- OAuth2: []
- {}
responses:
'200':
description: Hierarchy of dimensions in new order
/dimensions/scenarios/forecast:
post:
operationId: dimensions_scenarios_forecast_create
description: Generate a time series forecast of a Scenario
summary: Generate a time series forecast of a Scenario
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
tags:
- Dimensions
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/MetadataMessage'
examples:
GenerateAForecast:
value:
from_scenario:
dimension_id: 10
start_time_dimension_id: 12
end_time_dimension_id: 24
to_scenario:
dimension_id: 11
start_time_dimension_id: 30
end_time_dimension_id: 42
summary: Generate a forecast
description: "| **Parameter** | **Description** |\n|---|---|\n| from_scenario.dimension_id | The ID of the Scenario dimension to base the forecasted data off of |\n| from_scenario.start_time_dimension_id | The ID of the start Time dimension period to use for the source data |\n| from_scenario.end_time_dimension_id | The ID of the end Time dimension period to use for the source data |\n| to_scenario.dimension_id | The ID of the Scenario dimension the forecasted data is written to |\n "
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/MetadataMessage'
multipart/form-data:
schema:
$ref: '#/components/schemas/MetadataMessage'
required: true
security:
- OAuth2: []
- {}
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/MetadataMessage'
description: Acknowledgement of the request (generation of the forecast will be backgrounded)
/dimensions/time:
post:
operationId: dimensions_time_create
description: "This endpoint creates dimensions for an entire year. Alternatively, it can create a\n \"Cube Opening Balance\" dimension\n "
summary: Create Time Dimensions
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
tags:
- Dimensions
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DimensionTimeApiDocAttributes_1'
examples:
CreateDimensionsForOneOrMoreYears:
value:
years:
- 2022
- 2023
summary: Create dimensions for one or more years
Create"CubeOpeningBalance"Dimension:
value:
years:
- Cube Opening Balance
summary: Create "Cube Opening Balance" dimension
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/DimensionTimeApiDocAttributes_1'
multipart/form-data:
schema:
$ref: '#/components/schemas/DimensionTimeApiDocAttributes_1'
required: true
security:
- OAuth2: []
- {}
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Dimension'
description: The dimension(s) that were created
/dimensions/time/translate:
post:
operationId: dimensions_time_translate_create
description: Translates relative date phrases (like "Last Month", "Last 3 Months") to their corresponding time dimension names and IDs based on the context (row, column, or filter). For row/column context, multi-period phrases expand to individual dimensions. For filter context, multi-period phrases return a single aggregated dimension.
summary: Translate Relative Dates
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
tags:
- Dimensions
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TimeTranslateRequest'
examples:
TimeTranslateRequest:
value:
translations:
- phrase: Last Month
context: row
- phrase: Last 3 Months
context: filter
- phrase: Last 3 Months
context: row
- phrase: Last 2 Quarters
context: filter
- phrase: Last 2 Years
context: row
summary: Time Translate Request
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/TimeTranslateRequest'
multipart/form-data:
schema:
$ref: '#/components/schemas/TimeTranslateRequest'
required: true
security:
- OAuth2: []
- {}
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/TimeTranslateResponse'
examples:
Ti
# --- truncated at 32 KB (52 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cube-planning/refs/heads/main/openapi/cube-planning-dimensions-api-openapi.yml