---
metadata:
  - name: generator
    content: Diplodoc Platform v5.54.2
  - property: og:type
    content: article
  - property: article:section
    content: Справочник API
  - property: og:title
    content: Общий формат запросов
  - property: article:tag
    content: Техническая инструкция
alternate:
  - https://yandex.ru/support/tracker/en/api-ref/common-format.md
  - https://yandex.ru/support/tracker/ru/api-ref/common-format.md
  - href: en/api-ref/common-format.md
    type: text/markdown
    title: Markdown version
  - href: ../llms.txt
    type: text/markdown
    title: llms.txt
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.ru/support/tracker/en/llms.txt


# 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>
```

{% cut "Request structure" %}

```
<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
}
```
{% endcut %}

{% cut "Python" %}

```python
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()
```

{% endcut %}

{% note info "" %}

Yandex Tracker API sends and receives date and time parameters in the UTC±00:00 time zone. Therefore, the received time and date may differ from the client’s time zone from which the request is made.

{% endnote %}

## Methods {#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 {#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 {#headings}

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](https://yandex.ru/support/tracker/en/api-ref/access.md#about_OAuth).
  `Authorization: Bearer <IAM token>` — when accessing via an IAM token. Learn more in the section [Get API access via IAM token](https://yandex.ru/support/tracker/en/api-ref/access.md#iam-token).

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

* <!-- source: en/api-ref/_includes/org-id.md -->
  `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 Identity Hub.

  To get the organization ID, go to **Administration** → [**Organizations**](https://tracker.yandex.com/admin/orgs) and copy the value from the **ID** field. {#find-id}
  <!-- endsource: en/api-ref/_includes/org-id.md -->


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

  <!-- source: en/api-ref/_includes/org-id.md -->
  To get the organization ID, go to **Administration** → [**Organizations**](https://tracker.yandex.com/admin/orgs) and copy the value from the **ID** field. {#find-id}
  <!-- endsource: en/api-ref/_includes/org-id.md -->


* `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 {#body}

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](https://en.wikipedia.org/wiki/JSON)

### Editing parameters {#edit-fields}

- To add or remove a value from an array, use the `add` and `remove` commands:
  ```json
  {
      "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:

  ```json
  {
    "followers": {
      "replace": [
          {"target": "<id_1>", "replacement": "<id_2>"},
          {"target": "<id_3>", "replacement": "<id_4>"}]
    }
  }
  ```
- To nullify a field value, specify `null`.

  ```json translate=no
  {"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:

  - ```json translate=no
    {"type": 1}
    ```
  - ```json translate=no
    {"type": "bug"}
    ```
  - ```json translate=no
    {
        "type": { "id": "1" }
    }
    ```
  - ```json translate=no
    {
        "type": { "name": "Bug" }
    }
    ```
  - ```json translate=no
    {
        "type": {"set": "bug"}
    }
    ```

### Text format and variables {#text-format}

When working with requests to create or edit descriptions of [issues](https://yandex.ru/support/tracker/en/api-ref/issues/create-issue.md), [comments](https://yandex.ru/support/tracker/en/api-ref/issues/add-comment.md), [macros](https://yandex.ru/support/tracker/en/api-ref/post-macros.md), [triggers](https://yandex.ru/support/tracker/en/api-ref/queues/create-trigger.md), and [auto actions](https://yandex.ru/support/tracker/en/api-ref/queues/create-autoaction.md), use a special format for the message text:
* To format text, use [Yandex Flavored Markdown markup](https://yandex.com/support/tracker/user/markup.html).
* 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](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](https://yandex.com/support/tracker/user/vars.html) section.

### Using special characters {#str-escape}

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:


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

## Paginated display of results {#displaying-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](https://yandex.ru/support/tracker/en/api-ref/entities/about-entities.md)), paginated display of query results for events and comments is available, with more flexible settings:
* [Getting entity event history](https://yandex.ru/support/tracker/en/api-ref/entities/get-events-relative.md)
* [Getting comments for the entity](https://yandex.ru/support/tracker/en/api-ref/entities/comments/get-all-comments.md)


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 {#examples}

{% cut "Example 1: Change the issue name, description, type, and priority." %}

- The PATCH HTTP method is used.
- Issue TEST‑1 is being edited.
- New issue type: "Bug".
- New issue priority: "Minor".

<div class="request_example method_patch yfm-clipboard">
    <p>PATCH</p>
    <pre><code>https://api.tracker.yandex.net/v3/issues/TEST-1</code></pre>
    <button class="yfm-clipboard-button"><svg width="16" height="16" viewBox="0 0 24 24" class="yfm-clipboard-icon" data-animation="15">
    <path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path>
    <path stroke="currentColor" fill="transparent" strokewidth="1.5" d="M9.5 13l3 3l5 -5" visibility="hidden">
        <animate id="visibileAnimation-15" attributeName="visibility" from="hidden" to="visible" dur="0.2s" fill="freeze" begin=""></animate>
        <animate id="hideAnimation-15" attributeName="visibility" from="visible" to="hidden" dur="1s" begin="visibileAnimation-15.end+1" fill="freeze"></animate>
    </path>
</svg>
</button>
</div>

<!-- source: en/api-ref/_assets/style/methods.md -->

<!-- endsource: en/api-ref/_assets/style/methods.md -->

{% list tabs %}

- Request format

  ```json translate=no
  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"
        }
  }
  ```

- Python

  ```python
  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()
  ```

{% endlist %}

{% endcut %}

{% cut "Example 2: Retrieve a single issue with specified fields." %}

- The GET HTTP method is used.
- The response includes attachment display.

<div class="request_example method_get yfm-clipboard">
  <p>GET</p>
  <pre><code>https://api.tracker.yandex.net/v3/issues/JUNE-3?expand=attachments</code></pre>
    <button class="yfm-clipboard-button"><svg width="16" height="16" viewBox="0 0 24 24" class="yfm-clipboard-icon" data-animation="15">
    <path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path>
    <path stroke="currentColor" fill="transparent" strokewidth="1.5" d="M9.5 13l3 3l5 -5" visibility="hidden">
        <animate id="visibileAnimation-15" attributeName="visibility" from="hidden" to="visible" dur="0.2s" fill="freeze" begin=""></animate>
        <animate id="hideAnimation-15" attributeName="visibility" from="visible" to="hidden" dur="1s" begin="visibileAnimation-15.end+1" fill="freeze"></animate>
    </path>
</svg>
</button>
</div>

{% list tabs %}

- Request format

  ```
  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>
  ```

- Python

  ```python
  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()
  ```

{% endlist %}

{% endcut %}

{% cut "Example 3: Create an issue." %}

- The POST HTTP method is used.
- An issue titled "Test Issue" is created in the queue with the [key](*queuekey) "TREK".
- The new issue is a sub‑issue of "JUNE‑2".
- The issue type is "Bug".
- The issue assignee is <user_login>

<div class="request_example method_post yfm-clipboard">
    <p>POST</p>
    <pre><code>https://api.tracker.yandex.net/v3/issues/</code></pre>
    <button class="yfm-clipboard-button"><svg width="16" height="16" viewBox="0 0 24 24" class="yfm-clipboard-icon" data-animation="15">
    <path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path>
    <path stroke="currentColor" fill="transparent" strokewidth="1.5" d="M9.5 13l3 3l5 -5" visibility="hidden">
        <animate id="visibileAnimation-15" attributeName="visibility" from="hidden" to="visible" dur="0.2s" fill="freeze" begin=""></animate>
        <animate id="hideAnimation-15" attributeName="visibility" from="visible" to="hidden" dur="1s" begin="visibileAnimation-15.end+1" fill="freeze"></animate>
    </path>
</svg>
</button>
</div>

{% list tabs %}

- Request format

  ```json
  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]
  }
  ```

- Python

  ```python
  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()
  ```

{% endlist %}

{% endcut %}

{% cut "Example 4: Find queue issues assigned to a specific employee. Display results page by page." %}

- The POST HTTP method is used.
- Queue key: "TREK".
- Issue assignee: <user_login>.

<div class="request_example method_post yfm-clipboard">
    <p>POST</p>
    <pre><code>https://api.tracker.yandex.net/v3/issues/_search?perPage=15</code></pre>
    <button class="yfm-clipboard-button"><svg width="16" height="16" viewBox="0 0 24 24" class="yfm-clipboard-icon" data-animation="15">
    <path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path>
    <path stroke="currentColor" fill="transparent" strokewidth="1.5" d="M9.5 13l3 3l5 -5" visibility="hidden">
        <animate id="visibileAnimation-15" attributeName="visibility" from="hidden" to="visible" dur="0.2s" fill="freeze" begin=""></animate>
        <animate id="hideAnimation-15" attributeName="visibility" from="visible" to="hidden" dur="1s" begin="visibileAnimation-15.end+1" fill="freeze"></animate>
    </path>
</svg>
</button>
</div>

{% list tabs %}

- Request format

  ```json
  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>"
    }
  }
  ```

- Python

  ```python
  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()
  ```

{% endlist %}

{% endcut %}

[*queuekey]: A queue key is a unique code for a queue consisting of Latin characters, for example `TEST`. The key is contained in the link to the queue and its issues, and you need to specify it in API requests and auto action settings. You can't change the key after creating the queue.