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:
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:
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.
IDs
IDs of the records are string
s stored in _id
the property. Example:
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.
Last updated