General request format
General Yandex Tracker API request format:
<method> /v2/<resource_type>/<resource_ID>/?<parameter>=<value>
Host: https://api.tracker.yandex.net
Authorization: OAuth <OAuth_token>
X-Org-ID: <organization ID>
{
Request body in JSON format
}
Python
import requests;
def my_function():
session = requests.Session()
url = "https://https://api.tracker.yandex.net/v2/<resources>/<resource_ID>/?<param>=<value>"
json = {
# Request body in JSON format
}
head = {
"Authorization": "OAuth <OAuth_token>",
"X-Org-ID" or "X-Cloud-Org-ID": <organization_ID>
}
session.headers.update(head)
response = session.post(url, json=json) # session.* - get, post, path, delete
data = response.json()
print(response)
print(data)
my_function()
Note
Yandex Tracker API sends and receives date and time parameters in the UTC±00:00 time zone. Therefore, the time and date received may differ from the time zone of the client that the request is made from.
Methods
Requests made to Tracker API use one of the following HTTP methods:
GET
: Getting information about an object or list of objects.
POST
: Creating an object.
PATCH
: Editing the parameters of an existing object. Requests executed by the PATCH method only change the parameters that are explicitly specified in the request body.
DELETE
: Deleting an object.
Headers
In Tracker API requests, specify the following headers:
-
Host: https://api.tracker.yandex.net
-
Authorization: OAuth <OAuth_token>
: If OAuth 2.0 is used.Authorization: Bearer <IAM token>
: If an IAM token is used. -
X-Org-ID: <organization_ID>
orX-Cloud-Org-ID: <organization_ID>
.If you only have a Yandex Cloud Organization organization, use the
X-Cloud-Org-ID
header; if only Yandex 360 for Business or both organization types, useX-Org-ID
. To find out the organization ID, go to the Tracker settings page . The ID is shown in Organization ID for API. -
Accept-Language: <language tag>
: Localization language.By default, an HTTP request returns localized fields in Russian. To get localized field values in English, specify a header with the en tag.
Request body format
The request body includes a JSON object with the IDs of updated fields and their values.
-
To add or remove an array value, use the
add
orremove
command:-
{ "followers": { "add": ["<employee_1_ID>", "<employee_2_ID>"] } }
The
add
command adds new values to the array. To overwrite the array (delete the old values and add new ones), use theset
command. -
-
To reset the field value, set it to
null
. To reset the array, use an empty array,[]
. You can change individual values in the array using thetarget
andreplacement
commands:{"followers": null}
-
{ "followers": { "replace": [ {"target": "<ID_1>", "replacement": "<ID_2>"}, {"target": "<ID_3>", "replacement": "<ID_4>"}] } }
-
For example, to change the issue type to Error, use one of these methods:
{"type": 1}
{"type": "bug"}
-
{ "type": { "id": "1" } }
-
{ "type": { "name": "Error" } }
-
{ "type": {"set": "bug"} }
Text formats and variables
When making requests for the creation or update of comments, macros, triggers, and auto actions, use the following formatting for the message text:
- To format the text, use the Yandex Flavored Markdown markup.
- To add a line break, use
\n
. - To add values from the issue fields, use variables.
Pagination of results
If you request a list of objects, and the number of rows in the response exceeds 50, the response returns a page with the specified number of results. You can run more requests to view the next pages. This is where pagination of results helps.
If you use pagination, request results are calculated each time a new page is returned. So if changes occur in the request results when viewing a certain page, this may affect the output of the following pages. For example, the request found 11 issues, 10 of which are displayed. While viewing the results of the first page, one of the issues was changed and no longer meets the requirements of the search request. In this case, when requesting the second page with the results, an empty array is returned, since the remaining 10 issues are on the first page.
The new API offers paginated output of request results for events and comments with better customization.
For paginated results, use these parameters in the request:
-
perPage (optional)
Number of objects (issues, queues, and so on) on the page. The default value is 50.
-
page (optional)
Response page number. The default value is 1.
The response will contain the following headers:
-
X-Total-Pages
Total number of pages with entries.
-
X-Total-Count
Total number of entries in the response.
Request examples
Example 1: Change the name, description, type, and priority of an issue.
- An HTTP PATCH method is used.
- We are editing the TEST-1 issue.
- New issue type: Error.
- New issue priority: Low.
PATCH /v2/issues/TEST-1
Host: https://api.tracker.yandex.net
Authorization: OAuth <OAuth_token>
X-Org-ID: <organization ID>
{
"summary": "<new_issue_name>",
"description": "<new_issue_description>",
"type": {
"id": "1",
"key": "bug"
},
"priority": {
"id": "2",
"key": "minor"
}
}
import requests;
def my_function():
session = requests.Session()
url = "https://https://api.tracker.yandex.net/v2/issues/TEST-1"
json = {
"summary": "<new_issue_name>",
"description": "<new_issue_description>",
"type": {
"id": "1",
"key": "bug"
},
"priority": {
"id": "2",
"key": "minor"
}
}
head = {
"Authorization": "OAuth <OAuth_token>",
"X-Org-ID" or "X-Cloud-Org-ID": <organization_ID>
}
session.headers.update(head)
response = session.patch(url, json=json)
data = response.json()
print(response)
print(data)
my_function()
Example 2: Request for a single issue with the required fields specified.
- An HTTP GET method is used.
- The response will display attachments.
GET /v2/issues/JUNE-3?expand=attachments
Host: https://api.tracker.yandex.net
Authorization: OAuth <OAuth token>
X-Org-ID: <organization ID>
import requests;
def my_function():
session = requests.Session()
url = "https://https://api.tracker.yandex.net/v2/issues/JUNE-3?expand=attachments"
head = {
"Authorization": "OAuth <token>",
"X-Org-ID" or "X-Cloud-Org-ID": <organization_ID>
}
session.headers.update(head)
response = session.get(url)
data = response.json()
print(response)
print(data)
my_function()
Example 3: Create an issue.
- An HTTP POST method is used.
- We are creating an issue named Test Issue in the queue with the TREK key.
- The new issue is a sub-issue of JUNE-2.
- New issue type: Error.
- Assignee: <user_login>.
POST /v2/issues/ HTTP/1.1
Host: https://api.tracker.yandex.net
Authorization: OAuth <OAuth_token>
X-Org-ID: <organization ID>
{
"queue": "TREK",
"summary": "Test Issue",
"parent":"JUNE-2",
"type": "bug",
"assignee": "<user_login>",
"attachmentIds": [55, 56]
}
import requests;
def my_function():
session = requests.Session()
url = "https://https://api.tracker.yandex.net/v2/issues/"
json = {
"queue": "TREK",
"summary": "Test Issue",
"parent":"JUNE-2",
"type": "bug",
"assignee": "<user_login>",
"attachmentIds": [55, 56]
}
head = {
"Authorization": "OAuth <token>",
"X-Org-ID" or "X-Cloud-Org-ID": <organization_ID>
}
session.headers.update(head)
response = session.post(url, json=json)
data = response.json()
print(response)
print(data)
my_function()
Example 4: Find the issues in the queue that were assigned to a given employee. Paginate the results.
- An HTTP POST method is used.
- Queue key: TREK.
- Assignee: <user_login>.
POST /v2/issues/_search?perPage=15
Host: https://api.tracker.yandex.net
Authorization: OAuth <OAuth_token>
X-Org-ID: <organization ID>
{
"filter": {
"queue": "TREK",
"assignee": "<user_login>"
}
}
import requests;
def my_function():
session = requests.Session()
url = "https://https://api.tracker.yandex.net/v2/issues/_search?perPage=15"
json = {
"filter": {
"queue": "TREK",
"assignee": "<user_login>"
}
}
head = {
"Authorization": "OAuth <token>",
"X-Org-ID" or "X-Cloud-Org-ID": <organization_ID>
}
session.headers.update(head)
response = session.post(url, json=json)
data = response.json()
print(response)
print(data)
my_function()