Contact UsGet started
© 2024 Direct Cursus Technology L.L.C.

General request format

Written by
Updated at February 19, 2024

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> or X-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, use X-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 or remove 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 the set 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 the target and replacement 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:

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()
Previous
API access
Next
Getting issue parameters