General request format

The general format of requests to Yandex Tracker API:

<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
Content-Type: application/json
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 to Tracker API use one of the HTTP methods:

GET — retrieve information about an object or a list of objects;

POST — create an object;

PATCH — modify parameters of an existing object. Requests made using the PATCH method only change the parameters explicitly specified in the request body;

DELETE — delete an object.

Resource

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

• v3 — the current version, which includes all API method updates. It is recommended to use this version for all API requests.
• v2 — the previous version. You can use version v2 in requests, but some new API methods and Tracker object parameters may not be available.

Headers

Include the following headers in requests to Tracker API:

• Host: api.tracker.yandex.net

• Authorization: OAuth <OAuth token> — for OAuth 2.0 protocol access. Learn more in the section Get API access via the OAuth 2.0 protocol.
  Authorization: Bearer <IAM token> — when accessing via an IAM token. Learn more in the section Get API access via 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***.

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

• Content-Type: request body format.

  • application/json — text or data;
  • multipart/form-data — files.

• Accept-Language: <language tag> — localization language.

By default, the HTTP request returns localized fields in Russian. To get values of localized fields in English, specify the header with the en language tag.

Request body format

The request body contains a JSON object with identifiers of the modified task parameters (or other objects) and their values. What is the JSON format

Editing parameters

• To add or remove a value from an array, use the add and remove commands:

  {
      "followers": { "add": ["<employee_id_1>", "<employee_id_2>"] }
  }
  

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

• Individual values in an array can be changed using the target and replacement commands:

  {
    "followers": {
      "replace": [
          {"target": "<id_1>", "replacement": "<id_2>"},
          {"target": "<id_3>", "replacement": "<id_4>"}]
    }
  }
  

• To nullify a field value, specify null.

  {"followers": null}
  

• To refer to standard Tracker objects, such as statuses or issue types, you can use their identifiers, keys, or display names. For example, to change the issue type to “Bug”, use one of the methods:

  • {"type": 1}
    

  • {"type": "bug"}
    

  • {
        "type": { "id": "1" }
    }
    

  • {
        "type": { "name": "Bug" }
    }
    

  • {
        "type": {"set": "bug"}
    }
    

Text format and variables

When working with requests to create or edit descriptions of issues, comments, macros, triggers, and auto actions, use a special format for the message text:

• To format text, use Yandex Flavored Markdown markup.

• To add a line break, use the \n character.

• To insert values from issue fields, use variables. For example:

  • {{issue.<parameter_key>}} — an issue parameter whose value will be substituted for 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.

  Learn more in the Variables section.

Using special characters

When passing string‑type parameters, consider how to handle special characters:

• The ", \, and / characters must be escaped with a backslash \.
• Use the \n or \r characters for a line break.
• Unicode characters can be inserted in the \uFFFF format.

For example, task description text may include double quotes or line break characters:

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

Paginated display 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 make multiple requests to view subsequent pages. This uses the paginated results display mechanism.

With paginated display, query results are recalculated each time a new page is shown. If changes occur in the query results while viewing one page, this may affect how the following pages are displayed. For example, a query returns 11 issues, 10 of which are displayed. While viewing the first page’s results, one of the issues is changed and no longer meets the search query requirements. In this case, requesting the second results page will return an empty array, since the remaining 10 issues will be on the first page.

In the new API for projects, portfolios, and goals (Projects, portfolios, and goals), paginated display of query results for events and comments is available, with more flexible settings:

• Getting entity event history
• Getting comments for the entity

To paginate results, include the following parameters in your request:

• perPage (optional)

  Number of objects (issues, queues, etc.) per page. Default value: 50.

• page (optional)

  Response page number. Default value: 1.

The response will include the following headers:

• X-Total-Pages

  Total number of pages with records.

• X-Total-Count

  Total number of records in the response.

Examples of requests

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

PATCH /v3/issues/TEST-1
Host: api.tracker.yandex.net
Content-Type: application/json
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/
Host: api.tracker.yandex.net
Content-Type: application/json
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
Content-Type: application/json
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()