# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Atlassian Projects API
  version: 1.0.0
extends: openapi/atlassian-projects-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: 28
- target: $.paths['/workspaces/{workspace}/projects'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a project in a Bitbucket workspace
      effect: write
      questions:
      - How do I group Bitbucket repositories under a new project in my workspace?
      - Can a new Bitbucket workspace project be private and carry an avatar image?
      instructions:
      - text: Create a Bitbucket project named {name} with key {key} in workspace {workspace}.
        slots:
          name: requestBody.name
          key: requestBody.key
          workspace: path.workspace
      - text: Add a private project {name} to my {workspace} Bitbucket workspace.
        slots:
          name: requestBody.name
          workspace: path.workspace
      method: generated
      generated: '2026-10-01'
- target: $.paths['/workspaces/{workspace}/projects/{project_key}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update or create a Bitbucket workspace project by key
      effect: write
      questions:
      - Can I rename an existing Bitbucket project or change its description?
      - Is there a way to create-or-update a Bitbucket project at a known project key?
      instructions:
      - text: Rename Bitbucket project {project_key} in workspace {workspace} to {name}.
        slots:
          project_key: path.project_key
          workspace: path.workspace
          name: requestBody.name
      - text: Change the description of Bitbucket project {project_key} in {workspace} to {description}.
        slots:
          project_key: path.project_key
          workspace: path.workspace
          description: requestBody.description
      method: generated
      generated: '2026-10-01'
- target: $.paths['/workspaces/{workspace}/projects/{project_key}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a Bitbucket workspace project
      effect: destructive
      questions:
      - Why can't I delete a Bitbucket project that still has repositories in it?
      - Is deleting a project from a Bitbucket workspace reversible?
      instructions:
      - text: Delete the empty Bitbucket project {project_key} from workspace {workspace}.
        slots:
          project_key: path.project_key
          workspace: path.workspace
      - text: Permanently remove project {project_key} from my Bitbucket workspace {workspace}.
        slots:
          project_key: path.project_key
          workspace: path.workspace
      method: generated
      generated: '2026-10-01'
- target: $.paths['/workspaces/{workspace}/projects/{project_key}/default-reviewers'].get
  update:
    x-apievangelist-phrasing:
      intent: List a Bitbucket project's default reviewers
      effect: read
      questions:
      - Who gets added automatically as a reviewer on pull requests in this Bitbucket project?
      - Which users are the default reviewers for every repo in a project?
      instructions:
      - text: Show all default pull request reviewers for project {project_key} in workspace {workspace}.
        slots:
          project_key: path.project_key
          workspace: path.workspace
      - text: List the project-level default reviewers in {workspace}/{project_key}.
        slots:
          workspace: path.workspace
          project_key: path.project_key
      method: generated
      generated: '2026-10-01'
- target: $.paths['/workspaces/{workspace}/projects/{project_key}/default-reviewers/{selected_user}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check whether a user is a project default reviewer
      effect: read
      questions:
      - Is a specific person already a default reviewer on my Bitbucket project?
      - Can I look up one default reviewer entry for a project by user?
      instructions:
      - text: Check if {selected_user} is a default reviewer for project {project_key} in {workspace}.
        slots:
          selected_user: path.selected_user
          project_key: path.project_key
          workspace: path.workspace
      - text: Get the default reviewer record for user {selected_user} on Bitbucket project {project_key}, workspace {workspace}.
        slots:
          selected_user: path.selected_user
          project_key: path.project_key
          workspace: path.workspace
      method: generated
      generated: '2026-10-01'
- target: $.paths['/workspaces/{workspace}/projects/{project_key}/default-reviewers/{selected_user}'].put
  update:
    x-apievangelist-phrasing:
      intent: Add a default reviewer to a Bitbucket project
      effect: write
      questions:
      - How do I make someone review every pull request across a Bitbucket project?
      - Is adding a project default reviewer safe to repeat if they're already on the list?
      instructions:
      - text: Add {selected_user} as a default reviewer on project {project_key} in workspace {workspace}.
        slots:
          selected_user: path.selected_user
          project_key: path.project_key
          workspace: path.workspace
      - text: Make user {selected_user} an automatic PR reviewer for all repos in {workspace}/{project_key}.
        slots:
          selected_user: path.selected_user
          workspace: path.workspace
          project_key: path.project_key
      method: generated
      generated: '2026-10-01'
- target: $.paths['/workspaces/{workspace}/projects/{project_key}/default-reviewers/{selected_user}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a default reviewer from a Bitbucket project
      effect: destructive
      questions:
      - How do I stop someone being auto-added as a reviewer on a project's pull requests?
      - Can I take a user off a Bitbucket project's default reviewer list?
      instructions:
      - text: Remove {selected_user} from the default reviewers of project {project_key} in {workspace}.
        slots:
          selected_user: path.selected_user
          project_key: path.project_key
          workspace: path.workspace
      - text: Stop auto-adding {selected_user} as reviewer on Bitbucket project {project_key}, workspace {workspace}.
        slots:
          selected_user: path.selected_user
          project_key: path.project_key
          workspace: path.workspace
      method: generated
      generated: '2026-10-01'
- target: $.paths['/workspaces/{workspace}/projects/{project_key}/permissions-config/groups'].get
  update:
    x-apievangelist-phrasing:
      intent: List group permissions on a Bitbucket project
      effect: read
      questions:
      - Which groups have explicit access to my Bitbucket project?
      - What permission level does each group hold on a project?
      instructions:
      - text: List every explicit group permission on project {project_key} in workspace {workspace}.
        slots:
          project_key: path.project_key
          workspace: path.workspace
      - text: Show which groups can access Bitbucket project {workspace}/{project_key}.
        slots:
          workspace: path.workspace
          project_key: path.project_key
      method: generated
      generated: '2026-10-01'
- target: $.paths['/workspaces/{workspace}/projects/{project_key}/permissions-config/groups/{group_slug}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one group's permission on a Bitbucket project
      effect: read
      questions:
      - Does a particular group have admin, write or read access to my project?
      - Who is allowed to see a single group's permission on a Bitbucket project?
      instructions:
      - text: Get the permission group {group_slug} has on project {project_key} in {workspace}.
        slots:
          group_slug: path.group_slug
          project_key: path.project_key
          workspace: path.workspace
      - text: Check the access level of group {group_slug} for Bitbucket project {project_key}, workspace {workspace}.
        slots:
          group_slug: path.group_slug
          project_key: path.project_key
          workspace: path.workspace
      method: generated
      generated: '2026-10-01'
- target: $.paths['/workspaces/{workspace}/projects/{project_key}/permissions-config/groups/{group_slug}'].put
  update:
    x-apievangelist-phrasing:
      intent: Set a group's permission on a Bitbucket project
      effect: write
      questions:
      - How do I give a group create-repo rights on a Bitbucket project?
      - Can I change a group's project access with an OAuth token?
      instructions:
      - text: Grant group {group_slug} {permission} permission on project {project_key} in workspace {workspace}.
        slots:
          group_slug: path.group_slug
          permission: requestBody.permission
          project_key: path.project_key
          workspace: path.workspace
      - text: Change group {group_slug}'s access to {permission} for Bitbucket project {workspace}/{project_key}.
        slots:
          group_slug: path.group_slug
          permission: requestBody.permission
          workspace: path.workspace
          project_key: path.project_key
      method: generated
      generated: '2026-10-01'
- target: $.paths['/workspaces/{workspace}/projects/{project_key}/permissions-config/groups/{group_slug}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Revoke a group's explicit Bitbucket project permission
      effect: destructive
      questions:
      - How do I take away a group's explicit access to a Bitbucket project?
      - Can I remove the permission link between a project and one group?
      instructions:
      - text: Revoke group {group_slug}'s explicit permission on project {project_key} in {workspace}.
        slots:
          group_slug: path.group_slug
          project_key: path.project_key
          workspace: path.workspace
      - text: Remove group {group_slug} from Bitbucket project {workspace}/{project_key} permissions.
        slots:
          group_slug: path.group_slug
          workspace: path.workspace
          project_key: path.project_key
      method: generated
      generated: '2026-10-01'
- target: $.paths['/workspaces/{workspace}/projects/{project_key}/permissions-config/users'].get
  update:
    x-apievangelist-phrasing:
      intent: List user permissions on a Bitbucket project
      effect: read
      questions:
      - Which individual users have been granted access to my Bitbucket project?
      - What are the explicit per-user permissions on a project?
      instructions:
      - text: List every explicit user permission on project {project_key} in workspace {workspace}.
        slots:
          project_key: path.project_key
          workspace: path.workspace
      - text: Show the individual users with direct access to Bitbucket project {workspace}/{project_key}.
        slots:
          workspace: path.workspace
          project_key: path.project_key
      method: generated
      generated: '2026-10-01'
- target: $.paths['/workspaces/{workspace}/projects/{project_key}/permissions-config/users/{selected_user_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one user's permission on a Bitbucket project
      effect: read
      questions:
      - What access level does a specific user have directly on my Bitbucket project?
      - Does this person have an explicit admin or write grant on the project?
      instructions:
      - text: Get the explicit permission user {selected_user_id} holds on project {project_key} in {workspace}.
        slots:
          selected_user_id: path.selected_user_id
          project_key: path.project_key
          workspace: path.workspace
      - text: Check user {selected_user_id}'s direct access to Bitbucket project {workspace}/{project_key}.
        slots:
          selected_user_id: path.selected_user_id
          workspace: path.workspace
          project_key: path.project_key
      method: generated
      generated: '2026-10-01'
- target: $.paths['/workspaces/{workspace}/projects/{project_key}/permissions-config/users/{selected_user_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Set a user's permission on a Bitbucket project
      effect: write
      questions:
      - How do I give one workspace member write access to a Bitbucket project?
      - Can I set a project permission for the workspace owner?
      instructions:
      - text: Give user {selected_user_id} {permission} access to project {project_key} in workspace {workspace}.
        slots:
          selected_user_id: path.selected_user_id
          permission: requestBody.permission
          project_key: path.project_key
          workspace: path.workspace
      - text: Change {selected_user_id}'s explicit Bitbucket project permission on {workspace}/{project_key} to {permission}.
        slots:
          selected_user_id: path.selected_user_id
          workspace: path.workspace
          project_key: path.project_key
          permission: requestBody.permission
      method: generated
      generated: '2026-10-01'
- target: $.paths['/workspaces/{workspace}/projects/{project_key}/permissions-config/users/{selected_user_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Revoke a user's explicit Bitbucket project permission
      effect: destructive
      questions:
      - How do I remove one person's direct access to a Bitbucket project?
      - Can I delete a user's explicit project grant without touching their group access?
      instructions:
      - text: Revoke user {selected_user_id}'s explicit permission on project {project_key} in {workspace}.
        slots:
          selected_user_id: path.selected_user_id
          project_key: path.project_key
          workspace: path.workspace
      - text: Remove {selected_user_id} from the direct user permissions of Bitbucket project {workspace}/{project_key}.
        slots:
          selected_user_id: path.selected_user_id
          workspace: path.workspace
          project_key: path.project_key
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/project'].get
  update:
    x-apievangelist-phrasing:
      intent: List all visible Jira projects (deprecated)
      effect: read
      questions:
      - Is there a single call that returns every Jira project I can see, without paging?
      - What does the older, deprecated get-all-projects endpoint return in Jira?
      instructions:
      - text: Get every Jira project visible to me using the legacy unpaginated list.
      - text: Return all my Jira projects, limited to the last {recent} I touched, from the old all-projects endpoint.
        slots:
          recent: query.recent
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/project'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a Jira project from a template
      effect: write
      questions:
      - How do I create a new Jira software or business project?
      - Which project template keys can I use when creating a Jira project?
      - Can I assign a permission scheme and project lead when I create a Jira project?
      instructions:
      - text: Create a Jira project named {name} with key {key} led by {leadAccountId}.
        slots:
          name: requestBody.name
          key: requestBody.key
          leadAccountId: requestBody.leadAccountId
      - text: Set up Jira project {key} called {name} using template {projectTemplateKey}.
        slots:
          key: requestBody.key
          name: requestBody.name
          projectTemplateKey: requestBody.projectTemplateKey
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/project/recent'].get
  update:
    x-apievangelist-phrasing:
      intent: List recently viewed Jira projects
      effect: read
      questions:
      - Which Jira projects have I looked at most recently?
      - Can I get my last 20 viewed projects?
      instructions:
      - text: Show the Jira projects I viewed recently.
      - text: List my recently visited projects with {expand} expanded.
        slots:
          expand: query.expand
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/project/search'].get
  update:
    x-apievangelist-phrasing:
      intent: Search Jira projects with filters and paging
      effect: read
      questions:
      - How do I find Jira projects whose name or key matches some text?
      - Can I filter projects by category, type or archived status?
      - Is there a paginated way to page through all projects in my site?
      instructions:
      - text: Search Jira projects matching {query}.
        slots:
          query: query.query
      - text: Find all {typeKey} projects in category {categoryId}, {maxResults} per page.
        slots:
          typeKey: query.typeKey
          categoryId: query.categoryId
          maxResults: query.maxResults
      - text: List archived Jira projects using status {status}.
        slots:
          status: query.status
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/project/{projectIdOrKey}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a Jira project's details
      effect: read
      questions:
      - What are the details of a single Jira project, like its lead and issue types?
      - Can I look up a Jira project by its key instead of its ID?
      instructions:
      - text: Get the details of Jira project {projectIdOrKey}.
        slots:
          projectIdOrKey: path.projectIdOrKey
      - text: Show project {projectIdOrKey} with {expand} included.
        slots:
          projectIdOrKey: path.projectIdOrKey
          expand: query.expand
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/project/{projectIdOrKey}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a Jira project's details or schemes
      effect: write
      questions:
      - How do I change a Jira project's lead or name?
      - Can I swap a project's permission or notification scheme without touching the others?
      instructions:
      - text: Rename Jira project {projectIdOrKey} to {name}.
        slots:
          projectIdOrKey: path.projectIdOrKey
          name: requestBody.name
      - text: Make {leadAccountId} the lead of Jira project {projectIdOrKey}.
        slots:
          leadAccountId: requestBody.leadAccountId
          projectIdOrKey: path.projectIdOrKey
      - text: Apply permission scheme {permissionScheme} to project {projectIdOrKey}.
        slots:
          permissionScheme: requestBody.permissionScheme
          projectIdOrKey: path.projectIdOrKey
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/project/{projectIdOrKey}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a Jira project
      effect: destructive
      questions:
      - Can I delete a Jira project but keep it recoverable in the recycle bin?
      - Why won't Jira let me delete an archived project?
      instructions:
      - text: Delete Jira project {projectIdOrKey}.
        slots:
          projectIdOrKey: path.projectIdOrKey
      - text: Move project {projectIdOrKey} to the recycle bin with undo set to {enableUndo}.
        slots:
          projectIdOrKey: path.projectIdOrKey
          enableUndo: query.enableUndo
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/project/{projectIdOrKey}/archive'].post
  update:
    x-apievangelist-phrasing:
      intent: Archive a Jira project
      effect: write
      questions:
      - How do I archive a Jira project we no longer use?
      - What happens if I try to delete a project after archiving it?
      instructions:
      - text: Archive Jira project {projectIdOrKey}.
        slots:
          projectIdOrKey: path.projectIdOrKey
      - text: Put project {projectIdOrKey} into the archive instead of deleting it.
        slots:
          projectIdOrKey: path.projectIdOrKey
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/project/{projectIdOrKey}/delete'].post
  update:
    x-apievangelist-phrasing:
      intent: Delete a Jira project as a background task
      effect: destructive
      questions:
      - Is there a way to delete a large Jira project as an async task I can track?
      - Does the asynchronous project delete roll back if part of it fails?
      instructions:
      - text: Start an asynchronous delete of Jira project {projectIdOrKey} and give me the task link.
        slots:
          projectIdOrKey: path.projectIdOrKey
      - text: Delete project {projectIdOrKey} in the background as a transactional task.
        slots:
          projectIdOrKey: path.projectIdOrKey
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/project/{projectIdOrKey}/restore'].post
  update:
    x-apievangelist-phrasing:
      intent: Restore an archived or deleted Jira project
      effect: write
      questions:
      - How do I bring back a Jira project from the recycle bin?
      - Can I unarchive a Jira project through the API?
      instructions:
      - text: Restore Jira project {projectIdOrKey}.
        slots:
          projectIdOrKey: path.projectIdOrKey
      - text: Unarchive project {projectIdOrKey} so the team can use it again.
        slots:
          projectIdOrKey: path.projectIdOrKey
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/project/{projectIdOrKey}/statuses'].get
  update:
    x-apievangelist-phrasing:
      intent: List valid statuses per issue type in a project
      effect: read
      questions:
      - What statuses can issues move through in a given Jira project?
      - Which statuses are valid for bugs versus stories in my project?
      instructions:
      - text: List the valid statuses for each issue type in project {projectIdOrKey}.
        slots:
          projectIdOrKey: path.projectIdOrKey
      - text: Show the workflow statuses available in Jira project {projectIdOrKey}, grouped by issue type.
        slots:
          projectIdOrKey: path.projectIdOrKey
      method: generated
      generated: '2026-10-01'
- 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 my team-managed project?
      - What issue type levels exist in a next-gen Jira project?
      instructions:
      - text: Get the issue type hierarchy for next-gen project {projectId}.
        slots:
          projectId: path.projectId
      - text: Show which issue types sit at the epic, standard and subtask levels in project {projectId}.
        slots:
          projectId: path.projectId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/project/{projectKeyOrId}/notificationscheme'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the notification scheme used by a project
      effect: read
      questions:
      - Which notification scheme controls the emails a Jira project sends?
      - Who gets notified about events in my project?
      instructions:
      - text: Get the notification scheme for project {projectKeyOrId}.
        slots:
          projectKeyOrId: path.projectKeyOrId
      - text: Show project {projectKeyOrId}'s notification scheme with {expand} expanded.
        slots:
          projectKeyOrId: path.projectKeyOrId
          expand: query.expand
      method: generated
      generated: '2026-10-01'