Labels API

Obtaining the User API token

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. 

Attention! 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. 

 

Obtaining the list of categories

The result of the request is the obtaining of the list of all existing labels categories for the app. 

Request:

https://www.devtodev.com/api/v1/labels/categories/get

POST

{
	"user_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", // devtodev user API token
	"app_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"  // devtodev App ID
}

Response:

{
	"status_code": 200,
	"data": {
		"status": "complete",
		"categories": [
			"category name",
			"category name 2"
		]
	}
}

 

Removing categories

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:

https://www.devtodev.com/api/v1/labels/categories/delete

POST

{
	"user_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
	"app_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
	"category": "category to be removed",
	"move_labels_to_category": "category to which the labels will be moved"
}

Response:

{
	"status_code": 200,
	"data": {
		"status": "deleted",
		"category": "category to be removed"
	}
}

 

Obtaining the list of labels

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:

https://www.devtodev.com/api/v1/labels/get

POST

{
	"user_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
	"app_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
	"filters": {
		"id": {
			"in": [100500, 100501]
		},
		"category": {
			"in": ["category name", "category name 2"]
		},
		"start_date": {
			"gte": 1478625206
		},
		"end_date": {
			"lte": 1478625206
		}
	}
}

Response:

{
	"status_code": 200,
	"data": {
		"status": "complete",
		"labels": [{
			"id": 100500,
			"name": "label name",
			"description": "short label description",
			"category": "category name",
			"start_date": 1478625206,
			"end_date": 1478625206
		}]
	}
}

List of comparison operators that can be applied in a filter

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.

 

Adding labels

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:

https://www.devtodev.com/api/v1/labels/add

POST

{
	"user_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
	"app_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
	"labels": [{
		"name": "label name",
		"description": "short label description",
		"category": "category name",
		"start_date": 1478625206,
		"end_date": 1478625206
	}]
}

Response:

{
	"status_code": 201,
	"data": {
		"status": "created",
		"labels": [{
			"id": 100500,
			"name": "label name",
			"description": "short label description",
			"category": "category name",
			"start_date": 1478625206,
			"end_date": 1478625206
		}]
	}
}

 

Editing labels 

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:

https://www.devtodev.com/api/v1/labels/edit

POST

{
	"user_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
	"app_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
	"id": 100500,
	"name": "label name",
	"description": "short label description",
	"category": "category name",
	"start_date": 1478625206,
	"end_date": 1478625206
}

Response:

{
	"status_code": 200,
	"data": {
		"status": "complete",
		"labels": [{
			"id": 100500,
			"name": "label name",
			"description": "short label description",
			"category": "category name",
			"start_date": 1478625206,
			"end_date": 1478625206
		}]
	}
}

 

Deleting labels

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:

https://www.devtodev.com/api/v1/labels/delete

POST

{
	"user_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
	"app_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
	"ids": [100500, 100501]
}

Response:

{
	"status_code": 200,
	"data": {
		"status": "deleted",
		"labels": [{
			"id": 100500,
			"name": "label name",
			"description": "short label description",
			"category": "category name",
			"start_date": 1478625206,
			"end_date": 1478625206
		}]
	}
}

 

Error handling

In case there is an error in a request, the response is made in the following format:

{
	"status_code": 500,
	"errors": [{
		"code": 3,
		"msg": "Malformed json"
	}]
}

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.

 

List of possible errors

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.

 

Limitations

Limitations on the lenght of values

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

Limitations on the number of actions 

  • 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
Push sending (old)
Analytics Integration