Labels API
Last updated
Last updated
In order to be able to use Labels API you must have an individual User API token, which can be found in space settings in devtodev system.
You will be able to see the interface unit with User API token in space settings only in case your price plan and access rights (role) allow you to use devtodev API. You can discard User API token or create it again on the same page.
Pay your attention that if you use several spaces, each of them will have an individual User API token.
The result of the request is the obtaining of the list of all existing labels categories for the app.
Request:
POST
Response:
The request is used to remove or rename a category. The category can be removed only if its full name is specified. One request can remove only one category. In case the parameter move_labels_to_category is specified, labels that belong to the category that is going to be removed will be transfered to the specified category. If the specified category doesn't exist, it will be created. If move_labels_to_category is not specified, all the labels that belong to the category will be removed.
Request:
POST
Response:
The result of the request is the obtaining of the list of labels that are presented as objects.
You can use filters to get some specific labels you need. In case no filter is specified, you will receive the whole list of labels. It is possible to use any combination of fields in a filter.
Request:
POST
Response:
The filter can be described with an object, where the following comparison operators can be the properties:
API operator | Math operator | Description |
gt | > | Greater than |
lt | < | Less than |
eq | = | Equal |
gte | >= | Greater than or equal |
lte | <= | Less than or equal |
neq | != | Not equal |
eq | In the list | |
neq | Not in the list |
The empty object describes the filter that selects all the events in which the parameter value is not null or empty string.
In case the specified category doesn't exist, it will be created. If string values of fields exceed the maximum, they will be cut off.
If you need to specify an event without time length, start_date must be equal to end_date or end_date must not be specified.
Request:
POST
Response:
To edit a label you need to specify its identifier (id). All the specified fields for the label will be replaced. In case the specified category doesn't exist, it will be created.
If it is necessary to change the dates of an event, you must specify start_date. It is impossible to specify end_date without specifying start_date. If the label is used in relation to a continuous event (start_data and end_date are different timestamps), but in an edited version only the start_date is received, the label becomes a point that characterizes an instant event.
Request:
POST
Response:
The request is used to delete one or several labels. To delete a label its identifier is required. The request without specified identifiers is not valid.
Request:
POST
Response:
Error handling
In case there is an error in a request, the response is made in the following format:
where
status_code (number) - the general status of an error
errors (array) - an array of error descriptions
code (number) - the exact code of an error from the table of errors
msg (string) - a brief description of an error
The list of possible errors is given in a table.
Status code | Code | Value of "msg" field | Error description |
500 | 1 | Unknown Error | Unknown error. In case it repeats, please contact technical support. |
400 | 2 | Request body is empty | Request body is empty. There is no POST data in the request. |
400 | 3 | Malformed json | There is an error of JSON format in the request body. Fix the error of format. |
400 | 4 | Field not found: %field_name% | The required field is not specified in the request. Please add it to the request. |
400 | 5 | Field %field_name% has type %received_type% but %expected_type% expected | The type of data doesn't match the expected type. Follow the recommendation and change the data type to the expected one. It is possible to use the following types of data: boolean, integer, float, number (integer+float), string. |
400 | 6 | Invalid app id %app id value% | The requested app is not found. The app is unknown. The error can appear in case the specified app identifier is wrong or when the app has been removed. |
401 | 11 | Authorization error. Wrong user token %user_token value% | Authorization error. The specified User API token is wrong. Check the value of the specified key. |
401 | 12 | Authorization error. User_token is not set. | Authorization error. User API token is not specified in the request parameters. It is necessary to specify User API token ("user_token" field) in every request. |
403 | 13 | Access denied. You have no access to the app %app id value% | Access error. The owner specified in the User API token request has no access rights to the app specified in the same request. |
403 | 15 | Access denied. You have no access to API. | Access error. You have no access to devtodev API. The error can appear when User API token owner's access rights to the service API are changed as a result of the change of the user's role or the change of the price plan. |
403 | 23 | Access denied. You have no access to Labels API. | Access error. The error can appear in case the User API token owner has no access to the Labels API service due to the limitations of the user's role or limitations of the price plan of the space. |
400 | 28 | Unexpected value for field %field%. Received value: %value%. Expected values: %values%. | Unexpected value for the field. Follow the recommendations and correct the request. |
400 | 29 | Unexpected field %field% | The request contains the field that is not specified in the documentation. The field must be excluded from the request. |
400 | 30 | Invalid value for field %field%. Received value: %value%. Expected: %description% | Invalid value has been attributed to the field. Follow the recommendations and correct the request. |
404 | 34 | No results matched the request | The requested data is missing. |
429 | 35 | Quota exceeded. %% new labels per day per application quota has been exceeded. | The daily limit is exceeded. Tomorrow you will be able to add labels to the app again. |
400 | 37 | New labels array should not contain more than %% elements. | The array of labels contains more than 30 elements. Reduce the number of labels created in one request. |
429 | 36 | Quota exceeded. %% new labels per day per user quota has been exceeded. | The daily limit is exceeded. You will be able to add a new set of labels tomorrow. |
400 | 38 | Labels feature is not available for cross-platform projects | The labels feature is not available for cross-platform projects. Labels can be applied only to ordinary apps or branch-apps of cross-platform projects. |
Name | Field | Limitation |
Label name | name | not more than 10 symbols |
Short description of a label | description | not more than 512 symbols |
Category name | category | not more than 30 symbols |
Not more than 30 labels in one request on labels creation
Not more than 500 labels to be created in a calendar day for User API token
Not more than 200 labels to be created in a calendar day for an app
