Comment on page
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.
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.
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.
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.
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.
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.
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 of the records are
strings stored in _id the property. Example:627fd586f8b23768c7261a63
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.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.
If you face any issues with the API documentation, access token generation or want a missing endpoint to be added, please contact us.
Last modified 1mo ago