components:
  schemas:
    JQLReferenceData:
      additionalProperties: false
      description: Lists of JQL reference data.
      properties:
        jqlReservedWords:
          description: List of JQL query reserved words.
          items:
            type: string
          type: array
        visibleFieldNames:
          description: List of fields usable in JQL queries.
          items:
            $ref: '#/components/schemas/FieldReferenceData'
          type: array
        visibleFunctionNames:
          description: List of functions usable in JQL queries.
          items:
            $ref: '#/components/schemas/FunctionReferenceData'
          type: array
      type: object
    AutoCompleteSuggestions:
      additionalProperties: false
      description: The results from a JQL query.
      properties:
        results:
          description: The list of suggested item.
          items:
            $ref: '#/components/schemas/AutoCompleteSuggestion'
          type: array
      type: object
    PageBeanJqlFunctionPrecomputationBean:
      additionalProperties: false
      description: A page of items.
      properties:
        isLast:
          description: Whether this is the last page.
          readOnly: true
          type: boolean
        maxResults:
          description: The maximum number of items that could be returned.
          format: int32
          readOnly: true
          type: integer
        nextPage:
          description: If there is another page of results, the URL of the next page.
          format: uri
          readOnly: true
          type: string
        self:
          description: The URL of the page.
          format: uri
          readOnly: true
          type: string
        startAt:
          description: The index of the first item returned.
          format: int64
          readOnly: true
          type: integer
        total:
          description: The number of items returned.
          format: int64
          readOnly: true
          type: integer
        values:
          description: The list of items.
          items:
            $ref: '#/components/schemas/JqlFunctionPrecomputationBean'
          readOnly: true
          type: array
      type: object
    IssueMatches:
      additionalProperties: false
      description: >-
        A list of matched issues or errors for each JQL query, in the order the
        JQL queries were passed.
      properties:
        matches:
          items:
            $ref: '#/components/schemas/IssueMatchesForJQL'
          type: array
      required:
        - matches
      type: object
    ParsedJqlQueries:
      additionalProperties: false
      description: A list of parsed JQL queries.
      properties:
        queries:
          description: A list of parsed JQL queries.
          items:
            $ref: '#/components/schemas/ParsedJqlQuery'
          minLength: 1
          type: array
      required:
        - queries
      type: object
    ConvertedJQLQueries:
      additionalProperties: false
      description: The converted JQL queries.
      properties:
        queriesWithUnknownUsers:
          description: >-
            List of queries containing user information that could not be mapped
            to an existing user
          items:
            $ref: '#/components/schemas/JQLQueryWithUnknownUsers'
          type: array
        queryStrings:
          description: >-
            The list of converted query strings with account IDs in place of
            user identifiers.
          items:
            type: string
          type: array
      type: object
    SanitizedJqlQueries:
      additionalProperties: false
      description: The sanitized JQL queries for the given account IDs.
      properties:
        queries:
          description: The list of sanitized JQL queries.
          items:
            $ref: '#/components/schemas/SanitizedJqlQuery'
          type: array
      type: object
externalDocs:
  description: Find out more about Atlassian products and services.
  url: http://www.atlassian.com
info:
  contact:
    email: ecosystem@atlassian.com
  description: Needs description.
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  termsOfService: http://atlassian.com/terms/
  title: 'Atlassian rest/api/3/jql/'
  version: 1001.0.0-SNAPSHOT-67b5c6e5f3598d7ec1649016d026468ab2838a77
openapi: 3.0.1
paths:
  /rest/api/3/jql/autocompletedata:
    get:
      deprecated: false
      description: >-
        Returns reference data for JQL searches. This is a downloadable version
        of the documentation provided in [Advanced searching - fields
        reference](https://confluence.atlassian.com/x/gwORLQ) and [Advanced
        searching - functions
        reference](https://confluence.atlassian.com/x/hgORLQ), 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.<br><br>To filter visible field details by
        project or collapse non-unique fields by field type then [Get field
        reference data (POST)](#api-rest-api-3-jql-autocompletedata-post) can be
        used.<br><br>This operation can be accessed
        anonymously.<br><br>**[Permissions](#permissions) required:** None.
      operationId: atlassianGetautocomplete
      parameters: []
      responses:
        '200':
          content:
            application/json:
              example: >-
                {"jqlReservedWords":["empty","and","or","in","distinct"],"visibleFieldNames":[{"displayName":"summary","operators":["~","!~","is","is
                not"],"orderable":"true","searchable":"true","types":["java.lang.String"],"value":"summary"},{"auto":"true","cfid":"cf[10880]","displayName":"Sprint
                - cf[10880]","operators":["=","!=","in","not in","is","is
                not"],"orderable":"true","searchable":"true","types":["com.atlassian.greenhopper.service.sprint.Sprint"],"value":"Sprint"}],"visibleFunctionNames":[{"displayName":"standardIssueTypes()","isList":"true","types":["com.atlassian.jira.issue.issuetype.IssueType"],"value":"standardIssueTypes()"},{"displayName":"issuesWithText()","supportsListAndSingleValueOperators":"true","types":["com.atlassian.jira.issue.issuetype.IssueType"],"value":"issuesWithText()"}]}
              schema:
                $ref: '#/components/schemas/JQLReferenceData'
          description: Returned if the request is successful.
        '401':
          description: Returned if the authentication credentials are incorrect.
      security:
        - basicAuth: []
        - OAuth2:
            - read:jira-work
        - {}
      summary: 'Atlassian Get Field Reference Data Get'
      tags:
        - JQL
      x-atlassian-data-security-policy:
        - app-access-rule-exempt: true
      x-atlassian-oauth2-scopes:
        - scheme: OAuth2
          scopes:
            - read:jira-work
          state: Current
        - scheme: OAuth2
          scopes:
            - read:field:jira
          state: Beta
      x-atlassian-connect-scope: READ
    post:
      deprecated: false
      description: >-
        Returns reference data for JQL searches. This is a downloadable version
        of the documentation provided in [Advanced searching - fields
        reference](https://confluence.atlassian.com/x/gwORLQ) and [Advanced
        searching - functions
        reference](https://confluence.atlassian.com/x/hgORLQ), 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.<br><br>This operation can filter the custom
        fields returned by project. Invalid project IDs in `projectIds` are
        ignored. System fields are always returned.<br><br>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.<br><br>**[Permissions](#permissions) required:** None.
      operationId: atlassianGetautocompletepost
      parameters: []
      requestBody:
        content:
          application/json:
            example:
              includeCollapsedFields: true
              projectIds:
                - 10000
                - 10001
                - 10002
            schema:
              $ref: '#/components/schemas/SearchAutoCompleteFilter'
        required: true
      responses:
        '200':
          content:
            application/json:
              example: >-
                {"jqlReservedWords":["empty","and","or","in","distinct"],"visibleFieldNames":[{"displayName":"summary","operators":["~","!~","is","is
                not"],"orderable":"true","searchable":"true","types":["java.lang.String"],"value":"summary"},{"auto":"true","cfid":"cf[10061]","displayName":"Component
                - cf[10061]","operators":["=","!=","in","not in","is","is
                not"],"orderable":"true","types":["com.atlassian.jira.issue.customfields.option.Option"],"value":"cf[10061]"},{"auto":"true","cfid":"cf[10062]","displayName":"Component
                - cf[10062]","operators":["=","!=","in","not in","is","is
                not"],"orderable":"true","types":["com.atlassian.jira.issue.customfields.option.Option"],"value":"cf[10062]"},{"auto":"true","displayName":"Component
                - Component[Dropdown]","operators":["=","!=","in","not
                in","is","is
                not"],"searchable":"true","types":["com.atlassian.jira.issue.customfields.option.Option"],"value":"\"Component[Dropdown]\""}],"visibleFunctionNames":[{"displayName":"standardIssueTypes()","isList":"true","types":["com.atlassian.jira.issue.issuetype.IssueType"],"value":"standardIssueTypes()"}]}
              schema:
                $ref: '#/components/schemas/JQLReferenceData'
          description: Returned if the request is successful.
        '400':
          description: Returned if the request is not valid.
        '401':
          description: Returned if the authentication credentials are incorrect.
      security:
        - basicAuth: []
        - OAuth2:
            - read:jira-work
        - {}
      summary: 'Atlassian Get Field Reference Data Post'
      tags:
        - JQL
      x-atlassian-data-security-policy:
        - app-access-rule-exempt: true
      x-atlassian-oauth2-scopes:
        - scheme: OAuth2
          scopes:
            - read:jira-work
          state: Current
        - scheme: OAuth2
          scopes:
            - read:field:jira
          state: Beta
      x-atlassian-connect-scope: READ
  /rest/api/3/jql/autocompletedata/suggestions:
    get:
      deprecated: false
      description: >-
        Returns the JQL search auto complete suggestions for a
        field.<br><br>Suggestions can be obtained by providing:<br><br> *  `fieldName` to get a list of all values for the field.<br> *  `fieldName` and `fieldValue` to get a list of values containing the text
        in `fieldValue`.<br> *  `fieldName` and `predicateName` to get a list of
        all predicate values for the field.<br> *  `fieldName`, `predicateName`,
        and `predicateValue` to get a list of predicate values containing the
        text in `predicateValue`.<br><br>This operation can be accessed
        anonymously.<br><br>**[Permissions](#permissions) required:** None.
      operationId: atlassianGetfieldautocompleteforquerystring
      parameters:
        - description: The name of the field.
          in: query
          name: fieldName
          schema:
            example: reporter
            type: string
          x-showInExample: 'true'
        - description: The partial field item name entered by the user.
          in: query
          name: fieldValue
          schema:
            type: string
        - description: >-
            The name of the [ CHANGED operator
            predicate](https://confluence.atlassian.com/x/hQORLQ#Advancedsearching-operatorsreference-CHANGEDCHANGED)
            for which the suggestions are generated. The valid predicate
            operators are *by*, *from*, and *to*.
          in: query
          name: predicateName
          schema:
            type: string
        - description: The partial predicate item name entered by the user.
          in: query
          name: predicateValue
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              example: >-
                {"results":[{"displayName":"<b>Ac</b>tiveObjects
                (AO)","value":"ActiveObjects"},{"displayName":"Atlassian Connect
                (<b>AC</b>)","value":"Atlassian
                Connect"},{"displayName":"Atlassian Connect in Jira
                (<b>AC</b>JIRA)","value":"Atlassian Connect in Jira"}]}
              schema:
                $ref: '#/components/schemas/AutoCompleteSuggestions'
          description: Returned if the request is successful.
        '400':
          description: Returned if an invalid combination of parameters is passed.
        '401':
          description: Returned if the authentication credentials are incorrect.
      security:
        - basicAuth: []
        - OAuth2:
            - read:jira-work
        - {}
      summary: Atlassian Get Field Auto Complete Suggestions
      tags:
        - JQL
      x-atlassian-data-security-policy:
        - app-access-rule-exempt: false
      x-atlassian-oauth2-scopes:
        - scheme: OAuth2
          scopes:
            - read:jira-work
          state: Current
        - scheme: OAuth2
          scopes:
            - read:issue-details:jira
          state: Beta
      x-atlassian-connect-scope: READ
  /rest/api/3/jql/function/computation:
    get:
      deprecated: false
      description: >-
        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.<br><br>**[Permissions](#permissions) required:**
        This API is only accessible to apps and apps can only inspect their own
        functions.
      operationId: atlassianGetprecomputations
      parameters:
        - description: |-
            The function key in format:

             *  Forge: `ari:cloud:ecosystem::extension/[App ID]/[Environment ID]/static/[Function key from manifest]`
             *  Connect: `[App key]__[Module key]`
          in: query
          name: functionKey
          schema:
            items:
              default: ''
              type: string
            type: array
        - description: >-
            The index of the first item to return in a page of results (page
            offset).
          in: query
          name: startAt
          schema:
            default: 0
            format: int64
            type: integer
        - description: The maximum number of items to return per page.
          in: query
          name: maxResults
          schema:
            default: 100
            format: int32
            type: integer
        - description: |-
            [Order](#ordering) 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.
          in: query
          name: orderBy
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              example: >-
                {"isLast":true,"maxResults":100,"startAt":0,"total":1,"values":[{"id":"cf75a1b0-4ac6-4bd8-8a50-29a465a96520","value":"issue
                in (TEST-1, TEST-2,
                TEST-3)","functionKey":"ari:cloud:ecosystem::extension/00000000-1111-2222-3333-4444444/111111-2222-3333-4444-55555/static/issuesWithText","field":"issue","operator":"in","functionName":"issuesWithText","arguments":["Test"],"created":"2023-10-14T05:25:20.000+0000","updated":"2023-10-14T05:25:20.000+0000","used":"2023-10-14T05:25:20.000+0000"},{"id":"2a854f11-d0e1-4260-aea8-64a562a7062a","error":"Error
                message to be displayed to the
                user","functionKey":"ari:cloud:ecosystem::extension/00000000-1111-2222-3333-4444444/111111-2222-3333-4444-55555/static/issuesWithText","field":"issue","operator":"=","functionName":"issuesWithText","arguments":["10001"],"created":"2023-10-14T05:25:20.000+0000","updated":"2023-10-14T05:25:20.000+0000","used":"2023-10-14T05:25:20.000+0000"}]}
              schema:
                $ref: '#/components/schemas/PageBeanJqlFunctionPrecomputationBean'
          description: Returned if the request is successful.
        '400':
          description: Returned if the request is invalid.
        '401':
          description: Returned if the authentication credentials are incorrect or missing.
        '403':
          description: >-
            Returned if the request is not authenticated as the app that
            provided the function.
        '404':
          description: Returned if the function is not found.
      security:
        - basicAuth: []
        - OAuth2: []
      summary: 'Atlassian Get Precomputations Apps'
      tags:
        - JQL Functions (Apps)
      x-atlassian-data-security-policy:
        - app-access-rule-exempt: true
      x-atlassian-oauth2-scopes:
        - scheme: OAuth2
          scopes: []
          state: Current
        - scheme: OAuth2
          scopes: []
          state: Beta
      x-experimental: true
      x-atlassian-connect-scope: READ
    post:
      deprecated: false
      description: >-
        Update the precomputation value of a function created by a Forge/Connect
        app.<br><br>**[Permissions](#permissions) required:** An API for apps to
        update their own precomputations.
      operationId: atlassianUpdateprecomputations
      parameters: []
      requestBody:
        content:
          application/json:
            example:
              values:
                - id: f2ef228b-367f-4c6b-bd9d-0d0e96b5bd7b
                  value: issue in (TEST-1, TEST-2, TEST-3)
                - error: Error message to be displayed to the user
                  id: 2a854f11-d0e1-4260-aea8-64a562a7062a
            schema:
              $ref: '#/components/schemas/JqlFunctionPrecomputationUpdateRequestBean'
        required: true
      responses:
        '204':
          content:
            application/json:
              schema: {}
          description: Returned if the request is successful.
        '400':
          description: Returned if the request is invalid.
        '403':
          description: >-
            Returned if the request is not authenticated as the app that
            provided the function.
        '404':
          description: Returned if the function is not found.
      security:
        - basicAuth: []
        - OAuth2: []
      summary: 'Atlassian Update Precomputations Apps'
      tags:
        - JQL Functions (Apps)
      x-atlassian-data-security-policy:
        - app-access-rule-exempt: true
      x-atlassian-oauth2-scopes:
        - scheme: OAuth2
          scopes: []
          state: Current
        - scheme: OAuth2
          scopes: []
          state: Beta
      x-experimental: true
      x-atlassian-connect-scope: READ
  /rest/api/3/jql/match:
    post:
      deprecated: false
      description: >-
        Checks whether one or more issues would be returned by one or more JQL
        queries.<br><br>**[Permissions](#permissions) required:** None, however,
        issues are only matched against JQL queries where the user has:<br><br>
        *  *Browse projects* [project
        permission](https://confluence.atlassian.com/x/yodKLg) for the project
        that the issue is in.<br> *  If [issue-level
        security](https://confluence.atlassian.com/x/J4lKLg) is configured,
        issue-level security permission to view the issue.
      operationId: atlassianMatchissues
      parameters: []
      requestBody:
        content:
          application/json:
            example:
              issueIds:
                - 10001
                - 1000
                - 10042
              jqls:
                - project = FOO
                - issuetype = Bug
                - summary ~ "some text" AND project in (FOO, BAR)
            schema:
              $ref: '#/components/schemas/IssuesAndJQLQueries'
        required: true
      responses:
        '200':
          content:
            application/json:
              example: >-
                {"matches":[{"matchedIssues":[10000,10004],"errors":[]},{"matchedIssues":[100134,10025,10236],"errors":[]},{"matchedIssues":[],"errors":[]},{"matchedIssues":[],"errors":["Invalid
                JQL: broken = value"]}]}
              schema:
                $ref: '#/components/schemas/IssueMatches'
          description: Returned if the request is successful.
        '400':
          description: >-
            Returned if `jqls` exceeds the maximum number of JQL queries or
            `issueIds` exceeds the maximum number of issue IDs.
      security:
        - basicAuth: []
        - OAuth2:
            - read:jira-work
      summary: Atlassian Check Issues Against Jql
      tags:
        - Issue Search
      x-atlassian-data-security-policy:
        - app-access-rule-exempt: false
      x-atlassian-oauth2-scopes:
        - scheme: OAuth2
          scopes:
            - read:jira-work
          state: Current
        - scheme: OAuth2
          scopes:
            - read:issue-details:jira
          state: Beta
      x-atlassian-connect-scope: READ
  /rest/api/3/jql/parse:
    post:
      deprecated: false
      description: >-
        Parses and validates JQL queries.<br><br>Validation is performed in
        context of the current user.<br><br>This operation can be accessed
        anonymously.<br><br>**[Permissions](#permissions) required:** None.
      operationId: atlassianParsejqlqueries
      parameters:
        - description: >-
            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.
          in: query
          name: validation
          required: true
          schema:
            default: strict
            enum:
              - strict
              - warn
              - none
            type: string
      requestBody:
        content:
          application/json:
            example:
              queries:
                - >-
                  summary ~ test AND (labels in (urgent, blocker) OR
                  lastCommentedBy = currentUser()) AND status CHANGED AFTER
                  startOfMonth(-1M) ORDER BY updated DESC
                - >-
                  issue.property["spaces here"].value in ("Service requests",
                  Incidents)
                - invalid query
                - summary = test
                - summary in test
                - project = INVALID
                - universe = 42
            schema:
              $ref: '#/components/schemas/JqlQueriesToParse'
        required: true
      responses:
        '200':
          content:
            application/json:
              example: >-
                {"queries":[{"query":"summary ~ test AND (labels in (urgent,
                blocker) OR lastCommentedBy = currentUser()) AND status CHANGED
                AFTER -5d ORDER BY updated
                DESC","structure":{"orderBy":{"fields":[{"direction":"desc","field":{"encodedName":"updated","name":"updated"}}]},"where":{"clauses":[{"field":{"encodedName":"summary","name":"summary"},"operand":{"encodedValue":"test","value":"test"},"operator":"~"},{"clauses":[{"field":{"encodedName":"labels","name":"labels"},"operand":{"encodedOperand":"urgent,
                blocker)","values":[{"encodedValue":"urgent","value":"urgent"},{"encodedValue":"blocker","value":"blocker"}]},"operator":"in"},{"field":{"encodedName":"lastCommentedBy","name":"lastCommentedBy","property":[{"entity":"issue","key":"propertyKey","path":"path.in.property","type":"user"}]},"operand":{"arguments":[],"encodedOperand":"currentUser()","function":"currentUser"},"operator":"="}],"operator":"or"},{"field":{"encodedName":"status","name":"status"},"operator":"changed","predicates":[{"operand":{"arguments":["-1M"],"encodedOperand":"startOfMonth(-1M)","function":"startOfMonth"},"operator":"after"}]}],"operator":"and"}}},{"query":"issue.property[\"spaces
                here\"].value in (\"Service requests\",
                Incidents)","structure":{"where":{"field":{"encodedName":"issue.property[\"spaces
                here\"].value","name":"issue.property[spaces
                here].value","property":[{"entity":"issue","key":"spaces
                here","path":"value"}]},"operand":{"encodedOperand":"(\"Service
                requests\", Incidents)","values":[{"encodedValue":"\"Service
                requests\"","value":"Service
                requests"},{"encodedValue":"Incidents","value":"Incidents"}]},"operator":"in"}}},{"errors":["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)"],"query":"invalid query"},{"errors":["The operator '=' is
                not supported by the 'summary' field."],"query":"summary =
                test"},{"errors":["Operator 'in' does not support the non-list
                value '\"test\"' for field 'summary'."],"query":"summary in
                test"},{"errors":["The value 'INVALID' does not exist for the
                field 'project'."],"query":"project =
                INVALID"},{"errors":["Field 'universe' does not exist or you do
                not have permission to view it."],"query":"universe = 42"}]}
              schema:
                $ref: '#/components/schemas/ParsedJqlQueries'
          description: Returned if the request is successful.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorCollection'
          description: Returned if the request is invalid.
        '401':
          description: Returned if the authentication credentials are incorrect.
      security:
        - basicAuth: []
        - OAuth2:
            - read:jira-work
        - {}
      summary: Atlassian Parse Jql Query
      tags:
        - JQL
      x-atlassian-data-security-policy:
        - app-access-rule-exempt: false
      x-atlassian-oauth2-scopes:
        - scheme: OAuth2
          scopes:
            - read:jira-work
          state: Current
        - scheme: OAuth2
          scopes:
            - read:field:jira
            - validate:jql:jira
            - read:jql:jira
          state: Beta
      x-experimental: true
      x-atlassian-connect-scope: READ
  /rest/api/3/jql/pdcleaner:
    post:
      deprecated: false
      description: >-
        Converts one or more JQL queries with user identifiers (username or user
        key) to equivalent JQL queries with account IDs.<br><br>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](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-user-privacy-api-migration-guide/).<br><br>**[Permissions](#permissions)
        required:** Permission to access Jira.
      operationId: atlassianMigratequeries
      parameters: []
      requestBody:
        content:
          application/json:
            example:
              queryStrings:
                - assignee = mia
                - >-
                  issuetype = Bug AND assignee in (mia) AND reporter in (alana)
                  order by lastViewed DESC
            schema:
              $ref: '#/components/schemas/JQLPersonalDataMigrationRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              example: >-
                {"queriesWithUnknownUsers":[{"convertedQuery":"assignee =
                unknown","originalQuery":"assignee =
                mia"}],"queryStrings":["issuetype = Bug AND assignee in
                (abcde-12345) AND reporter in (abc551-c4e99) order by lastViewed
                DESC"]}
              schema:
                $ref: '#/components/schemas/ConvertedJQLQueries'
          description: >-
            Returned if the request is successful. Note that the JQL queries are
            returned in the same order that they were passed.
        '400':
          content:
            application/json:
              schema:
                type: string
          description: >-
            Returned if at least one of the queries cannot be converted. For
            example, the JQL has invalid operators or invalid keywords, or the
            users in the query cannot be found.
        '401':
          content:
            application/json:
              schema:
                type: string
          description: Returned if the authentication credentials are incorrect or missing.
      security:
        - basicAuth: []
        - OAuth2:
            - read:jira-user
      summary: Atlassian Convert User Identifiers To Account Ids In Jql Queries
      tags:
        - JQL
      x-atlassian-data-security-policy:
        - app-access-rule-exempt: true
      x-atlassian-oauth2-scopes:
        - scheme: OAuth2
          scopes:
            - read:jira-user
          state: Current
        - scheme: OAuth2
          scopes:
            - read:user:jira
            - read:jql:jira
            - validate:jql:jira
          state: Beta
      x-atlassian-connect-scope: READ
  /rest/api/3/jql/sanitize:
    post:
      deprecated: false
      description: >-
        Sanitizes one or more JQL queries by converting readable details into
        IDs where a user doesn't have permission to view the entity.<br><br>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.<br><br>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](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-jql/#api-rest-api-3-jql-sanitize-post).<br><br>Before
        sanitization each JQL query is parsed. The queries are returned in the
        same order that they were passed.<br><br>**[Permissions](#permissions)
        required:** *Administer Jira* [global
        permission](https://confluence.atlassian.com/x/x4dKLg).
      operationId: atlassianSanitisejqlqueries
      parameters: []
      requestBody:
        content:
          application/json:
            example:
              queries:
                - query: project = 'Sample project'
                - accountId: 5b10ac8d82e05b22cc7d4ef5
                  query: project = 'Sample project'
                - accountId: cda2aa1395ac195d951b3387
                  query: project = 'Sample project'
                - accountId: 5b10ac8d82e05b22cc7d4ef5
                  query: invalid query
            schema:
              $ref: '#/components/schemas/JqlQueriesToSanitize'
        required: true
      responses:
        '200':
          content:
            application/json:
              example: >-
                {"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"}]}
              schema:
                $ref: '#/components/schemas/SanitizedJqlQueries'
          description: Returned if the request is successful.
        '400':
          content:
            application/json:
              example: >-
                {"errorMessages":["The queries has to be
                provided."],"errors":{}}
              schema:
                $ref: '#/components/schemas/ErrorCollection'
          description: Returned if the request is invalid.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorCollection'
          description: Returned if the authentication credentials are incorrect or missing.
        '403':
          content:
            application/json:
              example: >-
                {"errorMessages":["You are not authorized to perform this
                action. Administrator privileges are required."],"errors":{}}
              schema:
                $ref: '#/components/schemas/ErrorCollection'
          description: Returned if the user does not have the necessary permission.
      security:
        - basicAuth: []
        - OAuth2:
            - manage:jira-configuration
      summary: Atlassian Sanitize Jql Queries
      tags:
        - JQL
      x-atlassian-data-security-policy:
        - app-access-rule-exempt: false
      x-atlassian-oauth2-scopes:
        - scheme: OAuth2
          scopes:
            - manage:jira-configuration
          state: Current
        - scheme: OAuth2
          scopes:
            - read:jql:jira
          state: Beta
      x-experimental: true
      x-atlassian-connect-scope: ADMIN
servers:
  - url: https://your-domain.atlassian.net
tags:
  - name: Issue Search
  - name: JQL
  - name: JQL Functions (Apps)
x-atlassian-narrative:
  documents:
    - anchor: about
      body: >-
        The Jira REST API enables you to interact with Jira programmatically.
        Use this API to 

        [build
        apps](https://developer.atlassian.com/cloud/jira/platform/integrating-with-jira-cloud/),
        script interactions with 

        Jira, or develop any other type of integration. This page documents the
        REST resources available in Jira Cloud, including 

        the HTTP response codes and example requests and responses.
      title: About
    - anchor: version
      body: >
        This documentation is for **version 3** of the Jira Cloud platform REST
        API, which is the latest version

        but is in **beta**. [Version
        2](https://developer.atlassian.com/cloud/jira/platform/rest/v2/) and 

        version 3 of the API offer the same collection of operations. However,
        version 3 provides support for 

        the [Atlassian Document
        Format](https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/) 

        (ADF) in: 

        - `body` in comments, including where comments are used in issue, issue
        link, and transition resources.

        - `comment` in worklogs.

        - `description` and `environment` fields in issues.

        - `textarea` type custom fields (multi-line text fields) in issues.
        Single line custom fields 
          (`textfield`) accept a string and don't handle Atlassian Document Format content.

        However, these new features are under development and may change.
      title: Version
    - anchor: authentication
      body: >
        ### Forge apps


        For Forge apps, [REST API
        scopes](https://developer.atlassian.com/cloud/jira/platform/scopes-for-oauth-2-3LO-and-forge-apps/) 

        are used when authenticating with Jira Cloud platform. See [Add scopes
        to call an Atlassian REST
        API](https://developer.atlassian.com/platform/forge/add-scopes-to-call-an-atlassian-rest-api/)
        for more details.


        The URIs for Forge app REST API calls have this structure:


        `/rest/api/3/<resource-name>`


        For example, `/rest/api/3/issue/DEMO-1`


        ### Connect apps


        For Connect apps, authentication (JWT-based) is built into the Connect
        libraries. Authorization is implemented using either 

        scopes (shown as _App scope required_ for operations on this page) or
        user impersonation. See 

        [Security for Connect
        apps](https://developer.atlassian.com/cloud/jira/platform/security-for-connect-apps/) 

        for details.


        The URIs for Connect app REST API calls have this structure:


        `https://<site-url>/rest/api/3/<resource-name>`


        For example, `https://your-domain.atlassian.net/rest/api/3/issue/DEMO-1`


        ### Other integrations


        For integrations that are not Forge or Connect apps, use OAuth 2.0
        authorization code grants (3LO) for security 

        (3LO scopes are shown as for operations _OAuth scopes required_). See 

        [OAuth 2.0 (3LO)
        apps](https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/) 

        for details.


        The URIs for OAuth 2.0 (3LO) app REST API calls have this structure:


        `https://api.atlassian.com/ex/jira/<cloudId>/rest/api/3/<resource-name>`


        For example,
        `https://api.atlassian.com/ex/jira/35273b54-3f06-40d2-880f-dd28cf8daafa/rest/api/3/issue/DEMO-1`


        ### Ad-hoc API calls


        For personal scripts, bots, and ad-hoc execution of the REST APIs use
        basic authentication. See [Basic auth for REST
        APIs](https://developer.atlassian.com/cloud/jira/platform/basic-auth-for-rest-apis/)
        for details. 


        The URIs for basic authentication REST API calls have this structure:


        `https://<site-url>/rest/api/3/<resource-name>`


        For example, `https://your-domain.atlassian.net/rest/api/3/issue/DEMO-1`
      title: Authentication and authorization
    - anchor: permissions
      body: >
        ### Operation permissions


        Most operations in this API require permissions. The calling user must
        have the required permissions for an operation to 

        use it. Note that for Connect apps, the app user must have the required
        permissions for the operation and the app must 

        have scopes that permit the operation.


        A permission can be granted to a group, project role, or issue role that
        the user is a member of, or granted directly to a user. 

        See [Permissions overview](https://confluence.atlassian.com/x/FQiiLQ)
        for details. The most common permissions are:


        - **Administer the Cloud site**: Users in the _site-admins_ group have
        this 

        permission. See [Manage
        groups](https://confluence.atlassian.com/x/24xjL) for details.

        - **Administer Jira**: Granted by the _Jira Administrators_ global
        permission. There is a default group for this permission. 

        See [Manage groups](https://confluence.atlassian.com/x/24xjL) and
        [Managing global permissions](https://confluence.atlassian.com/x/x4dKLg)
        for details.

        - **Administer a project in Jira**: Granted by the _Administer projects_
        project permission for a project. This can be 

        granted to a user, a group, a project role, and more. 

        See [Managing project
        permissions](https://confluence.atlassian.com/x/yodKLg) for details.

        - **Access a project in Jira**: Granted by the _Browse projects_ project
        permission for a project. This can be 

        granted to a user, a group, a project role, and more. 

        See [Managing project
        permissions](https://confluence.atlassian.com/x/yodKLg) for details.

        - **Access Jira**: Granted by the _Jira Users_ global permission. Users
        in the default product access group (for example, 

        _jira-software-users-acmesite_) have this permission. 

        See [Manage groups](https://confluence.atlassian.com/x/24xjL) and 

        [Managing global permissions](https://confluence.atlassian.com/x/x4dKLg)
        for details.


        ### Anonymous access


        Some operations provide support for anonymous access. However, anonymous
        access is only available if 

        the Jira permission needed to access the object or records returned by
        the operation is granted to 

        the _Public_ group. See [Allowing anonymous access to your
        project](https://confluence.atlassian.com/x/GDxxLg) 

        for details.


        If an operation is called anonymously and anonymous access is not
        available, the operation will return 

        an error. Note that not all operations that correspond to objects that
        can be given public access 

        provide for anonymous access.
      title: Permissions
    - anchor: expansion
      body: >+
        ### Expansion


        The Jira REST API uses resource expansion, which means that some parts
        of a resource are not returned unless specified 

        in the request. This simplifies responses and minimizes network traffic.


        To expand part of a resource in a request, use the expand query
        parameter and specify the object(s) to be expanded. 

        If you need to expand nested objects, use the `.` dot notation. If you
        need to expand multiple objects, use a 

        comma-separated list. 


        For example, the following request expands the `names` and
        `renderedFields` properties for the _JRACLOUD-34423_ issue:


        `GET issue/JRACLOUD-34423?expand=names,renderedFields`


        To discover which object can be expanded, refer to the `expand` property
        in the object. 

        In the JSON example below, the resource declares `widgets` as
        expandable.


        ```json

        {
          "expand": "widgets", 
          "self": "https://your-domain.atlassian.net/rest/api/3/resource/KEY-1", 
          "widgets": {
            "widgets": [],
            "size": 5
           }
        }

        ```


        ### Pagination


        The Jira REST API uses pagination to improve performance. Pagination is
        enforced for operations that could return a large 

        collection of items. When you make a request to a paginated resource,
        the response wraps the returned array of values in 

        a JSON object with paging metadata. For example:


        ```json

        {
            "startAt" : 0,
            "maxResults" : 10,
            "total": 200,
            "isLast": false,
            "values": [
                { /* result 0 */ },
                { /* result 1 */ },
                { /* result 2 */ }
            ]
        }

        ```


        *   `startAt` is the index of the first item returned in the page.

        *   `maxResults` is the maximum number of items that a page can return.
        Each operation can have a different limit for
            the number of items returned, and these limits may change without notice. To find the maximum number of items 
            that an operation could return, set `maxResults` to a large number—for example, over 1000—and if the returned value of `maxResults` is less than the requested value, the returned value is the maximum.
        *    `total` is the total number of items contained in all pages. This
        number **_may change_** as the client 

        requests the subsequent pages, therefore the client should always assume
        that the requested page can be empty. Note 

        that this property is not returned for all operations.

        *   `isLast` indicates whether the page returned is the last one. Note
        that this property is not returned for all operations.


        ### Ordering


        Some operations support ordering the elements of a response by a field.
        Check the documentation for the operation to 

        confirm whether ordering of a response is supported and which fields can
        be used. Responses are listed in ascending order 

        by default. You can change the order using the `orderby` query parameter
        with a `-` or `+` symbol. For example:


        *   `?orderBy=name` to order by `name` field ascending.

        *   `?orderBy=+name` to order by `name` field ascending.

        *   `?orderBy=-name` to order by `name` field descending.


      title: Expansion, pagination, and ordering
    - anchor: timestamps
      body: >
        By default, top-level timestamps (e.g. updated and created) are returned
        in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format, in the system
        default user time zone.


        To return date time data in the logged in user's timezone, please refer
        to `renderedFields` property under the `expand` query parameter in
        relevant APIs.
      title: Timestamps
    - anchor: special-request-headers
      body: >-
        The following request and response headers define important metadata for
        the Jira Cloud REST API resources.


        -   `X-Atlassian-Token` (request): Operations that accept
        multipart/form-data must include the `X-Atlassian-Token: no-check`

        header in requests. Otherwise the request is blocked by cross-site
        request forgery (CSRF/XSRF) protection.

        -   `X-Force-Accept-Language` (request): controls how the standard HTTP
        `Accept-Language` header is processed.

        By default `Accept-Language` is ignored and the response is in the
        language configured in the user's profile or,

        when no language is configured for the user, the default Jira instance
        language. For the response to recognize

        `Accept-Language` send `X-Force-Accept-Language = true` as well. If
        `Accept-Language` requests a language that Jira

        can return the response is in that language, otherwise Jira returns the
        response in the default language. If

        `Accept-Language` is not specified the response is in the default
        language.

        -   `X-AAccountId` (response): This response header contains the
        Atlassian account ID of the authenticated user.
      title: Special headers
    - anchor: anonymous-operations
      body: |2-
         Jira provides for all permissions, except the [global permission](https://confluence.atlassian.com/x/x4dKLg) Administer Jira, to be assigned to *Anyone*. Once a permission is assigned to *Anyone*, anyone knowing a project's URL is able to use the features in Jira enabled by the permission. However, the Jira REST API does not enable anonymous access for operations by default. This means that an anonymous user who may be able to perform an action through Jira, may not be able to perform the same action where it's enabled by the REST API. 

         The operations that provide anonymous access are annotated "This operation can be accessed anonymously."
      title: Anonymous operations
    - anchor: async-operations
      body: >-
        Some Jira REST API operations may trigger long-running or
        computationally expensive tasks. In these cases, the operation 

        will schedule an asynchronous task and return a `303 (See Other)`
        response, indicating the location of the queued task 

        in the `Location` header. You can query this task to get progress
        updates.


        When the task finishes, the response object will contain the `result`
        field. The content of the field is specific to the 

        operation that created the task. Refer to the operation’s documentation
        for more information.


        Note that asynchronous tasks are not guaranteed to be run in order. In
        other words, if you need your tasks to execute 

        in a certain order, you should start a task only after the prerequisite
        task(s) have finished.
      title: Asynchronous operations
    - anchor: experimental
      body: >
        Features and methods marked as experimental may change without notice.
        Feedback on experimental functionality is welcome. 

        Report your suggestions and bugs in the [ACJIRA
        project](https://ecosystem.atlassian.net/projects/ACJIRA) (preferred) or
        use the 

        **Give docs feedback** link at the top of this page. 
      title: Experimental features
    - anchor: status-codes
      body: >-
        The Jira Cloud platform REST API uses the [standard HTTP status
        codes](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html).


        Operations that return an error status code may also return a response
        body containing details of the error or errors. 

        The schema for the response body is shown below:



        ```json

        {
          "id": "https://docs.atlassian.com/jira/REST/schema/error-collection#",
          "title": "Error Collection",
          "type": "object",
          "properties": {
            "errorMessages": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "errors": {
              "type": "object",
              "patternProperties": {
                ".+": {
                  "type": "string"
                }
              },
              "additionalProperties": false
            },
            "status": { 
              "type": "integer"
            }
          },
          "additionalProperties": false
        }

        ```
      title: Status codes