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.

curl --location --request POST 'http://jira.local:8080/jira/rest//rest/api/3/jql/sanitize' \ --header 'Content-Type: application/json' \ --data-raw '{ "queries": [ { "query": "project = '\''Sample project'\''" }, { "accountId": "5b10ac8d82e05b22cc7d4ef5", "query": "project = '\''Sample project'\''" }, { "accountId": "cda2aa1395ac195d951b3387", "query": "project = '\''Sample project'\''" }, { "accountId": "5b10ac8d82e05b22cc7d4ef5", "query": "invalid query" } ] }'

{ "queries": [ { "initialQuery": "project = 'Sample project'", "sanitizedQuery": "project = 12345" }, { "initialQuery": "project = 'Sample project'", "sanitizedQuery": "project = 'Sample project'", "accountId": "5b10ac8d82e05b22cc7d4ef5" }, { "initialQuery": "project = 'Sample project'", "sanitizedQuery": "project = 12345", "accountId": "cda2aa1395ac195d951b3387" }, { "initialQuery": "non-parsable query", "errors": { "errorMessages": [ "Error in the JQL Query: Expecting operator but got 'query'. The valid operators are '=', '!=', '<', '>', '<=', '>=', '~', '!~', 'IN', 'NOT IN', 'IS' and 'IS NOT'. (line 1, character 9)" ], "errors": {} }, "accountId": "5b10ac8d82e05b22cc7d4ef5" } ] }

Request

Body Params application/json

The list of JQL queries to sanitize for the given account IDs.

queries

array[object (JqlQueryToSanitize) {2}]

required

The list of JQL queries to sanitize. Must contain unique values. Maximum of 20 queries.

accountId

string | null

optional

The account ID of the user, which uniquely identifies the user across all Atlassian products. For example, 5b10ac8d82e05b22cc7d4ef5.

<= 128 characters

query

string

required

The query to sanitize.

Examples

Responses

🟢200Returned if the request is successful.

application/json

Body

The sanitized JQL queries for the given account IDs.

queries

array[object (SanitizedJqlQuery) {4}]

optional

The list of sanitized JQL queries.

accountId

string | null

optional

The account ID of the user for whom sanitization was performed.

<= 128 characters

errors

object

optional

The list of errors.

initialQuery

string

optional

The initial query.

sanitizedQuery

string | null

optional

The sanitized query, if there were no errors.

🟠400Returned if the request is invalid.

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

🟠403Returned if the user does not have the necessary permission.