Cube Planning Taskflow API
The Taskflow API from Cube Planning — 11 operation(s) for taskflow.
OpenAPI Specification
openapi: 3.0.3
info:
title: Cube Agents Taskflow 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: Taskflow
paths:
/action-items:
get:
operationId: action_items_list
description: 'Retrieve a list of all action items created by the authenticated user within their company.
Items are returned ordered by position (ascending).'
summary: List action items
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
tags:
- Taskflow
security:
- OAuth2: []
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ActionItem'
description: ''
'401':
description: Unauthorized - authentication credentials not provided or invalid
'403':
description: Forbidden - insufficient permissions
post:
operationId: action_items_create
description: 'Create a new action item. The action item name must be unique within the company.
The position field is automatically set to the end of the list (count of existing items). Position is 0-indexed and maintains a continuous sequence with no gaps.'
summary: Create an action item
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
tags:
- Taskflow
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ActionItem'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/ActionItem'
multipart/form-data:
schema:
$ref: '#/components/schemas/ActionItem'
required: true
security:
- OAuth2: []
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/ActionItem'
description: ''
'400':
description: Invalid input - action item name must be unique or exceeds max length
'401':
description: Unauthorized - authentication credentials not provided or invalid
'403':
description: Forbidden - insufficient permissions
/action-items/{id}:
get:
operationId: action_items_retrieve
description: Retrieve details of a specific action item by ID. Users can only retrieve action items they created.
summary: Retrieve an action 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:
- Taskflow
security:
- OAuth2: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ActionItem'
description: ''
'401':
description: Unauthorized - authentication credentials not provided or invalid
'403':
description: Forbidden - insufficient permissions
'404':
description: Action item not found or not owned by user
patch:
operationId: action_items_partial_update
description: 'Partially update an action item. Only include fields to be updated.
- Set "completed" to true to mark as completed, or false to mark as incomplete.
- Update "position" to reorder the item (0-indexed). Other items will automatically shift to maintain continuous sequence.
- Users can only update action items they created.'
summary: Update an action 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:
- Taskflow
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PatchedActionItem'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/PatchedActionItem'
multipart/form-data:
schema:
$ref: '#/components/schemas/PatchedActionItem'
security:
- OAuth2: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ActionItem'
description: ''
'400':
description: Invalid input - action item name must be unique, exceeds max length, or position is invalid
'401':
description: Unauthorized - authentication credentials not provided or invalid
'403':
description: Forbidden - insufficient permissions
'404':
description: Action item not found or not owned by user
delete:
operationId: action_items_destroy
description: 'Delete an action item by ID. Users can only delete action items they created.
When an item is deleted, all items with higher positions are automatically shifted down to close the gap and maintain a continuous sequence.'
summary: Delete an action 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:
- Taskflow
security:
- OAuth2: []
responses:
'204':
description: Action item successfully deleted
'401':
description: Unauthorized - authentication credentials not provided or invalid
'403':
description: Forbidden - insufficient permissions
'404':
description: Action item not found or not owned by user
/processes:
get:
operationId: processes_list
description: List all workflows with optional filtering.
summary: List workflows
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
- in: query
name: created_by
schema:
type: integer
description: Filter by creator ID
- in: query
name: owner
schema:
type: integer
description: Filter by owner ID
- in: query
name: past_due
schema:
type: boolean
description: Filter for processes with tasks that have a due date in the past.
- in: query
name: search
schema:
type: string
description: Search term for process name or owner details.
- in: query
name: status
schema:
type: string
enum:
- COMPLETED
- IN_PROGRESS
- NOT_STARTED
description: Filter by status
tags:
- Taskflow
security:
- OAuth2: []
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Process'
description: ''
'401':
description: Unauthorized
'403':
description: Forbidden - User does not have permission to view processes.
post:
operationId: processes_create
description: 'Create a new workflow. Required field: name.'
summary: Create a workflow
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
tags:
- Taskflow
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Process'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/Process'
multipart/form-data:
schema:
$ref: '#/components/schemas/Process'
required: true
security:
- OAuth2: []
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/Process'
description: ''
'400':
description: Invalid input (e.g., duplicate name).
'401':
description: Unauthorized
'403':
description: Forbidden - User does not have permission to create processes.
/processes/{id}:
get:
operationId: processes_retrieve
description: Retrieve details of a specific workflow by its ID.
summary: Retrieve a workflow
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:
- Taskflow
security:
- OAuth2: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Process'
description: ''
'401':
description: Unauthorized
'403':
description: Forbidden - User does not have permission to view this process.
'404':
description: Process not found
patch:
operationId: processes_partial_update
description: Update specific process fields. Only include fields to be updated.
summary: Update a workflow (PATCH)
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:
- Taskflow
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PatchedProcess'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/PatchedProcess'
multipart/form-data:
schema:
$ref: '#/components/schemas/PatchedProcess'
security:
- OAuth2: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Process'
description: ''
'400':
description: Invalid input (e.g., duplicate name, invalid status transition).
'401':
description: Unauthorized
'403':
description: Forbidden - User does not have permission to update this process.
'404':
description: Process not found
delete:
operationId: processes_destroy
description: Soft delete a workflow by marking it as deleted.
summary: Delete a workflow
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:
- Taskflow
security:
- OAuth2: []
responses:
'204':
description: Process deleted successfully
'401':
description: Unauthorized
'403':
description: Forbidden - User does not have permission to delete this process.
'404':
description: Process not found
/processes/{id}/duplicate:
post:
operationId: processes_duplicate_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.'
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:
- Taskflow
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Process'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/Process'
multipart/form-data:
schema:
$ref: '#/components/schemas/Process'
required: true
security:
- OAuth2: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Process'
description: ''
/processes/{id}/remind-now:
post:
operationId: processes_remind_now_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.'
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:
- Taskflow
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Process'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/Process'
multipart/form-data:
schema:
$ref: '#/components/schemas/Process'
required: true
security:
- OAuth2: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Process'
description: ''
/processes/{id}/tasks/{task_id}/remind:
post:
operationId: processes_tasks_remind_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.'
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
- in: path
name: task_id
schema:
type: string
required: true
tags:
- Taskflow
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Process'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/Process'
multipart/form-data:
schema:
$ref: '#/components/schemas/Process'
required: true
security:
- OAuth2: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Process'
description: ''
/processes/{id}/tasks/export:
get:
operationId: processes_tasks_export_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.'
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:
- Taskflow
security:
- OAuth2: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Process'
description: ''
/tasks:
get:
operationId: tasks_list
description: List all tasks for a given workflow
summary: List workflows tasks
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
- in: query
name: assignee
schema:
type: integer
description: Filter by assignee id
- in: query
name: past_due
schema:
type: boolean
description: Filter by past_due
- in: query
name: process_id
schema:
type: integer
description: Filter by process id
required: true
- in: query
name: status
schema:
type: string
enum:
- DONE
- DRAFT
- TODO
description: Filter by status
tags:
- Taskflow
security:
- OAuth2: []
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Task'
description: ''
'401':
description: Unauthorized
post:
operationId: tasks_create
description: Create a new task
summary: Create a task
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
tags:
- Taskflow
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Task'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/Task'
multipart/form-data:
schema:
$ref: '#/components/schemas/Task'
required: true
security:
- OAuth2: []
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/Task'
description: ''
'400':
description: Invalid input
'401':
description: Unauthorized
/tasks/{id}:
get:
operationId: tasks_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.'
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:
- Taskflow
security:
- OAuth2: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Task'
description: ''
put:
operationId: tasks_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.'
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:
- Taskflow
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Task'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/Task'
multipart/form-data:
schema:
$ref: '#/components/schemas/Task'
required: true
security:
- OAuth2: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Task'
description: ''
patch:
operationId: tasks_partial_update
description: Update task fields. Only include fields to be updated.
summary: Update a task
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:
- Taskflow
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PatchedTask'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/PatchedTask'
multipart/form-data:
schema:
$ref: '#/components/schemas/PatchedTask'
security:
- OAuth2: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Task'
description: ''
'400':
description: Invalid input
'401':
description: Unauthorized
'404':
description: Task not found
delete:
operationId: tasks_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.'
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:
- Taskflow
security:
- OAuth2: []
responses:
'204':
description: No response body
/tasks/bulk:
post:
operationId: tasks_bulk_create
description: 'Executes a batch of Task operations (creates and updates) for a single Workflow Process.
**Request Rules:**
- Only `In Progress` or `Not Started` Processes are permitted
- Tasks with an `id` are treated as updates
- Tasks without an `id` (or `id: null`) are treated as creates
- Updates are processed before creates
- New tasks are always created with status `DRAFT` regardless of supplied value
- Only Workflow Managers can access this endpoint
**Resources:**
- Each task supports a `resources` array of `{id, content_type}` objects
- Valid `content_type` values: `dashboard`, `template`, `templateupload`, `canvas`
- Maximum of 1 resource per task
- Omit `resources` to preserve existing; set to `[]` to clear all
- User must have view access to a resource to assign it
- Restricted resources are returned with `permission_denied: true` and `content: {}`
**Response Behavior:**
- Returns 400 for request-level validation errors (invalid `process_id`, missing `tasks`, duplicate task IDs)
- Returns 200 with per-task results for individual task operations (partial success supported)
- Each result has `task` (data or null) and `errors` (null or error details)
- On update failure, `task` contains current state; on create failure, `task` is null
**Per-Task Error Structure (flat array):**
- Each error has: `code`, `detail`, and `source`
- Field errors: `source: { field: "name" }` with DRF codes (`null`, `required`, `invalid`)
- Business errors: `source: null` with custom codes (`INVALID_DATE_PAST_DUE`, `DUPLICATE_NAME`)
- Multiple errors can be present on a single task'
summary: Bulk create and update Tasks
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
tags:
- Taskflow
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BulkTaskRequest'
examples:
CreateMultipleTasks:
value:
process_id: 1
tasks:
- name: Review Q1 Budget
due_date: '2025-03-15'
- name: Update Forecasts
due_date: '2025-03-20'
assignee_id: 5
summary: Create multiple tasks
CreateTaskWithResource:
value:
process_id: 1
tasks:
- name: Review Q4 Report
due_date: '2026-02-15'
resources:
- id: '42'
content_type: dashboard
summary: Create task with resource
CreateTaskWithCanvasResource:
value:
process_id: 1
tasks:
- name: Review Q4 Canvas
due_date: '2026-02-15'
resources:
- id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
content_type: canvas
summary: Create task with canvas resource
UpdateMultipleTasks:
value:
process_id: 1
tasks:
- id: 10
name: Updated Task Name
- id: 11
status: TODO
assignee_id: 5
summary: Update multiple tasks
UpdateTask-ReplaceResource:
value:
process_id: 1
tasks:
- id: 15
resources:
- id: '99'
content_type: template
summary: Update task - replace resource
UpdateTask-RemoveAllResources:
value:
process_id: 1
tasks:
- id: 15
resources: []
summary: Update task - remove all resources
MixedCreateAndUpdate:
value:
process_id: 1
tasks:
- id: 10
name: Updated Task Name
- name: New Task
due_date: '2025-03-15'
summary: Mixed create and update
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/BulkTaskRequest'
multipart/form-data:
schema:
$ref: '#/components/schemas/BulkTaskRequest'
required: true
security:
- OAuth2: []
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/BulkTaskResult'
examples:
AllOperationsSucceed:
value:
- - task:
id: 10
process_id: 1
name: Updated Task Name
# --- truncated at 32 KB (57 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cube-planning/refs/heads/main/openapi/cube-planning-taskflow-api-openapi.yml