General query format

General Yandex Tracker API query format:

<method> /v2/<resources>/<resource_id>/?<param>=<value>
Host: https://api.tracker.yandex.net
Authorization: OAuth <token>
X-Org-ID: <organization ID>
{
   Request body in JSON format
} 

Methods

Tracker API queries use one of the following HTTP methods:

GET: Get information about an object or list of objects.

POST: Create an object.

PATCH: Change the parameters of an existing object. Requests sent via the PATCH method only change the parameters explicitly specified in the request body.

DELETE: Delete an object.

Headers

In requests to the Tracker API API, specify the following headers:

• Host: https://api.tracker.yandex.net

• Authorization: OAuth <your OAuth token>: If the OAuth 2.0 protocol is used.

  Authorization: Bearer <your IAM token>: If an IAM token is used.

• X-Org-ID: <organization ID>

  To find out the organization ID, go to the Tracker settings. The ID is shown in Organization ID for API.

Request body format

The request body passes 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": ["<id user1>", "<id user2>"] }
    }
    

  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. TTo 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": "<ID1>", "replacement": "<ID2>"},
            {"target": "<ID3>", "replacement": "<ID4>"}]
      }
    }
    

• For example, to change the issue type to Bug, use one of these methods:

  • {"type": 1}
  • {"type": "bug"}

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

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

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

Text formatting and variables

When handling requests for adding or editing comments, macros, triggers, and auto actions, use special text formatting:

• To format text, use the dedicated markup Yandex Flavored Markdown.
• To add a line break, enter \n.
• To add values from issue fields, use variables.

Paginated result output

If you request an object list and the response contains more than 50 lines, the request returns a page with the specified number of results. You can make multiple requests to view subsequent pages. To do this, use paginated display.

With paginated display, the request results are calculated each time a new page is displayed. 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 query. 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.

To enable paginated display, use the following parameters in the request:

• perPage (optional)

  The number of objects (issues, queues, and so on) on the page. Default: 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.

Examples of requests

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

GET /v2/issues/JUNE-3?expand=attachments
Host: https://api.tracker.yandex.net
Authorization: OAuth <OAuth token>
X-Org-ID: <organization ID>

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

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