# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Jira Projects API
  version: 1.0.0
extends: openapi/jira-projects-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 17
- target: $.paths['/project'].get
  update:
    x-apievangelist-phrasing:
      intent: List all visible projects via the unversioned path
      effect: read
      questions:
      - Is there an older unversioned /project endpoint that returns every project at once?
      - Can the legacy unpaginated project list include only recently viewed projects?
      instructions:
      - text: Call the legacy unversioned /project endpoint to list every project I can see.
      - text: Using the unversioned /project path, list projects with recent set to {recent} and expand {expand}.
        slots:
          recent: query.recent
          expand: query.expand
      method: generated
      generated: '2026-09-26'
- target: $.paths['/project/search'].get
  update:
    x-apievangelist-phrasing:
      intent: Page through projects via the unversioned search path
      effect: read
      questions:
      - Does the unversioned /project/search path let me filter projects by type or category?
      - Can I page through projects on the older search path without the /rest/api/3 prefix?
      instructions:
      - text: Search projects matching {query} using the unversioned /project/search path.
        slots:
          query: query.query
      - text: On the unversioned /project/search path, list projects of type {typeKey} in category {categoryId}.
        slots:
          typeKey: query.typeKey
          categoryId: query.categoryId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/project/{projectIdOrKey}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a project's details via the unversioned path
      effect: read
      questions:
      - Can I fetch a project's issue types and components from the legacy unversioned project path?
      - Does the older project lookup without the /rest/api/3 prefix still return versions and roles?
      instructions:
      - text: Get project {projectIdOrKey} from the unversioned /project path.
        slots:
          projectIdOrKey: path.projectIdOrKey
      - text: Using the legacy unversioned path, fetch project {projectIdOrKey} expanded with {expand}.
        slots:
          projectIdOrKey: path.projectIdOrKey
          expand: query.expand
      method: generated
      generated: '2026-09-26'
- target: $.paths['/project/{projectIdOrKey}/statuses'].get
  update:
    x-apievangelist-phrasing:
      intent: List a project's statuses via the unversioned path
      effect: read
      questions:
      - Does the legacy unversioned statuses path group a project's statuses by issue type?
      - Is there an older project statuses endpoint outside /rest/api/3 that I can still call?
      instructions:
      - text: List statuses for project {projectIdOrKey} using the unversioned /project path.
        slots:
          projectIdOrKey: path.projectIdOrKey
      - text: Via the legacy path without /rest/api/3, show the valid statuses per issue type in project {projectIdOrKey}.
        slots:
          projectIdOrKey: path.projectIdOrKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/project'].get
  update:
    x-apievangelist-phrasing:
      intent: List every project I can see in one response
      effect: read
      questions:
      - How do I get every Jira project visible to me in a single unpaginated call?
      - Is the deprecated get-all-projects call on /rest/api/3 still able to include project properties?
      instructions:
      - text: List all projects visible to me using the deprecated /rest/api/3/project call.
      - text: Get the full unpaginated project list from /rest/api/3/project including properties {properties}.
        slots:
          properties: query.properties
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/project'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new project from a template
      effect: write
      questions:
      - How do I create a new Jira project with a key and a name?
      - Can I pick a project template and type when creating a project?
      - Which schemes can I attach when setting up a new project?
      instructions:
      - text: Create a project named {name} with key {key}.
        slots:
          name: requestBody.name
          key: requestBody.key
      - text: Create project {name} with key {key} from template {projectTemplateKey}, led by {leadAccountId}.
        slots:
          name: requestBody.name
          key: requestBody.key
          projectTemplateKey: requestBody.projectTemplateKey
          leadAccountId: requestBody.leadAccountId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/project/recent'].get
  update:
    x-apievangelist-phrasing:
      intent: List projects I viewed recently
      effect: read
      questions:
      - Which projects have I looked at recently?
      - What are the up to 20 projects I viewed most recently?
      instructions:
      - text: Show my recently viewed projects.
      - text: List the projects I've viewed lately, expanded with {expand}.
        slots:
          expand: query.expand
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/project/search'].get
  update:
    x-apievangelist-phrasing:
      intent: Search and page through projects
      effect: read
      questions:
      - How do I search for projects by name or key with pagination?
      - Can I find only archived or deleted projects?
      - Is it possible to filter projects by a property value?
      instructions:
      - text: Search projects whose name or key contains {query}.
        slots:
          query: query.query
      - text: Find projects with keys {keys}, ordered by {orderBy}.
        slots:
          keys: query.keys
          orderBy: query.orderBy
      - text: List projects with status {status} where I can perform action {action}.
        slots:
          status: query.status
          action: query.action
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/project/{projectIdOrKey}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a project's details
      effect: read
      questions:
      - What issue types, components and versions does a project have?
      - Can I look up a project by its key instead of its ID?
      instructions:
      - text: Get the details of project {projectIdOrKey}.
        slots:
          projectIdOrKey: path.projectIdOrKey
      - text: Show project {projectIdOrKey} including properties {properties}.
        slots:
          projectIdOrKey: path.projectIdOrKey
          properties: query.properties
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/project/{projectIdOrKey}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a project's details or schemes
      effect: write
      questions:
      - How do I change a project's name or lead?
      - Can I swap the permission or notification scheme on an existing project?
      instructions:
      - text: Rename project {projectIdOrKey} to {name}.
        slots:
          projectIdOrKey: path.projectIdOrKey
          name: requestBody.name
      - text: Make {leadAccountId} the lead of project {projectIdOrKey}.
        slots:
          leadAccountId: requestBody.leadAccountId
          projectIdOrKey: path.projectIdOrKey
      - text: Set the permission scheme of project {projectIdOrKey} to {permissionScheme}.
        slots:
          projectIdOrKey: path.projectIdOrKey
          permissionScheme: requestBody.permissionScheme
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/project/{projectIdOrKey}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a project
      effect: destructive
      questions:
      - Can I delete a project but keep the option to undo it?
      - Why can't I delete a project that has been archived?
      instructions:
      - text: Delete project {projectIdOrKey}.
        slots:
          projectIdOrKey: path.projectIdOrKey
      - text: Delete project {projectIdOrKey} with undo set to {enableUndo}.
        slots:
          projectIdOrKey: path.projectIdOrKey
          enableUndo: query.enableUndo
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/project/{projectIdOrKey}/archive'].post
  update:
    x-apievangelist-phrasing:
      intent: Archive a project
      effect: write
      questions:
      - How do I archive a project that's no longer active?
      - What happens if I try to delete a project after archiving it?
      instructions:
      - text: Archive project {projectIdOrKey}.
        slots:
          projectIdOrKey: path.projectIdOrKey
      - text: Move project {projectIdOrKey} into the archive.
        slots:
          projectIdOrKey: path.projectIdOrKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/project/{projectIdOrKey}/delete'].post
  update:
    x-apievangelist-phrasing:
      intent: Delete a project as a background task
      effect: destructive
      questions:
      - Can I delete a large project as a transactional background task?
      - Where do I track the progress of an asynchronous project deletion?
      instructions:
      - text: Delete project {projectIdOrKey} asynchronously and give me the task link.
        slots:
          projectIdOrKey: path.projectIdOrKey
      - text: Start a background deletion of project {projectIdOrKey}.
        slots:
          projectIdOrKey: path.projectIdOrKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/project/{projectIdOrKey}/restore'].post
  update:
    x-apievangelist-phrasing:
      intent: Restore an archived or deleted project
      effect: write
      questions:
      - How do I bring back a project from the recycle bin?
      - Can I unarchive a project through the API?
      instructions:
      - text: Restore project {projectIdOrKey}.
        slots:
          projectIdOrKey: path.projectIdOrKey
      - text: Bring archived project {projectIdOrKey} back into use.
        slots:
          projectIdOrKey: path.projectIdOrKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/project/{projectIdOrKey}/statuses'].get
  update:
    x-apievangelist-phrasing:
      intent: List valid statuses for each issue type in a project
      effect: read
      questions:
      - What statuses can issues move through in a given project?
      - Which statuses apply to each issue type in my project?
      instructions:
      - text: List the statuses for project {projectIdOrKey}, grouped by issue type.
        slots:
          projectIdOrKey: path.projectIdOrKey
      - text: Show which statuses each issue type can have in project {projectIdOrKey}.
        slots:
          projectIdOrKey: path.projectIdOrKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/project/{projectId}/hierarchy'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a next-gen project's issue type hierarchy
      effect: read
      questions:
      - How are epics, stories and subtasks layered in a team-managed project?
      - What issue type levels exist in a next-gen project?
      instructions:
      - text: Get the issue type hierarchy for project {projectId}.
        slots:
          projectId: path.projectId
      - text: Show the epic, standard and subtask levels in next-gen project {projectId}.
        slots:
          projectId: path.projectId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/project/{projectKeyOrId}/notificationscheme'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the notification scheme a project uses
      effect: read
      questions:
      - Which notification scheme is attached to my project?
      - Who gets emailed about events in a project, per its notification scheme?
      instructions:
      - text: Get the notification scheme for project {projectKeyOrId}.
        slots:
          projectKeyOrId: path.projectKeyOrId
      - text: Show project {projectKeyOrId}'s notification scheme expanded with {expand}.
        slots:
          projectKeyOrId: path.projectKeyOrId
          expand: query.expand
      method: generated
      generated: '2026-09-26'