Common request format

General Yandex Tracker API request format:

<method> https://api.tracker.yandex.net/v3/<resource_type>/<resource_ID>/?<parameter>=<value>

<method> /v3/<resource_type>/<resource_ID>/?<parameter>=<value>
Host: api.tracker.yandex.net
Authorization: OAuth <OAuth_token>
X-Org-ID or X-Cloud-Org-ID: <organization_ID>

{
   Request body in JSON format
}

import requests;

def my_function():
    session = requests.Session()
    url = "https://api.tracker.yandex.net/v3/<resources>/<resource_id>/?<param>=<value>"
    json = {
        # Request body in JSON format
    }
    head =  {
        "Authorization": "OAuth <OAuth_token>",
        "X-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()

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.

Resource

The resource address in the request states the Yandex Tracker API version:

• v3: The current version that provides access to all API method updates. We recommend using this version for all API requests.

• v2: The previous version. You can use v2 in requests, but new API methods and Yandex Tracker object parameters may be unavailable.

Headers

In Tracker API requests, specify the following headers:

• Host: api.tracker.yandex.net

• Authorization: OAuth <OAuth_token>: If OAuth 2.0 is used. For more information, see Getting access to the API via OAuth 2.0.

  Authorization: Bearer <IAM_token>: If an IAM token is used. For more information, see Access the API with an IAM token.

  For example: Authorization: Bearer t1.ab123cd45*****************.

• X-Org-ID or X-Cloud-Org-ID: Organization ID.

  • Use the X-Org-ID header if a Tracker organization is linked to Yandex 360 for Business.

  • Use the X-Cloud-Org-ID header if a Tracker organization is linked to Yandex Cloud Organization.

  To get the organization ID, go to Administration → Organizations and copy the value from the ID field.

  For example: X-Org-ID: 1234***.

  For more information, see Getting access to the API via OAuth 2.0.

• 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 issue parameters (or other objects) and their values.

Editing parameters

• To add or remove an array value, use the add or remove command:

  {
      "followers": { "add": ["<employee_1_ID>", "<employee_2_ID>"] }
  }
  

• To overwrite the array (delete the old values and add new ones), use the set command. To reset the array, use an empty array, [].

• You can change individual values in the array using the target and replacement commands:

  {
    "followers": {
      "replace": [
          {"target": "<ID_1>", "replacement": "<ID_2>"},
          {"target": "<ID_3>", "replacement": "<ID_4>"}]
    }
  }
  

• To reset the field value, set it to null.

  {"followers": null}`
  

• To reference standard Yandex Tracker objects, such as issue statuses or types, you can use their IDs, keys, or display names. 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 to create or update issue descriptions, comments, macros, triggers, and auto actions, use a specific format 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. For example:

  • {{issue.<ключ_parameterа>}}: Issue parameter whose value replaces the variable. Full list of issue parameters: https://tracker.yandex.com/admin/fields.
  • {{currentUser}}: The current user's name, for example, when running a macro.
  • {{currentDateTime.date}}: Current date.
  • {{currentDateTime}}: Current date and time.

  For more information, see Variables.

Using special characters

When passing string parameters, make sure that you correctly handle these characters:

• You must escape the ", \, and / characters with a backslash (\).
• Use \n or \r for line breaks.
• You can insert Unicode characters using the \uFFFF format.

For example, an issue description may contain double quotes or line break characters:

{
  "description": "Make the following fixes:\n1. Use value \"1\" instead of value \"2\"."
}

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. If something changes in the request results while you're viewing a certain page, it could change how the next pages look. 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

https://api.tracker.yandex.net/v3/issues/TEST-1

PATCH /v3/issues/TEST-1
Host: api.tracker.yandex.net
Authorization: OAuth <OAuth_token>
X-Org-ID or X-Cloud-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://api.tracker.yandex.net/v3/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": <organization_ID>
    }
    session.headers.update(head)
    response = session.patch(url, json=json)
    data = response.json()
    print(response)
    print(data)

my_function()

https://api.tracker.yandex.net/v3/issues/JUNE-3?expand=attachments

GET /v3/issues/JUNE-3?expand=attachments
Host: api.tracker.yandex.net
Authorization: OAuth <OAuth_token>
X-Org-ID or X-Cloud-Org-ID: <organization_ID>

import requests;

def my_function():
    session = requests.Session()
    url = "https://api.tracker.yandex.net/v3/issues/JUNE-3?expand=attachments"
    head =  {
        "Authorization": "OAuth <token>",
        "X-Org-ID": <organization_ID>
    }
    session.headers.update(head)
    response = session.get(url)
    data = response.json()
    print(response)
    print(data)

my_function()

https://api.tracker.yandex.net/v3/issues/

POST /v3/issues/ HTTP/1.1
Host: api.tracker.yandex.net
Authorization: OAuth <OAuth_token>
X-Org-ID or X-Cloud-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://api.tracker.yandex.net/v3/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": <organization_ID>
    }
    session.headers.update(head)
    response = session.post(url, json=json)
    data = response.json()
    print(response)
    print(data)

my_function()

https://api.tracker.yandex.net/v3/issues/_search?perPage=15

POST /v3/issues/_search?perPage=15
Host: api.tracker.yandex.net
Authorization: OAuth <OAuth_token>
X-Org-ID or X-Cloud-Org-ID: <organization_ID>
{
  "filter": {
    "queue": "TREK",
    "assignee": "<user_login>"
  }
}

import requests;

def my_function():
    session = requests.Session()
    url = "https://api.tracker.yandex.net/v3/issues/_search?perPage=15"
    json = {
        "filter": {
            "queue": "TREK",
            "assignee": "<user_login>"
            }
        }
    head =  {
        "Authorization": "OAuth <token>",
        "X-Org-ID": <organization_ID>
    }
    session.headers.update(head)
    response = session.post(url, json=json)
    data = response.json()
    print(response)
    print(data)

my_function()