# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Atlassian Bitbucket Deployments API
  version: 1.0.0
extends: openapi/atlassian-deployments-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: 16
- target: $.paths['/repositories/{workspace}/{repo_slug}/deploy-keys'].get
  update:
    x-apievangelist-phrasing:
      intent: List a repository's deploy keys
      effect: read
      questions:
      - Which SSH deploy keys have access to this Bitbucket repository?
      - Can I audit the read-only deploy keys added to a single repo?
      instructions:
      - text: List the deploy keys on repository {workspace}/{repo_slug}.
        slots:
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Show every repository-level deploy key for {repo_slug}.
        slots:
          repo_slug: path.repo_slug
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/deploy-keys'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a deploy key to a repository
      effect: write
      questions:
      - How do I give a build server SSH access to one repository with a deploy key?
      - What happens to a deploy key if the OAuth consumer that added it changes?
      instructions:
      - text: Add a new deploy key to repository {workspace}/{repo_slug}.
        slots:
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Register an SSH deploy key for the {repo_slug} repo only.
        slots:
          repo_slug: path.repo_slug
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/deploy-keys/{key_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a repository deploy key
      effect: read
      questions:
      - What label and comment does a particular repository deploy key have?
      - Can I look up one repo deploy key by its ID?
      instructions:
      - text: Get deploy key {key_id} on repository {workspace}/{repo_slug}.
        slots:
          key_id: path.key_id
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Show repo deploy key {key_id} in {repo_slug}.
        slots:
          key_id: path.key_id
          repo_slug: path.repo_slug
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/deploy-keys/{key_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Relabel a repository deploy key
      effect: write
      questions:
      - Can I change the label or comment on an existing repository deploy key?
      - Do I have to resend the key itself when editing a deploy key's label?
      instructions:
      - text: Update the label of deploy key {key_id} on repository {workspace}/{repo_slug}.
        slots:
          key_id: path.key_id
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Change the comment on repo deploy key {key_id} in {repo_slug}.
        slots:
          key_id: path.key_id
          repo_slug: path.repo_slug
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/deploy-keys/{key_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a deploy key from a repository
      effect: destructive
      questions:
      - How do I revoke a deploy key's access to one repository?
      - Can I delete a leaked repository deploy key right away?
      instructions:
      - text: Delete deploy key {key_id} from repository {workspace}/{repo_slug}.
        slots:
          key_id: path.key_id
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Revoke repo deploy key {key_id} on {repo_slug}.
        slots:
          key_id: path.key_id
          repo_slug: path.repo_slug
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/deployments'].get
  update:
    x-apievangelist-phrasing:
      intent: List deployments for a repository
      effect: read
      questions:
      - What deployments have been run from this repository's pipelines?
      - Can I see the deployment history for a Bitbucket repo?
      instructions:
      - text: List deployments for repository {workspace}/{repo_slug}.
        slots:
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Show the deployment history of {repo_slug}.
        slots:
          repo_slug: path.repo_slug
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/deployments/{deployment_uuid}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a deployment
      effect: read
      questions:
      - What's the state of one specific deployment?
      - Can I fetch a single deployment by its UUID?
      instructions:
      - text: Get deployment {deployment_uuid} in {workspace}/{repo_slug}.
        slots:
          deployment_uuid: path.deployment_uuid
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Show details of deployment {deployment_uuid} for repo {repo_slug}.
        slots:
          deployment_uuid: path.deployment_uuid
          repo_slug: path.repo_slug
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/environments'].get
  update:
    x-apievangelist-phrasing:
      intent: List deployment environments for a repo
      effect: read
      questions:
      - Which deployment environments like staging and production are set up for this repo?
      - What environments can pipelines deploy this repository to?
      instructions:
      - text: List the deployment environments for {workspace}/{repo_slug}.
        slots:
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Show all environments configured on repo {repo_slug}.
        slots:
          repo_slug: path.repo_slug
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/environments'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a deployment environment
      effect: write
      questions:
      - How do I add a new environment such as a QA stage for deployments?
      - Can I name a new deployment environment when creating it?
      instructions:
      - text: Create a deployment environment named {name} in {workspace}/{repo_slug}.
        slots:
          name: requestBody.name
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Add environment {name} to repo {repo_slug}.
        slots:
          name: requestBody.name
          repo_slug: path.repo_slug
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/environments/{environment_uuid}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a deployment environment
      effect: read
      questions:
      - What are the details of one deployment environment?
      - Can I look up an environment by its UUID?
      instructions:
      - text: Get environment {environment_uuid} in {workspace}/{repo_slug}.
        slots:
          environment_uuid: path.environment_uuid
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Show deployment environment {environment_uuid} of repo {repo_slug}.
        slots:
          environment_uuid: path.environment_uuid
          repo_slug: path.repo_slug
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/environments/{environment_uuid}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a deployment environment
      effect: destructive
      questions:
      - Can I remove a deployment environment we no longer use?
      - What's the way to delete a stale staging environment from a repo?
      instructions:
      - text: Delete environment {environment_uuid} from {workspace}/{repo_slug}.
        slots:
          environment_uuid: path.environment_uuid
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Remove deployment environment {environment_uuid} in repo {repo_slug}.
        slots:
          environment_uuid: path.environment_uuid
          repo_slug: path.repo_slug
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/environments/{environment_uuid}/changes'].post
  update:
    x-apievangelist-phrasing:
      intent: Update a deployment environment
      effect: write
      questions:
      - How do I change the settings of an existing deployment environment?
      - Can an environment be edited after it's created?
      instructions:
      - text: Apply changes to environment {environment_uuid} in {workspace}/{repo_slug}.
        slots:
          environment_uuid: path.environment_uuid
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Update deployment environment {environment_uuid} for repo {repo_slug}.
        slots:
          environment_uuid: path.environment_uuid
          repo_slug: path.repo_slug
      method: generated
      generated: '2026-10-01'
- target: $.paths['/workspaces/{workspace}/projects/{project_key}/deploy-keys'].get
  update:
    x-apievangelist-phrasing:
      intent: List a project's deploy keys
      effect: read
      questions:
      - Which deploy keys grant access to every repository in a Bitbucket project?
      - Can I list project-level deploy keys rather than per-repo ones?
      instructions:
      - text: List the deploy keys on project {project_key} in workspace {workspace}.
        slots:
          project_key: path.project_key
          workspace: path.workspace
      - text: Show project-level deploy keys for {project_key}.
        slots:
          project_key: path.project_key
      method: generated
      generated: '2026-10-01'
- target: $.paths['/workspaces/{workspace}/projects/{project_key}/deploy-keys'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a deploy key to a project
      effect: write
      questions:
      - How do I add one deploy key that works across all repos in a project?
      - Can a deploy key be added at the project level?
      instructions:
      - text: Add a deploy key to project {project_key} in workspace {workspace}.
        slots:
          project_key: path.project_key
          workspace: path.workspace
      - text: Create a project-wide SSH deploy key for {project_key}.
        slots:
          project_key: path.project_key
      method: generated
      generated: '2026-10-01'
- target: $.paths['/workspaces/{workspace}/projects/{project_key}/deploy-keys/{key_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a project deploy key
      effect: read
      questions:
      - What does a specific project deploy key look like?
      - Can I fetch one project-level deploy key by ID?
      instructions:
      - text: Get deploy key {key_id} on project {project_key} in {workspace}.
        slots:
          key_id: path.key_id
          project_key: path.project_key
          workspace: path.workspace
      - text: Show project deploy key {key_id} for {project_key}.
        slots:
          key_id: path.key_id
          project_key: path.project_key
      method: generated
      generated: '2026-10-01'
- target: $.paths['/workspaces/{workspace}/projects/{project_key}/deploy-keys/{key_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a deploy key from a project
      effect: destructive
      questions:
      - How do I revoke a project-wide deploy key?
      - Can I delete a deploy key from a whole project at once?
      instructions:
      - text: Delete deploy key {key_id} from project {project_key} in {workspace}.
        slots:
          key_id: path.key_id
          project_key: path.project_key
          workspace: path.workspace
      - text: Revoke project deploy key {key_id} on {project_key}.
        slots:
          key_id: path.key_id
          project_key: path.project_key
      method: generated
      generated: '2026-10-01'