jql

get-auto-complete

Get field reference data (GET)

Returns reference data for JQL searches. This is a downloadable version of the documentation provided in Advanced searching - fields reference and Advanced searching - functions reference, along with a list of JQL-reserved words. Use this information to assist with the programmatic creation of JQL queries or the validation of queries built in a custom query builder.

To filter visible field details by project or collapse non-unique fields by field type then Get field reference data (POST) can be used.

This operation can be accessed anonymously.

Permissions required: None.

GET /rest/api/3/jql/autocompletedata

Example:

jr jql get-auto-complete

get-auto-complete-post

Get field reference data (POST)

Returns reference data for JQL searches. This is a downloadable version of the documentation provided in Advanced searching - fields reference and Advanced searching - functions reference, along with a list of JQL-reserved words. Use this information to assist with the programmatic creation of JQL queries or the validation of queries built in a custom query builder.

This operation can filter the custom fields returned by project. Invalid project IDs in projectIds are ignored. System fields are always returned.

It can also return the collapsed field for custom fields. Collapsed fields enable searches to be performed across all fields with the same name and of the same field type. For example, the collapsed field Component - Component[Dropdown] enables dropdown fields Component - cf[10061] and Component - cf[10062] to be searched simultaneously.

Permissions required: None.

POST /rest/api/3/jql/autocompletedata

Flag	Type	Required	Description
--body	string	No	request body (JSON string, @file, or - for stdin)

Example:

jr jql get-auto-complete-post

get-field-auto-complete-for-query-string

Get field auto complete suggestions

Returns the JQL search auto complete suggestions for a field.

Suggestions can be obtained by providing:

• fieldName to get a list of all values for the field.
• fieldName and fieldValue to get a list of values containing the text in fieldValue.
• fieldName and predicateName to get a list of all predicate values for the field.
• fieldName, predicateName, and predicateValue to get a list of predicate values containing the text in predicateValue.

This operation can be accessed anonymously.

Permissions required: None.

GET /rest/api/3/jql/autocompletedata/suggestions

Flag	Type	Required	Description
--fieldName	string	No	The name of the field.
--fieldValue	string	No	The partial field item name entered by the user.
--predicateName	string	No	The name of the CHANGED operator predicate for which the suggestions are generated. The valid predicate operators are by, from, and to.
--predicateValue	string	No	The partial predicate item name entered by the user.

Example:

jr jql get-field-auto-complete-for-query-string

get-precomputations

Get precomputations (apps)

Returns the list of a function's precomputations along with information about when they were created, updated, and last used. Each precomputation has a value - the JQL fragment to replace the custom function clause with.

Permissions required: This API is only accessible to apps and apps can only inspect their own functions.

The new read:app-data:jira OAuth scope is 100% optional now, and not using it won't break your app. However, we recommend adding it to your app's scope list because we will eventually make it mandatory.

GET /rest/api/3/jql/function/computation

Flag	Type	Required	Description
--functionKey	string	No	The function key in format:

• Forge: ari:cloud:ecosystem::extension/[App ID]/[Environment ID]/static/[Function key from manifest]

• Connect: [App key]__[Module key] | | --maxResults | string | No | The maximum number of items to return per page. | | --orderBy | string | No | Order the results by a field:

• functionKey Sorts by the functionKey.

• used Sorts by the used timestamp.

• created Sorts by the created timestamp.

• updated Sorts by the updated timestamp. | | --startAt | string | No | The index of the first item to return in a page of results (page offset). |

Example:

jr jql get-precomputations

get-precomputations-by-id

Get precomputations by ID (apps)

Returns function precomputations by IDs, along with information about when they were created, updated, and last used. Each precomputation has a value - the JQL fragment to replace the custom function clause with.

Permissions required: This API is only accessible to apps and apps can only inspect their own functions.

The new read:app-data:jira OAuth scope is 100% optional now, and not using it won't break your app. However, we recommend adding it to your app's scope list because we will eventually make it mandatory.

POST /rest/api/3/jql/function/computation/search

Flag	Type	Required	Description
--body	string	No	request body (JSON string, @file, or - for stdin)
--orderBy	string	No	Order the results by a field:

• functionKey Sorts by the functionKey.
• used Sorts by the used timestamp.
• created Sorts by the created timestamp.
• updated Sorts by the updated timestamp. |

Example:

jr jql get-precomputations-by-id

match-issues

Check issues against JQL

Checks whether one or more issues would be returned by one or more JQL queries.

Permissions required: None, however, issues are only matched against JQL queries where the user has:

• Browse projects project permission for the project that the issue is in.
• If issue-level security is configured, issue-level security permission to view the issue.

POST /rest/api/3/jql/match

Flag	Type	Required	Description
--body	string	No	request body (JSON string, @file, or - for stdin)

Example:

jr jql match-issues

migrate-queries

Convert user identifiers to account IDs in JQL queries

Converts one or more JQL queries with user identifiers (username or user key) to equivalent JQL queries with account IDs.

You may wish to use this operation if your system stores JQL queries and you want to make them GDPR-compliant. For more information about GDPR-related changes, see the migration guide.

Permissions required: Permission to access Jira.

POST /rest/api/3/jql/pdcleaner

Flag	Type	Required	Description
--body	string	No	request body (JSON string, @file, or - for stdin)

Example:

jr jql migrate-queries

parse-queries

Parse JQL query

Parses and validates JQL queries.

Validation is performed in context of the current user.

This operation can be accessed anonymously.

Permissions required: None.

POST /rest/api/3/jql/parse

Flag	Type	Required	Description
--body	string	No	request body (JSON string, @file, or - for stdin)
--validation	string	No	How to validate the JQL query and treat the validation results. Validation options include:

• strict Returns all errors. If validation fails, the query structure is not returned.
• warn Returns all errors. If validation fails but the JQL query is correctly formed, the query structure is returned.
• none No validation is performed. If JQL query is correctly formed, the query structure is returned. |

Example:

jr jql parse-queries

sanitise-queries

Sanitize JQL queries

Sanitizes one or more JQL queries by converting readable details into IDs where a user doesn't have permission to view the entity.

For example, if the query contains the clause project = 'Secret project', and a user does not have browse permission for the project "Secret project", the sanitized query replaces the clause with project = 12345" (where 12345 is the ID of the project). If a user has the required permission, the clause is not sanitized. If the account ID is null, sanitizing is performed for an anonymous user.

Note that sanitization doesn't make the queries GDPR-compliant, because it doesn't remove user identifiers (username or user key). If you need to make queries GDPR-compliant, use Convert user identifiers to account IDs in JQL queries.

Before sanitization each JQL query is parsed. The queries are returned in the same order that they were passed.

Permissions required: Administer Jira global permission.

POST /rest/api/3/jql/sanitize

Flag	Type	Required	Description
--body	string	No	request body (JSON string, @file, or - for stdin)

Example:

jr jql sanitise-queries

update-precomputations

Update precomputations (apps)

Update the precomputation value of a function created by a Forge/Connect app.

Permissions required: An API for apps to update their own precomputations.

The new write:app-data:jira OAuth scope is 100% optional now, and not using it won't break your app. However, we recommend adding it to your app's scope list because we will eventually make it mandatory.

POST /rest/api/3/jql/function/computation

Flag	Type	Required	Description
--body	string	No	request body (JSON string, @file, or - for stdin)
--skipNotFoundPrecomputations	string	No

Example:

jr jql update-precomputations