# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Atlassian The Jira Cloud platform REST JQL API
  version: 1.0.0
extends: openapi/atlassian-jql-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 6
- target: $.paths['/rest/api/3/jql/autocompletedata'].get
  update:
    x-apievangelist-phrasing:
      intent: Download JQL field and function reference
      effect: read
      questions:
      - Which fields, functions and reserved words can I use in a JQL query?
      - Is there a downloadable reference of every searchable JQL field?
      instructions:
      - text: Get the full JQL field and function reference data.
      - text: Download the list of JQL-searchable fields, operators and functions.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/jql/autocompletedata'].post
  update:
    x-apievangelist-phrasing:
      intent: Get JQL reference data scoped to projects
      effect: read
      questions:
      - Can I get JQL field reference data limited to the fields used in certain projects?
      - Does the JQL reference include collapsed custom fields if I ask for them?
      instructions:
      - text: Get JQL reference data for projects {projectIds}.
        slots:
          projectIds: requestBody.projectIds
      - text: Fetch JQL field reference for projects {projectIds} with collapsed fields {includeCollapsedFields}.
        slots:
          projectIds: requestBody.projectIds
          includeCollapsedFields: requestBody.includeCollapsedFields
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/jql/autocompletedata/suggestions'].get
  update:
    x-apievangelist-phrasing:
      intent: Suggest values for a JQL field
      effect: read
      questions:
      - What values can I type after a field name like status or assignee in JQL?
      - Can Jira suggest matching values as I type part of a JQL field value?
      instructions:
      - text: Suggest JQL values for field {fieldName} starting with {fieldValue}.
        slots:
          fieldName: query.fieldName
          fieldValue: query.fieldValue
      - text: List autocomplete values for JQL field {fieldName}.
        slots:
          fieldName: query.fieldName
      - text: Suggest values for predicate {predicateName} on field {fieldName}.
        slots:
          predicateName: query.predicateName
          fieldName: query.fieldName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/jql/parse'].post
  update:
    x-apievangelist-phrasing:
      intent: Parse and validate JQL queries
      effect: read
      questions:
      - Is my JQL query syntactically valid before I run it?
      - Can I get the parsed structure of a JQL query, with errors explained?
      instructions:
      - text: Validate the JQL queries {queries} with {validation} validation.
        slots:
          queries: requestBody.queries
          validation: query.validation
      - text: Parse JQL {queries} and report any errors.
        slots:
          queries: requestBody.queries
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/jql/pdcleaner'].post
  update:
    x-apievangelist-phrasing:
      intent: Convert usernames in JQL to account IDs
      effect: read
      questions:
      - My saved JQL filters use usernames; how do I rewrite them with account IDs for GDPR?
      - Can Jira convert user keys inside old JQL queries into account IDs?
      instructions:
      - text: Convert the user identifiers in JQL queries {queryStrings} to account IDs.
        slots:
          queryStrings: requestBody.queryStrings
      - text: Rewrite {queryStrings} so usernames become account IDs.
        slots:
          queryStrings: requestBody.queryStrings
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/jql/sanitize'].post
  update:
    x-apievangelist-phrasing:
      intent: Sanitize JQL to hide restricted details
      effect: read
      questions:
      - Can I strip project names a user can't see from a JQL query before showing it to them?
      - What does sanitizing a JQL query replace with IDs?
      instructions:
      - text: Sanitize the JQL queries {queries}.
        slots:
          queries: requestBody.queries
      - text: Hide restricted entity names in JQL {queries} by converting them to IDs.
        slots:
          queries: requestBody.queries
      method: generated
      generated: '2026-10-01'