Cube Planning Connections API
Connections to external source systems allow Cube to automatically import source dimensions and transaction data.
OpenAPI Specification
openapi: 3.0.3
info:
title: Cube Agents Connections 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: Connections
description: "Connections to external source systems allow Cube to automatically import source\n dimensions and transaction data.\n "
paths:
/connection/{connection_id}/deactivate:
post:
operationId: connection_deactivate_create
description: Mark the connection as inactive. This will remove this connection from the UI. No data tied to this connection will be affected.
summary: Deactivate a connection
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
- in: path
name: connection_id
schema:
type: string
format: uuid
required: true
tags:
- Connections
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Connection'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/Connection'
multipart/form-data:
schema:
$ref: '#/components/schemas/Connection'
required: true
security:
- OAuth2: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Connection'
description: ''
'400':
description: Bad Request - Failed to disconnect from external provider
'401':
description: Unauthorized
'403':
description: Forbidden - User does not have permission to modify this connection.
'404':
description: Connection not found
/connection/{connection_id}/import/settings:
get:
operationId: connection_import_settings_retrieve
description: "Get the default settings and required information for starting an import for a given connection.\n "
summary: Get Import Settings for Connection
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
- in: path
name: connection_id
schema:
type: string
format: uuid
description: The ID of a connection
required: true
examples:
ConnectionRequest:
value: bba75209-bd2b-4d82-9fde-dc38a16ae9d7
summary: Connection Request
tags:
- Connections
security:
- OAuth2: []
- {}
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectionImportSettingsResponse'
description: ''
/connection/{connection_id}/resync:
post:
operationId: connection_resync_create
description: "Use this endpoint to resync dimensions from a source connection.\n "
summary: Resync a Connection
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
- in: path
name: connection_id
schema:
type: string
format: uuid
description: The ID of a connection
required: true
examples:
ConnectionRequest:
value: bba75209-bd2b-4d82-9fde-dc38a16ae9d7
summary: Connection Request
- in: query
name: end_time_dimension_id
schema:
type: integer
description: Optional time dimension ID for the end of the date range to sync (for supported Integrations).
examples:
EndTimeDimensionID:
value: 2
summary: End Time Dimension ID
- in: query
name: start_time_dimension_id
schema:
type: integer
description: Optional time dimension ID for the beginning of the date range to sync (for supported Integrations).
examples:
StartTimeDimensionID:
value: 1
summary: Start Time Dimension ID
tags:
- Connections
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ResyncRequest'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/ResyncRequest'
multipart/form-data:
schema:
$ref: '#/components/schemas/ResyncRequest'
security:
- OAuth2: []
- {}
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ResyncResponse'
description: ''
/connection/{connection_id}/salesforce/soql:
get:
operationId: connection_salesforce_soql_retrieve
description: "Make a query against Salesforce and return the results\n "
summary: Salesforce SOQL
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
- in: path
name: connection_id
schema:
type: string
format: uuid
description: The ID of a connection
required: true
examples:
ConnectionRequest:
value: bba75209-bd2b-4d82-9fde-dc38a16ae9d7
summary: Connection Request
- in: query
name: options_only
schema:
type: boolean
description: "Whether the request is for field options (for mapping dimensions)\n or for all the data in tabular format"
- in: query
name: query
schema:
type: string
description: The Salesforce SoQL to execute
required: true
tags:
- Connections
security:
- OAuth2: []
- {}
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/SalesforceSoQLResponse'
description: ''
/connection/{connection_id}/source-file-storage:
get:
operationId: connection_source_file_storage_retrieve
description: This endpoint retrieves all managed source files and folders for a connection
summary: Get Source Files
parameters:
- in: path
name: connection_id
schema:
type: string
format: uuid
description: The UUID of the ERP connection.
required: true
tags:
- Connections
security:
- OAuth2: []
- {}
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/FileNode'
examples:
SampleFileList:
value:
- - id: '001'
name: root
type: folder
size: 0
modified_at: null
relative_path: ''
parent_id: null
- id: '002'
name: file1.txt
type: file
size: 1024
modified_at: '2026-07-19T00:15:26.979270Z'
relative_path: file1.txt
parent_id: '001'
- id: '003'
name: folder 1
type: folder
size: 0
modified_at: null
relative_path: ''
parent_id: '001'
- id: '004'
name: file2.txt
type: file
size: 2048
modified_at: '2026-07-19T00:15:26.979320Z'
relative_path: folder 1/file2.txt
parent_id: '003'
summary: Sample File List
description: List of source files and folders
'404':
description: Connection does not exist
patch:
operationId: connection_source_file_storage_partial_update
description: This endpoint edits a source file in a connection
summary: Edit Source File
parameters:
- in: path
name: connection_id
schema:
type: string
format: uuid
description: The UUID of the ERP connection.
required: true
tags:
- Connections
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PatchedEditFile'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/PatchedEditFile'
multipart/form-data:
schema:
$ref: '#/components/schemas/PatchedEditFile'
security:
- OAuth2: []
- {}
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/FileNode'
examples:
SuccessResponse:
value:
id: '002'
name: new-file-name.txt
type: file
size: 1024
modified_at: '2026-07-19T00:15:26.980030Z'
relative_path: new-folder/new-file-name.txt
parent_id: '001'
summary: Success Response
description: File edited successfully
'400':
description: Invalid input
'404':
description: File or connection does not exist
/connection/{connection_id}/source-file-storage/delete:
post:
operationId: connection_source_file_storage_delete_create
description: This endpoint deletes a batch of source files for a connection
summary: Delete Batch of Source Files
parameters:
- in: path
name: connection_id
schema:
type: string
format: uuid
description: The UUID of the ERP connection.
required: true
tags:
- Connections
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteBatch'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/DeleteBatch'
multipart/form-data:
schema:
$ref: '#/components/schemas/DeleteBatch'
required: true
security:
- OAuth2: []
- {}
responses:
'200':
description: Files deleted successfully
'400':
description: Invalid input
'404':
description: Connection does not exist
/connection/{connection_id}/source-file-storage/download:
post:
operationId: connection_source_file_storage_download_create
description: This endpoint generates a download URL for a source file in a connection
summary: Generate Download URL for Source File
parameters:
- in: path
name: connection_id
schema:
type: string
format: uuid
description: The UUID of the ERP connection.
required: true
tags:
- Connections
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DownloadFile'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/DownloadFile'
multipart/form-data:
schema:
$ref: '#/components/schemas/DownloadFile'
required: true
security:
- OAuth2: []
- {}
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/SourceFileDownload'
examples:
SuccessResponse:
value:
download_url: https://example.com/signed-url
summary: Success Response
description: Download URL generated successfully
'400':
description: Invalid input
'404':
description: Connection does not exist
/connection/{connection_id}/source-file-storage/upload-urls:
post:
operationId: connection_source_file_storage_upload_urls_create
description: This endpoint generates upload URLs for source files in a connection
summary: Generate Upload URLs for Source Files
parameters:
- in: path
name: connection_id
schema:
type: string
format: uuid
description: The UUID of the ERP connection.
required: true
tags:
- Connections
requestBody:
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/FileUploadRequest'
application/x-www-form-urlencoded:
schema:
type: array
items:
$ref: '#/components/schemas/FileUploadRequest'
multipart/form-data:
schema:
type: array
items:
$ref: '#/components/schemas/FileUploadRequest'
required: true
security:
- OAuth2: []
- {}
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/SourceFileUpload'
examples:
SuccessResponse:
value:
upload_urls:
- https://example.com/signed-url-1
- https://example.com/signed-url-2
summary: Success Response
description: Upload URLs generated successfully
'400':
description: Invalid input
'404':
description: Connection does not exist
/connections:
get:
operationId: retrieve
description: Get all connections for a company
summary: Get all Connections
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
tags:
- Connections
security:
- OAuth2: []
- {}
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Connection'
description: ''
/connections/{connection_id}:
get:
operationId: retrieve_2
description: Get a single connection
summary: Get a Connection
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
- in: path
name: connection_id
schema:
type: string
format: uuid
description: The ID of a connection
required: true
examples:
ConnectionRequest:
summary: Connection Request
tags:
- Connections
security:
- OAuth2: []
- {}
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Connection'
description: ''
/connections/{connection_id}/imports:
post:
operationId: ImportDataCreate
description: This endpoint will start a data import with the given connection. The request requires a connection ID and dimension IDs necessary to start an import.
summary: Start a Data Import
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
- in: path
name: connection_id
schema:
type: string
format: uuid
required: true
tags:
- Connections
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ImportDataRequest'
examples:
QueueADataImportForTheSpecifiedConnectionWithTheFollowingValues:
value:
dimensions:
other:
- 6
- 12
time:
start: 31
end: 44
scenario: 8
summary: Queue a data import for the specified connection with the following values
description: "| **Parameter** | **Type** | **Description** |\n|---|---|---|\n| dimensions | dictionary | Wrapper for dimensions data |\n| other | list of integers | Within the dimensions object, a list of cube dimension ids to use for unmapped source dimensions |\n| time | dictionary | Within the dimensions object, a dictionary representing the date range of the import |\n| start | integer | Within the time object, the id of the start time dimension |\n| end | integer | Within the time object, the id of the end time dimension |\n| scenario | integer | Within the dimensions object, the id of the scenario dimension |\n "
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/ImportDataRequest'
multipart/form-data:
schema:
$ref: '#/components/schemas/ImportDataRequest'
required: true
security:
- OAuth2: []
- {}
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Import'
description: The import was queued and a message was sent in the metadata.
/connections/{connection_id}/imports/{import_id}:
put:
operationId: ImportDataCancel
description: Cancel an active data import by providing the import ID and connection ID. This action immediately stops the import process and sends a cancellation email to the user who initiated the import. Accessible only to Finance and Admin users.
summary: Cancel a Data Import
parameters:
- in: header
name: HTTP_ACCEPT
schema:
type: string
default: application/json; version=1.1
description: Set the version of API the request is for
required: true
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
- in: path
name: connection_id
schema:
type: string
format: uuid
required: true
- in: path
name: import_id
schema:
type: integer
required: true
tags:
- Connections
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ImportUpdateApiDocAttributes_1'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/ImportUpdateApiDocAttributes_1'
multipart/form-data:
schema:
$ref: '#/components/schemas/ImportUpdateApiDocAttributes_1'
required: true
security:
- OAuth2: []
- {}
deprecated: true
responses:
'200':
content:
application/json; version=1.0:
schema:
$ref: '#/components/schemas/Import'
description: Attempt to cancel an active import.
'403':
content:
application/json; version=1.0:
schema:
$ref: '#/components/schemas/Import'
description: User is not at least a finance user.
'400':
content:
application/json; version=1.0:
schema:
$ref: '#/components/schemas/Import'
description: Indicates a race condition has occurred and the cancellation failed.
/imports:
get:
operationId: ImportGetList
description: "List all of a company's source data imports ordered by most recent to least.\n Optionally filtered by a data table id."
summary: Get Import History
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:
- Connections
security:
- OAuth2: []
- {}
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Import'
description: The import history list
components:
schemas:
OlapCubeChange:
type: object
properties:
id:
type: integer
readOnly: true
message:
type: string
nullable: true
maxLength: 1024
created_at:
type: string
format: date-time
readOnly: true
metadata:
nullable: true
type:
$ref: '#/components/schemas/OlapCubeChangeTypeEnum'
friendly_type:
type: string
readOnly: true
created_by:
$ref: '#/components/schemas/User'
user:
allOf:
- $ref: '#/components/schemas/User'
readOnly: true
num_changes:
type: integer
maximum: 4294967295
minimum: 0
format: int64
nullable: true
url:
type: string
readOnly: true
status:
$ref: '#/components/schemas/OlapCubeChangeStatusEnum'
batch_id:
type: string
readOnly: true
nullable: true
required:
- batch_id
- created_at
- created_by
- friendly_type
- id
- url
- user
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'
ImportUpdateApiDocAttributes_1:
type: object
properties:
status:
$ref: '#/components/schemas/Status6a6Enum'
status_message:
type: string
required:
- status
Status6a6Enum:
enum:
- CANCELLED
type: string
description: '* `CANCELLED` - Cancelled'
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:
type: string
format: date
nullable: true
has_children:
type: boolean
write_block_reason:
type: string
description: "If the dimension cannot be written to, return the reason why. Otherwise, return nothing.\n\nArgs:\n obj: The model object to be checked if can be written to.\n\nReturns:\n str (Optional): The error blocking the dimension from being written to, if one exists"
readOnly: true
metadata:
type: string
nullable: true
required:
- active
- formula
- id
- name
- parent_id
- write_block_reason
Connection:
type: object
properties:
id:
type: string
format: uuid
readOnly: true
active:
type: boolean
readOnly: true
type:
type: string
nullable: true
description: "Return the category of the associated Integration model for backwards compatibility\n\nReturns:\n The integration category (See Integration.CATEGORIES)"
readOnly: true
friendly_source:
type: string
readOnly: true
integration:
allOf:
- $ref: '#/components/schemas/Integration'
readOnly: true
settings:
type: object
additionalProperties: {}
metadata:
type: object
additionalProperties: {}
readOnly: true
required:
- active
- friendly_source
- id
- integration
- metadata
- settings
- type
SourceFileUpload:
type: object
properties:
upload_urls:
type: array
items:
type: string
format: uri
required:
- upload_urls
Import:
type: object
properties:
id:
type: integer
readOnly: true
created_at:
type: string
format: date-time
readOnly: true
completed_at:
type: string
format: date-time
nullable: true
user:
$ref: '#/components/schemas/User'
status:
$ref: '#/components/schemas/Status6a6Enum'
scenario_dimension:
$ref: '#/components/schemas/Dimension'
start_time_dimension:
$ref: '#/components/schemas/Dimension'
end_time_dimension:
$ref: '#/components/schemas/Dimension'
data_table:
$ref: '#/components/schemas/SourceDataTable'
status_message:
type: string
nullable: true
olap_cube_change:
$ref: '#/components/schemas/OlapCubeChange'
source_import_type:
allOf:
- $ref: '#/components/schemas/SourceImportTypeEnum'
readOnly: true
required:
- created_at
- data_table
- end_time_dimension
- id
- olap_cube_change
- scenario_dimension
- source_import_type
- start_time_dimension
- status
- user
ResyncResponse:
type: object
properties:
num_unmapped:
type: integer
audit_log_event_id:
type: string
format: uuid
auth_redirect_url:
type: string
format: uri
required:
- audit_log_event_id
- auth_redirect_url
- num_unmapped
Transaction:
type: object
properties:
num_transactions:
type: integer
file_imports:
$ref: '#/components/schemas/FileImports'
required:
- file_imports
- num_transactions
DownloadFile:
type: object
properties:
relative_path:
type: string
required:
- relative_path
SourceDataTable:
type: object
properties:
id:
type: string
format: uuid
readOnly: true
name:
type: string
maxLength: 255
active:
type: boolean
readOnly: true
settings:
type: object
additionalProperties: {}
created_at:
type: string
format: date-time
readOnly: true
connection:
allOf:
- $ref: '#/components/schemas/Connection'
readOnly: true
type:
allOf:
- $ref: '#/components/schemas/SourceDataTableTypeEnum'
readOnly: true
type_friendly:
type: string
readOnly: true
last_import:
type: object
additionalProperties: {}
readOnly: true
last_successful_import:
type: object
additionalProperties: {}
readOnly: true
source_type:
type: string
description: "Returns the human-friendly category of the connection's Integration, if the table has\na connection. Otherwise, returns 'Data Table'.\n\nReturns:\n The human-friendly source category"
readOnly: true
mapping_data:
type: object
additionalProperties: {}
readOnly: true
description:
type: string
required:
- active
- connection
- created_at
- id
- last_import
- last_successful_import
- mapping_data
- name
- settings
- source_type
- type
- type_friendly
SalesforceSoQLResponse:
type: object
properties:
response:
type: array
items: {}
option_response:
type: array
items: {}
required:
- option_response
- response
ResyncRequest:
type: object
properties:
start_time_dimension_id:
type: integer
minimum: 1
description: The time dimension ID for the beginning of the date range to sync (for supported Integrations).
end_time_dimension_id:
type: integer
minimum: 1
description: The time dimension ID for the end of the date range to sync (for supported Integrations).
ConnectionImportSettingsResponse:
type: object
properties:
block_reason:
type: string
tlds_needed:
type: object
additionalProperties: {}
scenarios:
type: object
additionalProperti
# --- truncated at 32 KB (79 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cube-planning/refs/heads/main/openapi/cube-planning-connections-api-openapi.yml