Tasks

Definitions of the types and formats of the data used in the endpoints can be found at the bottom of the page.

Endpoints

Get Tasks

GET https://cubicl.io/api/v1/tasks

Gets tasks matching the given search criteria. Some details won't be returned in the response. Use Get Task By Id request to get all details.

Query Parameters

Name	Type	Description
group	string	Project id
assignee	string	Task assignee id
limit	number
skip	number
tag	string	Tag name
customer	string	Client id
assignedBy	string	Task owner id
startDate	number	Start of time interval the task's start date or deadline falls into. Must be used with "endDate" parameter.
endDate	number	Read "startDate"
archived	string	'true' to get archived tasks 'false' to get unarchived tasks 'all' to get all tasks Default is 'false'
recursive	string	'true' to get tasks in descended projects too Leave empty to get tasks only in given project Default is empty
search	string	Text to search in task name
include	string	Comma separated list of properties to be included in the response
exclude	string	Comma separated list of properties to be excluded in the response. Cannot be used together with include.

200: OK List of tasks

Task[]

403: Forbidden You don't have the permission to get tasks.

{ code: 4 }

Get Task By Id

GET https://cubicl.io/api/v1/tasks/:id

Path Parameters

Name	Type	Description
id*	string	Task id

200: OK Task details

Task

403: Forbidden You don't have the permission to get the task.

{ code: 4 }

Create Task

POST https://cubicl.io/api/v1/tasks

Request Body

Name	Type	Description
group*	string	Project id
workFlowId	string	Set when task is being created with a workflow.
parent	string	Parent task id. Set when task is being created a subtask of another task.
private	boolean	Default is false
recurrence	Recurrence	If 'recurrent' is true, this should be set. Check below for recurrence details.
recurrent	boolean	Default is false.
steps	CheckList | ProgressBar	If 'stepType' is 'steps', provide steps in CheckList format. Id field is not required. It will be set in the server. If 'stepType' is 'progress', provide steps in ProgressBar format. If 'stepType' is 'none', don't set this.
stepType	string	'none' for no task steps 'steps' for checklist 'progress' for progress bar Default is 'none'
files	string[]	List of file ids. In order to create a file with files, you need to upload files before creating the task and set their ids here.
customer	string	Client id
tags	string[]	Tag ids
priority	number	1 to 5. 5 is highest. Default is 3.
assignees	string[]	List of assignee ids
deadline	number
start	number	Start date
desc	string	Task description
name*	string	Task name
state	string	State name. If not given, default state set in the project details will be used.
estimatedTime	number	Estimated time of the task in seconds. Shown in the UI only when enabled in the project settings.
customFields	object	An object where keys are the custom field names and values are the values of those fields.
followers	string[]	Ids of task followers. If not set, task owner and assignees will be followers.

200: OK New task details

Task

422: Unprocessable Entity Invalid operation

// Empty response
// Potential causes:
// - Invalid project
// - Invalid parent task

403: Forbidden You don't have the permission

{ code: 4 }

422: Unprocessable Entity Task state does not exists

{ code: 503 }

Update Task

PUT https://cubicl.io/api/v1/tasks/:id

Updates a task with given details. All details are optional. Only given fields are updated. If you need to unset a field, set its values to null or appropriate falsy value. For example, an empty string for strings.

Path Parameters

Name	Type	Description
id*	string	Task id

Request Body

Name	Type	Description
assignees	string[]	Assignee id list
followers	string[]	Follower id list
customer	string	Client id
deadline	number	Deadline
desc	string	Description
group	string	The project id to which the task is to be moved
files	string[]	File id list
recurrent	boolean	Boolean
recurrence	Recurrence	Task recurrence details
name	string	Task name
workflowId	string	Workflow id
start	number	Start date
steps	Checklist | ProgressBar	Required when 'stepType' is 'steps' or 'progress'
stepType	string	'none', 'steps' or 'progress'
private	boolean
state	string	Task state name. Required when moving the task to a different project and changing to a different state within that project.
subtasks	string[]	Subtask id list
estimatedTime	number	Estimated task duration in seconds
customFields	object	An object where keys are field names and values are field values.
updateTemplate	boolean	If task is recurrent this field will determine whether to update the details only on the task itself or including the future copies of the task.

200: OK Updated task details and task update activity

{
    activity: TaskActivity,
    task: Task
}

403: Forbidden You don't have the permission

{
    // 4: No permission to update task details
    // 804: No permission to move the task out of the project
    // 805: No permission to move the task into the project
    code: number
}

422: Unprocessable Entity Invalid operation

// Following object or empty response for unknown error
{
    // 403: This update changes the Gantt Chart and you have no permission for that
    // 406: Task in the Gantt Chart must have dates.
    // 503: Task state does not exist
    // 604: Archived tasks cannot be updated
    code: number
}

Delete Task

DELETE https://cubicl.io/api/v1/tasks/:id

Deletes the task with given id.

Path Parameters

Name	Type	Description
id*	string	Task id

200: OK Empty response

403: Forbidden You don't have the permission.

{ code: 4 }

422: Unprocessable Entity Invalid operation

// Following object or empty response for unknown error
{
    // 4: This operation requires to delete subtasks but you have no permission for that
    // 403: This update changes the Gantt Chart and you have no permission for that
    code: number
}

Add Subtask to Task

POST https://cubicl.io/api/v1/tasks/:id/subtasks

Path Parameters

Name	Type	Description
id*	string	Task ID

Request Body

Name	Type	Description
subtask*	string	The ID of the task to be added as a subtask.

200: OK Empty response

403: Forbidden You don't have the permission.

{ code: 4 }

422: Unprocessable Entity A task higher in the hierarchy cannot be added as a subtask.

{ code: 802 }

Update Task State

PUT https://cubicl.io/api/v1/tasks/:id/state

Changes the state of a task to the given state. The default states for a project are Pending, Active, Completed, and Suspended. These states are recorded in the system as cb_waiting, cb_active, cb_completed, and cb_suspended, respectively. When using default states, the recorded values must be sent.

Path Parameters

Name	Type	Description
id*	string	Task id

Request Body

Name	Type	Description
value*	string	New task state name.

200: OK Task State Activity

TaskStateActivity

403: Forbidden You don't have the permission

{ code: 4 }

422: Unprocessable Entity Task state does not exists

{ code: 503 }

422: Unprocessable Entity Invalid operation

// Error message
// Potential causes:
// - Archived tasks cannot have their state updated.
// - The task is already in the desired state.

Create Task Comment

POST https://cubicl.io/api/v1/tasks/:id/activities

Creates a comment on a task.

Path Parameters

Name	Type	Description
id*	string	Task ID

Request Body

Name	Type	Description
content	string	The content of the comment. Either 'content' or 'fileIds' must be provided.
fileIds	string[]	List of file IDs. In order to create a comment with files, you need to upload the files before creating the comment and set their IDs here. Either 'fileIds' or 'content' must be provided.
mentions	Mention[]	List of users mentioned in the comment.
replyToId	string	The ID of the comment you want to reply to.

200: OK Task Activity

TaskActivity

403: Forbidden You don't have the permission.

{ code: 4 }

Change Task Comment Visibility

PUT https://cubicl.io/api/v1/tasks/:taskId/activities/:activityId

In support requests and tasks shared with your client, you can change the visibility of your comment for your portal client. When comments in email tasks are made visible, the comment is sent as an email.

Path Parameters

Name	Type	Description
taskId*	string	Task ID
activityId*	string	The ID of the activity whose visibility is to be changed.

Request Body

Name	Type	Description
value*	boolean	Determines the visibility of the comment. true makes it visible, false removes the visibility.

200: OK Empty response

403: Forbidden You don't have the permission.

{ code: 4 }

422: Unprocessable Entity Invalid operation

// Error message
// Potential causes:
// - Only activities of type "post" can have their visibility changed.
// - Visibility can only be changed for support requests, tasks shared with customers, or email tasks.
// - The visibility of comments created by portal or email users cannot be changed.
// - The visibility of comments made visible in email tasks cannot be removed.

Get Task Activities

GET https://cubicl.io/api/v1/tasks/:id/activities

Path Parameters

Name	Type	Description
id*	string	Task id

200: OK Task Activities

TaskActivity[]

403: Forbidden You don't have the permission

{ code: 4 }

Data

Task

Details of a task.

{
    _id: string;
    name: string;
    desc: string;
    state: string;
    start: number | null; // Start date
    deadline: number | null;
    assignees: string[]; // Assignee ids
    assignedBy: string; // Owner id
    followers: string[];
    // Ids of the portal users who follow this task if task is shared in
    // the client portal
    portalFollowers?: string[];
    // From 1 to 5. 5 is the highest.
    priority: number;
    // A score to sort same-priority tasks among themselves. 
    // Lowest score is shown at the top.
    priorityScore: number;
    // Project id
    group: string;
    completedAt: number;
    archivedAt?: number | null;
    /* none: Task has no steps
     * steps: Task has a checklist
     * progress: Task has a progress bar
     */
    stepType: 'none' | 'steps' | 'progress';
    // Check below for definitions of these types
    steps?: CheckList | ProgressBar;
    customer: {
        _id: string,
        name: string,
    } | null,
    createdAt: number;
    files: { _id: string }[];
    tags: string[];
    subtasks: string[];
    parent: string | null;
    // This property exists if task is created for an incoming mail
    // An id is created for the email sender
    email?: {
        emailUserId: string,
    };
    // This property exists if task is created for a support request
    // through the Client Portal feature
    support?: {
        portalUser: string, // Id of the client portal user
    };
    private: boolean;
    sharedWithCustomer?: boolean;
    // Exists if task belongs to a workflow
    workflow?: {
        id: string,
        templateId: string,
        isCompleted: boolean,
        taskflowId: string
    };
    estimatedTime?: number; // Duration in seconds
    // If task has custom fields, holds the name and value for each field
    customFields?: {[fieldName: string]: string};
    // If task is recurrent, shows if this is the newest copy
    lastCopy?: boolean;
}

Task Steps

Tasks can have a checklist or a progress bar to indicate the steps / overall progress.

type ProgressBar = {
    completed: number;
    total: number;
}

type CheckList = TaskStep[];

type TaskStep = {
    id: string;
    name: string;
    desc?: string;
    assignees: string[]; // Ids of the step assignees
    /* Task steps are recursive. They can have sub-steps too.
     * If not set, the step has no sub-steps.
     * If 'steps', a property named 'steps' holds sub-steps.
     * If 'progress', this step object has a property named 'total'.
     */
    stepType?: 'steps' | 'progress';
    steps?: CheckList;
    // If 'stepType' is 'progress', this is a number and indicates the total number
    // of steps in the bar. Otherwise, a boolean to indicate completion.
    completed: boolean | number;
    // Set when 'stepType' is 'progress'
    total?: number;
}
    

Recurrence

type Recurrence = {
    type: 'daily' | 'weekly' | 'monthly';
    // Example: Set 3 for task to be copied every 3 days/weeks/months.
    period: number;
    // New copy is created after task deadline or when task is completed
    createWhen: 'after-deadline' | 'completed';
    // If true, recurrence continues. Otherwise, it will pause.
    active: boolean;
    /* 'none': Continues indefinitely
     * 'date': Continues until given date in the 'end' parameter.
     * 'count': Continues until amount of copies set in 'maxCount' parameter
     * are created. The task itself is the first copy. So if, maxCount is 1,
     * no copies will be created.
     */
    stopCondition: 'none' | 'date' | 'count';
    end?: number;
    maxCount?: number;
    // If 'type' is 'weekly' you can set in which days of the week a copy should
    // be created. The list is the days of the week indicating whether that day
    // a copy should be created. Starts with Monday.
    days?: boolean[];
}

Task Activity

Update and progress actions and messages on tasks create task activities.

type TaskActivity = {
    _id: string;
    // Id of the user who did the activity
    user: string;
    // Id of the portal user who created the activity. Exists only when
    // activity is created in the Client Portal by a portal user.
    portalUser?: string;
    // Id of the email sender. Exists when the activity is created due to
    // an incoming mail.
    emailUser?: string;
    type:
        | 'post' // A post (comment) on the task
        | 'update' // Task is updated
        | 'progress' // Task step completed/uncompleted, progress changed
        | 'archive' // Task is archived
        | 'restore' // Task is restored from the archive
        | 'state-change' // Task state is changed
        | 'delete'; // Task is deleted
    // Holds the info about the update. The shape depends on the 'type'
    data?: object;
    // If 'type' is 'post', holds the comment content
    content?: string;
    // If 'type' is 'post', holds the file details
    files?: File[] = [];
    createdAt: number;
    // If activity is a reply to a previous post, keeps the referenced activity id
    replyToId?: string;
    // Whether the activity (post) is shared with a Client Portal user.
    customerCanSee: boolean;
    // List of users mentioned in the post
    mentions: Mention[];
    customFields?: {
        fieldName: string;
        value: string;
    }[];
    // If a task is created from an incoming email
    emailDetails?: EmailDetails;
    // If task is created for an incoming email, posts on the task can be sent
    // as email. This holds the state of the mail.
    mailStatus?: 'not-sent' | 'sending' | 'sent' | 'mail-box-error' | 'error';
}

type Mention = {
    id: string;  // User id
    name: string; // Text used to mention user in the post
}

type EmailDetails = {
    to: EmailPerson[];
    cc: EmailPerson[];
    from: EmailPerson;
}

type EmailPerson = {
    name: string;
    emailAddress: string;
}

Task State

type TaskState = {
    name: string;
    type: 'waiting' | 'active' | 'completed' | 'suspended' | 'cancelled';
    color: string;
    textColor: string;
    isDefault?: boolean;
}

type TaskStateActivity = {
    _id: string;
    // Id of the user who did the activity
    user: string;
    task: string;
    type: 'state-change';
    data: {
        oldState: TaskState;
        newState: TaskState;
    };
}  

Default Task States

If task states are not customized for the project, default states are used. These values are translated into the user's language when shown in the UI. These values are:

State Value	Translation in UI
cb_waiting	Pending
cb_active	Active
cb_completed	Completed
cb_suspended	Suspended

You can check the project object to see whether task states are customized or defaults are being used.