# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Snyk Broker Connections API
  version: 1.0.0
extends: openapi/snyk-brokerconnections-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: 12
- target: $.paths['/orgs/{org_id}/brokers/connections'].get
  update:
    x-apievangelist-phrasing:
      intent: List Broker connections used by an organization
      effect: read
      questions:
      - Which Broker connections are wired into my Snyk organization?
      - Can I see the Broker connections an org is integrated with?
      instructions:
      - text: List the Broker connections for org {org_id}.
        slots:
          org_id: path.org_id
      - text: Show which brokered connections organization {org_id} uses.
        slots:
          org_id: path.org_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/tenants/{tenant_id}/brokers/connections/{connection_id}/integrations'].get
  update:
    x-apievangelist-phrasing:
      intent: List integrations using a Broker connection
      effect: read
      questions:
      - Which integrations depend on a particular Broker connection?
      - Before I remove a Broker connection, can I see what integrations use it?
      instructions:
      - text: List integrations using Broker connection {connection_id} in tenant {tenant_id}.
        slots:
          connection_id: path.connection_id
          tenant_id: path.tenant_id
      - text: Show every integration that routes through connection {connection_id} for tenant {tenant_id}.
        slots:
          connection_id: path.connection_id
          tenant_id: path.tenant_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/tenants/{tenant_id}/brokers/connections/{connection_id}/orgs/{org_id}/integration'].post
  update:
    x-apievangelist-phrasing:
      intent: Point an org's integration at a Broker connection
      effect: write
      questions:
      - How do I make an organization's integration use a specific Broker connection?
      - Can I attach a Broker connection to one org's integration configuration?
      instructions:
      - text: Configure org {org_id} to use Broker connection {connection_id} in tenant {tenant_id}.
        slots:
          org_id: path.org_id
          connection_id: path.connection_id
          tenant_id: path.tenant_id
      - text: Create the integration configuration linking connection {connection_id} to organization {org_id} under tenant {tenant_id}.
        slots:
          connection_id: path.connection_id
          org_id: path.org_id
          tenant_id: path.tenant_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/tenants/{tenant_id}/brokers/connections/{connection_id}/orgs/{org_id}/integrations/{integration_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Detach an integration from a Broker connection
      effect: destructive
      questions:
      - How do I stop one org integration from using a Broker connection?
      - Can I unlink a single integration without deleting the whole connection?
      instructions:
      - text: Remove integration {integration_id} of org {org_id} from Broker connection {connection_id} in tenant {tenant_id}.
        slots:
          integration_id: path.integration_id
          org_id: path.org_id
          connection_id: path.connection_id
          tenant_id: path.tenant_id
      - text: Unlink integration {integration_id} from connection {connection_id} for org {org_id}, tenant {tenant_id}.
        slots:
          integration_id: path.integration_id
          connection_id: path.connection_id
          org_id: path.org_id
          tenant_id: path.tenant_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/tenants/{tenant_id}/brokers/installs/{install_id}/deployments/{deployment_id}/connections'].get
  update:
    x-apievangelist-phrasing:
      intent: List Broker connections in a deployment
      effect: read
      questions:
      - What Broker connections are configured on a given Broker deployment?
      - Can I list all connections under one Universal Broker deployment?
      instructions:
      - text: List connections in deployment {deployment_id} of install {install_id}, tenant {tenant_id}.
        slots:
          deployment_id: path.deployment_id
          install_id: path.install_id
          tenant_id: path.tenant_id
      - text: Show the Broker connections for deployment {deployment_id} (install {install_id}, tenant {tenant_id}).
        slots:
          deployment_id: path.deployment_id
          install_id: path.install_id
          tenant_id: path.tenant_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/tenants/{tenant_id}/brokers/installs/{install_id}/deployments/{deployment_id}/connections'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a Broker connection on a deployment
      effect: write
      questions:
      - How do I add a new Broker connection to a deployment?
      - Can I create a connection for a Universal Broker deployment through the API?
      instructions:
      - text: Create a Broker connection on deployment {deployment_id} for install {install_id} in tenant {tenant_id}.
        slots:
          deployment_id: path.deployment_id
          install_id: path.install_id
          tenant_id: path.tenant_id
      - text: Add a new connection to Broker deployment {deployment_id} (tenant {tenant_id}, install {install_id}).
        slots:
          deployment_id: path.deployment_id
          tenant_id: path.tenant_id
          install_id: path.install_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/tenants/{tenant_id}/brokers/installs/{install_id}/deployments/{deployment_id}/connections'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete all Broker connections on a deployment
      effect: destructive
      questions:
      - How do I wipe every Broker connection from a deployment at once?
      - Can I clear all connections on a deployment in one call?
      instructions:
      - text: Delete all Broker connections on deployment {deployment_id}, install {install_id}, tenant {tenant_id}.
        slots:
          deployment_id: path.deployment_id
          install_id: path.install_id
          tenant_id: path.tenant_id
      - text: Remove every connection from Broker deployment {deployment_id} under install {install_id} in tenant {tenant_id}.
        slots:
          deployment_id: path.deployment_id
          install_id: path.install_id
          tenant_id: path.tenant_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/tenants/{tenant_id}/brokers/installs/{install_id}/deployments/{deployment_id}/connections/{connection_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one Broker connection's details
      effect: read
      questions:
      - Where can I see the configuration of a single Broker connection?
      - Can I fetch one connection's data by its connection ID?
      instructions:
      - text: Get Broker connection {connection_id} on deployment {deployment_id}, install {install_id}, tenant {tenant_id}.
        slots:
          connection_id: path.connection_id
          deployment_id: path.deployment_id
          install_id: path.install_id
          tenant_id: path.tenant_id
      - text: Show connection {connection_id} details for deployment {deployment_id} in tenant {tenant_id}, install {install_id}.
        slots:
          connection_id: path.connection_id
          deployment_id: path.deployment_id
          tenant_id: path.tenant_id
          install_id: path.install_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/tenants/{tenant_id}/brokers/installs/{install_id}/deployments/{deployment_id}/connections/{connection_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a single Broker connection
      effect: destructive
      questions:
      - How do I delete just one Broker connection from a deployment?
      - Can I remove a specific connection by ID and keep the others?
      instructions:
      - text: Delete Broker connection {connection_id} from deployment {deployment_id}, install {install_id}, tenant {tenant_id}.
        slots:
          connection_id: path.connection_id
          deployment_id: path.deployment_id
          install_id: path.install_id
          tenant_id: path.tenant_id
      - text: Remove only connection {connection_id} on deployment {deployment_id} (tenant {tenant_id}, install {install_id}).
        slots:
          connection_id: path.connection_id
          deployment_id: path.deployment_id
          tenant_id: path.tenant_id
          install_id: path.install_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/tenants/{tenant_id}/brokers/installs/{install_id}/deployments/{deployment_id}/connections/{connection_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a Broker connection's configuration
      effect: write
      questions:
      - How do I change the configuration of an existing Broker connection?
      - Can I edit a connection in place instead of recreating it?
      instructions:
      - text: Update Broker connection {connection_id} on deployment {deployment_id}, install {install_id}, tenant {tenant_id}.
        slots:
          connection_id: path.connection_id
          deployment_id: path.deployment_id
          install_id: path.install_id
          tenant_id: path.tenant_id
      - text: Edit the settings of connection {connection_id} in deployment {deployment_id} for tenant {tenant_id}, install {install_id}.
        slots:
          connection_id: path.connection_id
          deployment_id: path.deployment_id
          tenant_id: path.tenant_id
          install_id: path.install_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/tenants/{tenant_id}/brokers/installs/{install_id}/deployments/{deployment_id}/connections/{connection_id}/bulk_migration'].get
  update:
    x-apievangelist-phrasing:
      intent: List orgs eligible for bulk Universal Broker migration
      effect: read
      questions:
      - Which organizations would be moved if I bulk migrate to Universal Broker?
      - Can I preview the org IDs tied to a connection type before migrating?
      instructions:
      - text: List orgs to bulk migrate for connection {connection_id} on deployment {deployment_id}, install {install_id}, tenant {tenant_id}.
        slots:
          connection_id: path.connection_id
          deployment_id: path.deployment_id
          install_id: path.install_id
          tenant_id: path.tenant_id
      - text: Show migration candidates for connection {connection_id} (tenant {tenant_id}, install {install_id}, deployment {deployment_id}).
        slots:
          connection_id: path.connection_id
          tenant_id: path.tenant_id
          install_id: path.install_id
          deployment_id: path.deployment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/tenants/{tenant_id}/brokers/installs/{install_id}/deployments/{deployment_id}/connections/{connection_id}/bulk_migration'].post
  update:
    x-apievangelist-phrasing:
      intent: Bulk migrate integrations to Universal Broker
      effect: write
      questions:
      - How do I move legacy brokered integrations onto Universal Broker in bulk?
      - Can I migrate many orgs' integrations to a Universal Broker connection at once?
      instructions:
      - text: Bulk migrate integrations to Universal Broker connection {connection_id} on deployment {deployment_id}, install {install_id}, tenant {tenant_id}.
        slots:
          connection_id: path.connection_id
          deployment_id: path.deployment_id
          install_id: path.install_id
          tenant_id: path.tenant_id
      - text: Run the legacy-to-universal migration for connection {connection_id} in tenant {tenant_id} (install {install_id}, deployment {deployment_id}).
        slots:
          connection_id: path.connection_id
          tenant_id: path.tenant_id
          install_id: path.install_id
          deployment_id: path.deployment_id
      method: generated
      generated: '2026-09-26'