Query Syntax

To filter entities that you wish to get from a server in response to your request, you need to specify the query parameter in the request. Basically, in YouTrack terms, the query parameter represents a search query and it has the same syntax with the adjustment for HTML symbols escaping for URIs. For details about YouTrack search queries, refer to the Search Query Reference page.

Let's see how it works on a sample request for the issues list.

Samples

Request without Query Parameter

First, let's get an unfiltered list of issues, without the query parameter.

Request

curl -X GET \
'https://example.myjetbrains.com/youtrack/api/issues?fields=id,summary,project(name)' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer perm:amFuZS5kb2U=.UkVTVCBBUEk=.wcKuAok8cHmAtzjA6xlc4BrB4hleaX' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json'
      

Response body

In response, the server sends the following:

[
  {
    "project":{
      "name":"Demo Project",
      "$type":"Project"
    },
    "summary":"Welcome to your YouTrack!",
    "id":"2-99",
    "$type":"Issue"
  },
  {
    "project":{
      "name":"Demo Project",
      "$type":"Project"
    },
    "summary":"Create Issues",
    "id":"2-106",
    "$type":"Issue"
  },
  {
    "project":{
      "name":"Sample Project",
      "$type":"Project"
    },
    "summary":"REST API lets you create issues!",
    "id":"2-142",
    "$type":"Issue"
  },
  {
    "project":{
      "name":"Sample Project",
      "$type":"Project"
    },
    "summary":"Issue from REST #1",
    "id":"2-0",
    "$type":"Issue"
  }
]
      

Request with Query Parameter

Now, let's use the query request parameter to filter the list of issues by the name of the project.

Request

curl -X GET \
'https://example.myjetbrains.com/youtrack/api/issues?fields=id,summary,project(name)&query=project:+%7BSample+Project%7D' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer perm:amFuZS5kb2U=.UkVTVCBBUEk=.wcKuAok8cHmAtzjA6xlc4BrB4hleaX' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json'
      

Response body

To the sample request with the query parameter, the response body contains data only for matching issues:

[
  {
    "project":{
      "name":"Sample Project",
      "$type":"Project"
    },
    "summary":"REST API lets you create issues!",
    "id":"2-142",
    "$type":"Issue"
  },
  {
    "project":{
      "name":"Sample Project",
      "$type":"Project"
    },
    "summary":"Issue from REST #1",
    "id":"2-0",
    "$type":"Issue"
  }
]
      

Finally, let's use a bit more complex query. Here, we are looking for issues that are assigned to the user "john.doe", are not yet resolved, and contain the word "summary".

Request

curl -X GET \
'https://example.myjetbrains.com/youtrack/api/issues?fields=id,summary,project(name)&query=for:+john.doe+%23Unresolved+summary' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer perm:amFuZS5kb2U=.UkVTVCBBUEk=.wcKuAok8cHmAtzjA6xlc4BrB4hleaX' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json'
      

Response body

[
  {
    "project":{
      "name":"Sample Project",
      "$type":"Project"
    },
    "summary":"New summary",
    "id":"2-42",
    "$type":"Issue"
  }
]
      

Last modified: 28 October 2020