# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Bitbucket Deployments API
  version: 1.0.0
extends: openapi/bitbucket-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 read-only access keys are installed on this repo?
      - Can I audit the deploy keys that can clone a repository?
      instructions:
      - text: List deploy keys on repository {workspace}/{repo_slug}.
        slots:
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Show every access key added to repo {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 a single repo?
      - Can I add a labelled access key to one repository?
      instructions:
      - text: Add a deploy key to repository {workspace}/{repo_slug}.
        slots:
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Install a new access key for my CI server on repo {repo_slug}.
        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 specific repo deploy key have?
      - When was a particular repository access key last used?
      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 access key {key_id}'s label.
        slots:
          key_id: path.key_id
      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:
      - How do I rename the label on an existing repo deploy key?
      - Can I change a repository access key's comment without replacing it?
      instructions:
      - text: Update the label on deploy key {key_id} in repository {workspace}/{repo_slug}.
        slots:
          key_id: path.key_id
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Change the comment on repo access key {key_id}.
        slots:
          key_id: path.key_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/deploy-keys/{key_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a repository deploy key
      effect: destructive
      questions:
      - How do I revoke a deploy key from one repo?
      - Can I delete a repository access key that leaked?
      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 access 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}/deployments'].get
  update:
    x-apievangelist-phrasing:
      intent: List deployments in a repository
      effect: read
      questions:
      - What has been deployed from this repository recently?
      - Can I see the deployment history across all environments of a repo?
      instructions:
      - text: List deployments in {workspace}/{repo_slug}.
        slots:
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Show the deployment history for repo {repo_slug} in workspace {workspace}.
        slots:
          repo_slug: path.repo_slug
          workspace: path.workspace
      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 see which release and environment a given deployment targeted?
      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
      effect: read
      questions:
      - Which deployment environments are set up for this repo?
      - Can I list test, staging and production environments for a repository?
      instructions:
      - text: List deployment environments for {workspace}/{repo_slug}.
        slots:
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Show every environment 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 deployment environment like QA to a repo?
      - Can I create a named environment for tracking deployments?
      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 settings 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 the details of deployment environment {environment_uuid} on 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:
      - How do I delete a deployment environment we no longer use?
      - Can I remove an environment from a repository entirely?
      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} on 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: Change a deployment environment's settings
      effect: write
      questions:
      - How do I rename or reconfigure an existing deployment environment?
      - Can I submit changes to an environment's settings through the API?
      instructions:
      - text: Update environment {environment_uuid} in {workspace}/{repo_slug}.
        slots:
          environment_uuid: path.environment_uuid
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Apply changes to deployment environment {environment_uuid} on 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 access keys can read every repo in a project?
      - Can I see the deploy keys set at project level?
      instructions:
      - text: List deploy keys on project {project_key} in {workspace}.
        slots:
          project_key: path.project_key
          workspace: path.workspace
      - text: Show project-level access 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 give one SSH key read access to all repos in a project?
      - Can a single access key cover a whole project?
      instructions:
      - text: Add a deploy key to project {project_key} in {workspace}.
        slots:
          project_key: path.project_key
          workspace: path.workspace
      - text: Create a project-wide access key on {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 are the details of one project-level deploy key?
      - Can I look up a project access key by its 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 access 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 project deploy key
      effect: destructive
      questions:
      - How do I revoke a project-wide deploy key?
      - Can I delete an access key from a project?
      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 access key {key_id} on {project_key}.
        slots:
          key_id: path.key_id
          project_key: path.project_key
      method: generated
      generated: '2026-10-01'