JIRA 7.6.1

Search for issues using JQL (POST)

POST

/rest/api/3/search

Issue search

Searches for issues using JQL.

There is a GET version of this resource that can be used for smaller JQL query expressions.

This operation can be accessed anonymously.

Permissions required: Issues are included in the response where the user has:

Browse projects project permission for the project containing the issue.

If issue-level security is configured, issue-level security permission to view the issue.

Request Example

Shell

JavaScript

Java

Swift

curl --location --request POST 'http://jira.local:8080/jira/rest//rest/api/3/search' \
--header 'Content-Type: application/json' \
--data-raw '{
    "expand": [
        "names",
        "schema",
        "operations"
    ],
    "fields": [
        "summary",
        "status",
        "assignee"
    ],
    "fieldsByKeys": false,
    "jql": "project = HSP",
    "maxResults": 15,
    "startAt": 0
}'

Response Example

200 - Success

{
  "expand": "names,schema",
  "startAt": 0,
  "maxResults": 50,
  "total": 1,
  "issues": [
    {
      "expand": "",
      "id": "10002",
      "self": "https://your-domain.atlassian.net/rest/api/3/issue/10002",
      "key": "ED-1",
      "fields": {
        "watcher": {
          "self": "https://your-domain.atlassian.net/rest/api/3/issue/EX-1/watchers",
          "isWatching": false,
          "watchCount": 1,
          "watchers": [
            {
              "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g",
              "accountId": "5b10a2844c20165700ede21g",
              "displayName": "Mia Krystof",
              "active": false
            }
          ]
        },
        "attachment": [
          {
            "id": 10000,
            "self": "https://your-domain.atlassian.net/rest/api/3/attachments/10000",
            "filename": "picture.jpg",
            "author": {
              "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g",
              "key": "",
              "accountId": "5b10a2844c20165700ede21g",
              "accountType": "atlassian",
              "name": "",
              "avatarUrls": {
                "48x48": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48",
                "24x24": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24",
                "16x16": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16",
                "32x32": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32"
              },
              "displayName": "Mia Krystof",
              "active": false
            },
            "created": "2023-07-12T06:03:00.833+0000",
            "size": 23123,
            "mimeType": "image/jpeg",
            "content": "https://your-domain.atlassian.net/jira/rest/api/3/attachment/content/10000",
            "thumbnail": "https://your-domain.atlassian.net/jira/rest/api/3/attachment/thumbnail/10000"
          }
        ],
        "sub-tasks": [
          {
            "id": "10000",
            "type": {
              "id": "10000",
              "name": "",
              "inward": "Parent",
              "outward": "Sub-task"
            },
            "outwardIssue": {
              "id": "10003",
              "key": "ED-2",
              "self": "https://your-domain.atlassian.net/rest/api/3/issue/ED-2",
              "fields": {
                "status": {
                  "iconUrl": "https://your-domain.atlassian.net/images/icons/statuses/open.png",
                  "name": "Open"
                }
              }
            }
          }
        ],
        "description": {
          "type": "doc",
          "version": 1,
          "content": [
            {
              "type": "paragraph",
              "content": [
                {
                  "type": "text",
                  "text": "Main order flow broken"
                }
              ]
            }
          ]
        },
        "project": {
          "self": "https://your-domain.atlassian.net/rest/api/3/project/EX",
          "id": "10000",
          "key": "EX",
          "name": "Example",
          "avatarUrls": {
            "48x48": "https://your-domain.atlassian.net/secure/projectavatar?size=large&pid=10000",
            "24x24": "https://your-domain.atlassian.net/secure/projectavatar?size=small&pid=10000",
            "16x16": "https://your-domain.atlassian.net/secure/projectavatar?size=xsmall&pid=10000",
            "32x32": "https://your-domain.atlassian.net/secure/projectavatar?size=medium&pid=10000"
          },
          "projectCategory": {
            "self": "https://your-domain.atlassian.net/rest/api/3/projectCategory/10000",
            "id": "10000",
            "name": "FIRST",
            "description": "First Project Category"
          },
          "simplified": false,
          "style": "classic",
          "insight": {
            "totalIssueCount": 100,
            "lastIssueUpdateTime": "2023-07-12T06:03:00.831+0000"
          }
        },
        "comment": [
          {
            "self": "https://your-domain.atlassian.net/rest/api/3/issue/10010/comment/10000",
            "id": "10000",
            "author": {
              "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g",
              "accountId": "5b10a2844c20165700ede21g",
              "displayName": "Mia Krystof",
              "active": false
            },
            "body": {
              "type": "doc",
              "version": 1,
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque eget venenatis elit. Duis eu justo eget augue iaculis fermentum. Sed semper quam laoreet nisi egestas at posuere augue semper."
                    }
                  ]
                }
              ]
            },
            "updateAuthor": {
              "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g",
              "accountId": "5b10a2844c20165700ede21g",
              "displayName": "Mia Krystof",
              "active": false
            },
            "created": "2021-01-17T12:34:00.000+0000",
            "updated": "2021-01-18T23:45:00.000+0000",
            "visibility": {
              "type": "role",
              "value": "Administrators",
              "identifier": "Administrators"
            }
          }
        ],
        "issuelinks": [
          {
            "id": "10001",
            "type": {
              "id": "10000",
              "name": "Dependent",
              "inward": "depends on",
              "outward": "is depended by"
            },
            "outwardIssue": {
              "id": "10004L",
              "key": "PR-2",
              "self": "https://your-domain.atlassian.net/rest/api/3/issue/PR-2",
              "fields": {
                "status": {
                  "iconUrl": "https://your-domain.atlassian.net/images/icons/statuses/open.png",
                  "name": "Open"
                }
              }
            }
          },
          {
            "id": "10002",
            "type": {
              "id": "10000",
              "name": "Dependent",
              "inward": "depends on",
              "outward": "is depended by"
            },
            "inwardIssue": {
              "id": "10004",
              "key": "PR-3",
              "self": "https://your-domain.atlassian.net/rest/api/3/issue/PR-3",
              "fields": {
                "status": {
                  "iconUrl": "https://your-domain.atlassian.net/images/icons/statuses/open.png",
                  "name": "Open"
                }
              }
            }
          }
        ],
        "worklog": [
          {
            "self": "https://your-domain.atlassian.net/rest/api/3/issue/10010/worklog/10000",
            "author": {
              "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g",
              "accountId": "5b10a2844c20165700ede21g",
              "displayName": "Mia Krystof",
              "active": false
            },
            "updateAuthor": {
              "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g",
              "accountId": "5b10a2844c20165700ede21g",
              "displayName": "Mia Krystof",
              "active": false
            },
            "comment": {
              "type": "doc",
              "version": 1,
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "I did some work here."
                    }
                  ]
                }
              ]
            },
            "updated": "2021-01-18T23:45:00.000+0000",
            "visibility": {
              "type": "group",
              "value": "jira-developers",
              "identifier": "276f955c-63d7-42c8-9520-92d01dca0625"
            },
            "started": "2021-01-17T12:34:00.000+0000",
            "timeSpent": "3h 20m",
            "timeSpentSeconds": 12000,
            "id": "100028",
            "issueId": "10002"
          }
        ],
        "updated": 1,
        "timetracking": {
          "originalEstimate": "10m",
          "remainingEstimate": "3m",
          "timeSpent": "6m",
          "originalEstimateSeconds": 600,
          "remainingEstimateSeconds": 200,
          "timeSpentSeconds": 400
        }
      }
    }
  ],
  "warningMessages": [
    "The value 'bar' does not exist for the field 'foo'."
  ]
}

Request

Body Params application/json

expand

array[string]

optional

Use expand to include additional information about issues in the response. Note that, unlike the majority of instances where expand is specified, expand is defined as a list of values. The expand options are:

renderedFields Returns field values rendered in HTML format.

names Returns the display name of each field.

schema Returns the schema describing a field type.

transitions Returns all possible transitions for the issue.

operations Returns all possible operations for the issue.

editmeta Returns information about how each field can be edited.

changelog Returns a list of recent updates to an issue, sorted by date, starting from the most recent.

versionedRepresentations Instead of fields, returns versionedRepresentations a JSON array containing each version of a field's value, with the highest numbered item representing the most recent version.

fields

array[string]

optional

A list of fields to return for each issue, use it to retrieve a subset of fields. This parameter accepts a comma-separated list. Expand options include:

*all Returns all fields.

*navigable Returns navigable fields.

Any issue field, prefixed with a minus to exclude.

The default is *navigable.

Examples:

summary,comment Returns the summary and comments fields only.

-description Returns all navigable (default) fields except description.

*all,-comment Returns all fields except comments.

Multiple fields parameters can be included in a request.

Note: All navigable fields are returned by default. This differs from GET issue where the default is all fields.

fieldsByKeys

boolean

optional

Reference fields by their key (rather than ID). The default is false.

jql

string

optional

A JQL expression.

maxResults

integer <int32>

optional

The maximum number of items to return per page.

Default:

properties

array[string]

optional

A list of up to 5 issue properties to include in the results. This parameter accepts a comma-separated list.

startAt

integer <int32>

optional

The index of the first item to return in the page of results (page offset). The base index is 0.

validateQuery

enum<string>

optional

Determines how to validate the JQL query and treat the validation results. Supported values:

strict Returns a 400 response code if any errors are found, along with a list of all errors (and warnings).

warn Returns all errors as warnings.

none No validation is performed.

true Deprecated A legacy synonym for strict.

false Deprecated A legacy synonym for warn.

The default is strict.

Note: If the JQL is not correctly formed a 400 response code is returned, regardless of the validateQuery value.

Allowed values:

strictwarnnonetruefalse

Examples

Responses

🟢200Returned if the request is successful.

application/json

Body

The result of a JQL search.

expand

string

read-onlyoptional

Expand options that include additional search result details in the response.

issues

array[object (IssueBean) {15}]

read-onlyoptional

The list of issues found by the search.

changelog

object

read-onlyoptional

Details of changelogs associated with the issue.

editmeta

object

read-onlyoptional

The metadata for the fields on the issue that can be amended.

expand

string

read-onlyoptional

Expand options that include additional issue details in the response.

fields

object

optional

fieldsToInclude

object (IncludedFields)

optional

string

read-onlyoptional

The ID of the issue.

key

string

read-onlyoptional

The key of the issue.

names

object

read-onlyoptional

The ID and name of each field present on the issue.

operations

allOf {1}

read-onlyoptional

The operations that can be performed on the issue.

properties

object

read-onlyoptional

Details of the issue properties identified in the request.

renderedFields

object

read-onlyoptional

The rendered value of each field present on the issue.

schema

object

read-onlyoptional

The schema describing each field present on the issue.

self

string <uri>

read-onlyoptional

The URL of the issue details.

transitions

array[object (IssueTransition) {12}]

read-onlyoptional

The transitions that can be performed on the issue.

versionedRepresentations

object

read-onlyoptional

The versions of each field on the issue.

maxResults

integer <int32>

read-onlyoptional

The maximum number of results that could be on the page.

names

object

read-onlyoptional

The ID and name of each field in the search results.

Additional properties

string

read-onlyoptional

schema

object

read-onlyoptional

The schema describing the field types in the search results.

Additional properties

object (JsonTypeBean)

optional

The schema of a field.

startAt

integer <int32>

read-onlyoptional

The index of the first item returned on the page.

total

integer <int32>

read-onlyoptional

The number of results on the page.

warningMessages

array[string]

read-onlyoptional

Any warnings related to the JQL query.

🟠400Returned if the JQL query is invalid.

🟠401Returned if the authentication credentials are incorrect or missing.

Modified at 2023-07-13 03:27:27

Search for issues using JQL (GET)

Bulk set issues properties by list