Introduction

Cubicl API integration documentation

API integration allows you to integrate Cubicl with your own software or other software you are using. You can send HTTP requests to get, create, edit and delete tasks, clients, files, and other records. This is a technical document. If you don't have a technical background, it is best to direct this document to a developer.

Protocol

Cubicl uses a RESTful API. JSON is used for request body and responses. API URLs start with https://cubicl.io/api/v1/. For example, you need to send a request to the following URL to create a task:

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

Successful requests will return 200 or other HTTP status codes starting with 2. Following HTTP status codes are returned in case of error.

Status	Name	Description
400	Bad Request	Request parameters are missing or incorrectly formatted.
401	Unauthorized	Access token is invalid or missing.
403	Not Permitted	You don't have necessary permissions to do the operation.
404	Not Found	Resource does not exist.
405	Wrong Method	You have used the wrong HTTP method (GET, POST etc.). Check the API documentation to see which method is used for the request.
418	No Coffee	You are attempting to brew coffee but this request cannot be fulfilled since the server is a teapot.
422	Invalid Request	You are trying to do something which is not possible or does not make sense. Check the data you are working on.
429	Too Many Requests	You have sent too much requests in a short interval. You cannot send more than 120 requests per minute. Wait a bit and try again.
5xx	Server Error	An error occured in the server.

You cannot send more than 60 requests per minute. Put a delay between requests if you plan to send them in a loop.

Access Tokens

Cubicl uses Bearer authentication scheme for API access. In order to send requests to our API, you need to create an access token in the Integrations Page. When sending requests, send the access token in a header named Authorization as follows:

Authorization: Bearer YOUR_TOKEN_HERE

Access tokens allow you to send requests (access data or do operations) on behalf of a user. Because of that, they are sensitive data and must be treated as passwords. Do NOT share them with others. Do NOT put them into shared or public code repositories.

You can always remove access tokens in Cubicl interface to cut their access.

Permissions

Since access tokens allow access on behalf of a user, the corresponding user must have the necessary permissions to perform that action. User permissions are set in the Cubicl interface. Access tokens are created for each user separately. Because of that, you need to create the token in the account of the user on whose behalf you will be sending requests.

Separate Account

Actions done through API requests, such as creating a task, will look like as if they are done by the owner of the access token. If you need to separate automated API actions from the user's own actions, you may consider creating a new user account just for API access. This should also be considered when your API integration implementation requires a broad range of permissions that you don't want to give a user. Monthly or yearly subscription fees apply to these accounts as well since they are no different than a regular user account.

Data and Representation

In the following pages, you will see the API endpoint details. The properties and format of the data sent in a request and returned from the server is explained here.

Representation

Data is represented in Typescript type definition format in this documentation. An example is given below with comments.

type Task = {
    // Names and types of properties are shown as key-type pairs
    name: string,
    activityCount: number,
    completed: boolean,
    // Object types define type of each of their properties
    progress: {
        totalSteps: number,
        completed: number,
    },
    // Array types have square brackets next to the type name. Be aware that
    // properties can hold an array of objects or an array of arrays too.
    assigneeIds: string[],
    // If a field can be missing, it will have a "?" next to the property name. If
    // the field type can have different types or if it can be null, it will be
    // shown as a union of types with a "|" symbol.
    archivedAt?: Date | null,
}

IDs

IDs of the records are strings stored in _id the property. Example:

627fd586f8b23768c7261a63

Date Values

Dates in the requests and responses are sent as Unix Timestamps in seconds. Because of that, their types are shown as number in the API documentation.

Sparse Data

Unless specified otherwise, create and update requests only need the required fields. Other fields don't need to be set in the requests.

Records returned from the server may not contain all the fields if they are not set or unset before. Your code should be able to handle missing fields. In this case, accept them as null or a falsy value.

Help

If you face any issues with the API documentation, access token generation or want a missing endpoint to be added, please contact us.