Cube Library API
The Library API from Cube — 12 operation(s) for library.
OpenAPI Specification
openapi: 3.0.3
info:
title: Cube Agents Library 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: Library
paths:
/folders:
get:
operationId: folders_list
description: List folders for the requesting company in the given namespace. Supports drill-in via `?parent_id=`.
summary: List folders
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
- in: query
name: namespace
schema:
type: string
enum:
- LIBRARY
description: Folder namespace to list / create under. Defaults to `LIBRARY` when omitted.
- in: query
name: parent_id
schema:
type: integer
description: Parent folder id whose direct children should be listed. Omit to list root folders.
tags:
- Library
security:
- OAuth2: []
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Folder'
description: ''
post:
operationId: folders_create
description: 'This is a shortcut class that will include all 6 resourceful actions part of the DRF ViewSets:
- list()
- retrieve()
- create()
- update()
- partial_update()
- destroy()
If you do not want to expose all 6 of these in your ViewSet, then use the CubeAuthenticatedViewSet and add the
appropriate mixins to it (see rest_framework.mixins). This will allow the api to behave appropriately and block
requests to unprocessable endpoints. Furthermore, it will make the drf_spectacular documentation be generated more
easily.'
summary: Create a folder
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
tags:
- Library
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Folder'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/Folder'
multipart/form-data:
schema:
$ref: '#/components/schemas/Folder'
required: true
security:
- OAuth2: []
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/Folder'
description: ''
/folders/{id}:
get:
operationId: folders_retrieve
description: 'This is a shortcut class that will include all 6 resourceful actions part of the DRF ViewSets:
- list()
- retrieve()
- create()
- update()
- partial_update()
- destroy()
If you do not want to expose all 6 of these in your ViewSet, then use the CubeAuthenticatedViewSet and add the
appropriate mixins to it (see rest_framework.mixins). This will allow the api to behave appropriately and block
requests to unprocessable endpoints. Furthermore, it will make the drf_spectacular documentation be generated more
easily.'
summary: Retrieve a folder
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
- in: path
name: id
schema:
type: string
required: true
tags:
- Library
security:
- OAuth2: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Folder'
description: ''
patch:
operationId: folders_partial_update
description: 'This is a shortcut class that will include all 6 resourceful actions part of the DRF ViewSets:
- list()
- retrieve()
- create()
- update()
- partial_update()
- destroy()
If you do not want to expose all 6 of these in your ViewSet, then use the CubeAuthenticatedViewSet and add the
appropriate mixins to it (see rest_framework.mixins). This will allow the api to behave appropriately and block
requests to unprocessable endpoints. Furthermore, it will make the drf_spectacular documentation be generated more
easily.'
summary: Update a folder
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
- in: path
name: id
schema:
type: string
required: true
tags:
- Library
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PatchedFolder'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/PatchedFolder'
multipart/form-data:
schema:
$ref: '#/components/schemas/PatchedFolder'
security:
- OAuth2: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Folder'
description: ''
delete:
operationId: folders_destroy
description: 'This is a shortcut class that will include all 6 resourceful actions part of the DRF ViewSets:
- list()
- retrieve()
- create()
- update()
- partial_update()
- destroy()
If you do not want to expose all 6 of these in your ViewSet, then use the CubeAuthenticatedViewSet and add the
appropriate mixins to it (see rest_framework.mixins). This will allow the api to behave appropriately and block
requests to unprocessable endpoints. Furthermore, it will make the drf_spectacular documentation be generated more
easily.'
summary: Delete a folder
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
- in: path
name: id
schema:
type: string
required: true
tags:
- Library
security:
- OAuth2: []
responses:
'204':
description: No response body
/library:
get:
operationId: library_list
description: 'Read-only unified listing of Library entries: folders, templates, and files. Each row carries a `type` discriminator (`folder`, `template`, or `file`) and the fields relevant to that kind. Folders are always pinned to the top of the page regardless of `?ordering=`. The listing is **shallow** -- use `?folder_id=` to drill into a folder. `file` covers both binary uploads and URL bookmarks (same underlying model).'
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
- in: query
name: created_by_id
schema:
type: integer
description: Filter to entries created by the given user id.
- in: query
name: folder_id
schema:
type: integer
description: Folder id to scope the listing to (drill-in). Omit to list the root context.
- name: limit
required: false
in: query
description: Number of results to return per page.
schema:
type: integer
- in: query
name: ordering
schema:
type: string
description: 'Comma-separated sort tokens (prefix `-` for descending). Allowed: [''created_at'', ''created_by'', ''last_opened_at'', ''name'', ''sharing_scheme'']. Default: `-created_at`. Folders always pin at the top regardless of ordering.'
- name: page
required: false
in: query
description: A page number within the paginated result set.
schema:
type: integer
- in: query
name: search
schema:
type: string
description: Case-insensitive substring match on `name`, applied at SQL before pagination.
- in: query
name: type
schema:
type: string
enum:
- all
- file
- template
description: 'Single value: `all` (default), `template`, or `file`. Narrows the non-folder kinds shown. **Folders are always included in the response regardless of this filter** -- use `?folder_id=` to scope inside a folder instead. `file` covers both binary uploads and URL bookmarks (they share the underlying `TemplateUpload` model).'
tags:
- Library
security:
- OAuth2: []
responses:
'200':
description: No response body
/library-items:
get:
operationId: library_items_list
description: List all library items
summary: List library items
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
tags:
- Library
security:
- OAuth2: []
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/LibraryItem'
description: ''
'401':
description: Unauthorized
'403':
description: Forbidden. Request was valid, but you do not have necessary permissions.
post:
operationId: library_items_create
description: Create a library item. Either file or url must be provided but not both.
summary: Create a library item
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
tags:
- Library
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/LibraryItem'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/LibraryItem'
multipart/form-data:
schema:
$ref: '#/components/schemas/LibraryItem'
required: true
security:
- OAuth2: []
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/LibraryItem'
description: ''
'400':
description: Bad request. Validation error.
'401':
description: Unauthorized
'403':
description: Forbidden. Request was valid, but you do not have necessary permissions.
/library-items/{id}:
get:
operationId: library_items_retrieve
description: Retrieve a library item by id
summary: Retrieve a library item
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
- in: path
name: id
schema:
type: string
required: true
tags:
- Library
security:
- OAuth2: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/LibraryItem'
description: ''
'401':
description: Unauthorized
'403':
description: Forbidden. Request was valid, but you do not have necessary permissions.
'404':
description: Library item not found
patch:
operationId: library_items_partial_update
description: Update a library item. Cannot replace an existing file with a url or vice versa. Cannot set both file and url.
summary: Update a library item
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
- in: path
name: id
schema:
type: string
required: true
tags:
- Library
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PatchedLibraryItem'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/PatchedLibraryItem'
multipart/form-data:
schema:
$ref: '#/components/schemas/PatchedLibraryItem'
security:
- OAuth2: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/LibraryItem'
description: ''
'400':
description: Bad request. Cannot set both file and url, or cannot replace file with url (or vice versa).
'401':
description: Unauthorized
'403':
description: Forbidden. Request was valid, but you do not have necessary permissions.
'404':
description: Library item not found
delete:
operationId: library_items_destroy
description: Delete a library item by id
summary: Delete a library item
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
- in: path
name: id
schema:
type: string
required: true
tags:
- Library
security:
- OAuth2: []
responses:
'204':
description: Library item deleted successfully
'401':
description: Unauthorized
'403':
description: Forbidden. Request was valid, but you do not have necessary permissions.
'404':
description: Library item not found
/library/owners:
get:
operationId: library_owners_list
description: Distinct creators of Library entries visible to the requester. Backs the Library page Owner filter dropdown. Mirrors `/library` visibility (same `?folder_id=` / `?type=` scoping, same per-instance permission filter) so creators of rows the requester can't see never appear here. Not paginated -- owner counts are bounded by company size.
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
- in: query
name: created_by_id
schema:
type: integer
description: Filter to entries created by the given user id.
- in: query
name: folder_id
schema:
type: integer
description: Folder id to scope the owner set to a specific folder. Omit to return owners of the root listing. Same semantics as `/library?folder_id=`.
- name: limit
required: false
in: query
description: Number of results to return per page.
schema:
type: integer
- in: query
name: ordering
schema:
type: string
description: 'Comma-separated sort tokens (prefix `-` for descending). Allowed: [''created_at'', ''created_by'', ''last_opened_at'', ''name'', ''sharing_scheme'']. Default: `-created_at`. Folders always pin at the top regardless of ordering.'
- name: page
required: false
in: query
description: A page number within the paginated result set.
schema:
type: integer
- in: query
name: search
schema:
type: string
description: Case-insensitive substring match on `name`, applied at SQL before pagination.
- in: query
name: type
schema:
type: string
enum:
- all
- file
- template
description: 'Single value: `all` (default), `template`, or `file`. Narrows the owner set to creators of items of those kinds. Folders are always considered, matching `/library`.'
tags:
- Library
security:
- OAuth2: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedUserList'
description: ''
/templates:
get:
operationId: templates_list
description: 'List all templates available to the authenticated user company.
- Expensive fields such as `content`, `styles`, `sheet_metadata`, `formulas`, `images`, etc are omitted from this response for performance reasons.'
summary: List all templates.
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
- in: query
name: planning_table_id
schema:
type: integer
description: Limit results to those associated with this planning table id
tags:
- Library
security:
- OAuth2: []
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Template'
examples:
ListTemplates:
value:
- id: bdf7a8d3-3dcd-4fed-b13a-939d6b9b5a59
name: A Fabulous Template
allow_web_publish: true
address: A1:G6
description: A fabulous description
ranges:
- id: 22
address: C2:D4
cube_value_range:
id: 2
filters:
'6': 66
'7': 77
name: Range 11
fetch_enabled: true
publish_enabled: true
currency:
id: 3
name: United States Dollar
code: USD
exclude_zeros: false
table_datasets:
- id: 11
address: D5:F7
planning_table_id: 1
scenario_id: 8
sharing_scheme: MANAGERS
shared_with: []
created_by:
id: 501
first_name: John
last_name: Doe
is_staff: true
timezone: US/Eastern
created_at: '2026-07-12T00:28:02.235809+00:00'
modified_at: '2026-07-12T00:28:02.235872+00:00'
folder: null
last_opened_at: '2026-07-12T00:28:02.235896+00:00'
summary: List Templates
description: Successful retrieval of templates
post:
operationId: templates_create
description: 'Create a new template.
- When submitted fields contain A1 range values, these values will be normalized (shifted) relative to cell A1 before being stored.
- Matrix fields such as `content`, `styles`, `sheet_metadata`, `formulas`, and `images` will be _sparsified_ for storage optimization, meaning their values will be stored as key-value pairs addressed by their cell references.'
summary: Create a template.
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
tags:
- Library
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Template'
examples:
CreateATemplate:
value:
name: A Fabulous Template
allow_web_publish: true
address: A1:G6
description: A fabulous description
ranges:
- id: 22
address: C2:D4
table_datasets:
- id: 11
address: D5:F7
content:
- - ''
- ''
- ''
- ''
- ''
- ''
- ''
- - ''
- ''
- ''
- ''
- ''
- ''
- ''
- - ''
- ''
- ''
- ''
- ''
- ''
- ''
- - ''
- ''
- ''
- ''
- ''
- ''
- ''
- - ''
- ''
- ''
- ''
- ''
- ''
- ''
- - ''
- ''
- '12345'
- June 13, 1982
- ''
- ''
- ''
styles:
- - font_underline: false
background_color: '#ffffff'
font_italic: false
font_color: '#000000'
font_size: 10
vertical_alignment: bottom
font_bold: false
font_family: Arial
font_line_through: false
- ''
- ''
- ''
- ''
- ''
- ''
- - ''
- ''
- ''
- ''
- ''
- ''
- ''
- - ''
- ''
- ''
- ''
- ''
- ''
- ''
- - ''
- ''
- ''
- ''
- ''
- ''
- ''
- - ''
- ''
- ''
- ''
- ''
- ''
- ''
- - ''
- ''
- ''
- ''
- ''
- ''
- font_underline: false
background_color: '#ffffff'
font_italic: false
font_color: '#000000'
font_size: 10
vertical_alignment: bottom
font_bold: false
font_family: Arial
font_line_through: false
formulas:
- - ''
- ''
- ''
- =SUM(A1:B4)
- =SUM(A1:B5)
- ''
- ''
- - ''
- ''
- ''
- ''
- ''
- ''
- ''
- - =DIV(A1:B4)
- ''
- ''
- ''
- ''
- ''
- ''
- - ''
- ''
- ''
- ''
- ''
- ''
- ''
- - ''
- ''
- ''
- ''
- ''
- ''
- ''
- - ''
- ''
- ''
- ''
- ''
- ''
- ''
formats:
- - ''
- ''
- '#,##0.00'
- 0.00%
- ''
- ''
- ''
- - ''
- ''
- ''
- '#,##0.00;(#,##0.00)'
- ''
- ''
- ''
- - ''
- ''
- mm/dd/yyyy
- ''
- ''
- ''
- ''
- - ''
- ''
- ''
- h:mm:ss am/pm
- ''
- ''
- ''
- - ''
- ''
- ''
- ''
- ''
- ''
- ''
- - ''
- ''
- ''
- ''
- ''
- ''
- ''
data_validation: {}
sheet_metadata:
gridlines: true
columns:
A:
visibility: true
width: 100
G:
visibility: true
width: 100
rows:
'1':
visibility: true
height: 21
'6':
visibility: true
height: 21
merged_cells: {}
images:
- - ''
- ''
- ''
- ''
- ''
- ''
- ''
- - ''
- ''
- ''
- ''
- ''
- ''
- ''
- - ''
- ''
- ''
- ''
- ''
- ''
- ''
- - ''
- ''
- ''
- ''
- ''
- ''
- ''
- - ''
- ''
- ''
- ''
- ''
- ''
- ''
- - ''
- ''
- ''
- ''
- ''
- ''
- url: https://crystal.com/clear.png
summary: Create a Template
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/Template'
multipart/form-data:
schema:
$ref: '#/components/schemas/Template'
required: true
security:
- OAuth2: []
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/Template'
examples:
TemplateCreated:
value:
id: 255f6070-53c0-48f1-991c-da59faa3a217
name: A Fabulous Template
allow_web_publish: true
address: A1:G6
description: A fabulous description
ranges:
- id: 22
address: C2:D4
cube_value_range:
id: 2
filters:
'6': 66
'7': 77
name: Range 11
fetch_enabled: true
publish_enabled: true
currency:
id: 3
name: United States Dollar
code: USD
exclude_zeros: false
headers:
B1: Q1-25
A2: Revenue
filters:
'6': 66
'7': 77
table_datasets:
- id: 11
address: D5:F7
planning_table_id: 1
scenario_id: 8
planning_table_schema:
- id: 4e947903-9d1a-4523-b537-b90364972868
name: Column-A
required: true
type: text
- id: 4bb32be6-3a05-4894-8278-166dd7685f47
name: Column-B
required: false
type: text
content:
C6: '12345'
D6: June 13, 1982
styles:
A1:
font_underline: false
background_color: '#ffffff'
font_italic: false
font_color: '#000000'
font_size: 10
vertical_alignment: bottom
font_bold: false
font_family: Arial
font_line_through: false
G6:
font_underline: false
background_color: '#ffffff'
font_italic: false
font_color: '#000000'
font_size: 10
vertical_alignment: bottom
font_bold: false
font_family: Arial
font_line_through: false
formulas:
D1: =SUM(A1:B4)
E1: =SUM(A1:B5)
A3: =DIV(A1:B4)
formats:
C1: '#,##0.00'
# --- truncated at 32 KB (144 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cubesoftware/refs/heads/main/openapi/cubesoftware-library-api-openapi.yml