Cubicl Docs
Search…
⌃K

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 120 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.