Issue search

Currently being removed. Search for issues using JQL (POST)

Changed on

Endpoint is currently being removed. More details

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:

post/rest/api/3/search

Request

  • Base URL
    https://your-domain.atlassian.net
  • URL
    https://your-domain.atlassian.net/rest/api/3/search
  • Auth
    • HTTP basic
    • or OAuth 2
      Authorization code: https://auth.atlassian.com/authorize
      Token URL: https://auth.atlassian.com/oauth/token scopes: read:jira-work
    • or none

Request body

expandstring[]

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.
fieldsstring[]

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.

fieldsByKeysboolean

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

jqlstring

A JQL expression.

maxResultsinteger

The maximum number of items to return per page.

propertiesstring[]

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

startAtinteger

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

validateQuery'strict' | 'warn' | 'none' | 'true' | 'false'

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.

Response

Returned if the request is successful.

expandstring

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

maxResultsinteger

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

namesobject

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

schemaobject

The schema describing the field types in the search results.

startAtinteger

The index of the first item returned on the page.

totalinteger

The number of results on the page.

warningMessagesstring[]

Any warnings related to the JQL query.

Changes

  • 75c9c58763c9Revision changes
    • warning

      added the new product_discovery enum value to the /////////////////// response property for the response status

  • 6abe311e7b55Revision changes
    • info

      endpoint deprecated