# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Postman API Catalog API
  version: 1.0.0
extends: openapi/postman-apicatalog-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: 16
- target: $.paths['/api-catalog/discovery-services'].get
  update:
    x-apievangelist-phrasing:
      intent: List discovered services
      effect: read
      questions:
      - Which services has API Catalog discovered in my infrastructure that aren't catalogued yet?
      - Can I filter discovered services by discovery source or status?
      - How do I search discovered services by name?
      instructions:
      - text: List the services discovered from source {discoverySource}.
        slots:
          discoverySource: query.discoverySource
      - text: Find discovered services matching {search} with status {status}.
        slots:
          search: query.search
          status: query.status
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api-catalog/discovery-services'].post
  update:
    x-apievangelist-phrasing:
      intent: Add discovered services to API Catalog
      effect: write
      questions:
      - How do I promote discovered services into the API Catalog?
      - How many discovered services can I add to the catalog in one call?
      instructions:
      - text: 'Add these discovered services to the API Catalog: {discoveredServices}.'
        slots:
          discoveredServices: requestBody.discoveredServices
      - text: Catalog discovered services {discoveredServices}.
        slots:
          discoveredServices: requestBody.discoveredServices
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api-catalog/discovery-services/{serviceId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a discovered service's details
      effect: read
      questions:
      - What endpoints and OpenAPI spec were detected for a discovered service?
      - Can I see the inferred specification of a service before adding it to the catalog?
      instructions:
      - text: Show the details of discovered service {serviceId}.
        slots:
          serviceId: path.serviceId
      - text: Get the detected endpoints and spec for discovered service {serviceId}.
        slots:
          serviceId: path.serviceId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api-catalog/services'].get
  update:
    x-apievangelist-phrasing:
      intent: List catalogued services in an environment
      effect: read
      questions:
      - Which services are catalogued in my production system environment?
      - Can I filter catalog services by tag or governance group?
      instructions:
      - text: List all catalogued services in system environment {systemEnvironmentId}.
        slots:
          systemEnvironmentId: query.systemEnvironmentId
      - text: Show services tagged {tags} in system environment {systemEnvironmentId}.
        slots:
          tags: query.tags
          systemEnvironmentId: query.systemEnvironmentId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api-catalog/services/{serviceId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a catalogued service's health and ownership
      effect: read
      questions:
      - What is the health, traffic and compliance status of one service in the catalog?
      - Who owns a catalogued service and what does it depend on?
      instructions:
      - text: Show service {serviceId} in system environment {systemEnvironmentId}.
        slots:
          serviceId: path.serviceId
          systemEnvironmentId: query.systemEnvironmentId
      - text: Get the ownership and dependencies of catalog service {serviceId} in environment {systemEnvironmentId}.
        slots:
          serviceId: path.serviceId
          systemEnvironmentId: query.systemEnvironmentId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api-catalog/services/{serviceId}/endpoints'].get
  update:
    x-apievangelist-phrasing:
      intent: List a service's observed endpoints and metrics
      effect: read
      questions:
      - Which endpoints of a service are actually receiving traffic, and how are they performing?
      - Can I filter a service's observed endpoints by HTTP method or response code?
      instructions:
      - text: List the observed endpoints of service {serviceId} in environment {systemEnvironmentId}.
        slots:
          serviceId: path.serviceId
          systemEnvironmentId: query.systemEnvironmentId
      - text: Show service {serviceId}'s endpoints returning {responseCodes} in environment {systemEnvironmentId}.
        slots:
          serviceId: path.serviceId
          responseCodes: query.responseCodes
          systemEnvironmentId: query.systemEnvironmentId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api-catalog/services/{serviceId}/monitor-runs'].get
  update:
    x-apievangelist-phrasing:
      intent: List a service's scheduled monitor runs
      effect: read
      questions:
      - How have the scheduled monitors for a catalogued service been doing lately?
      - Can I see only the failed monitor runs for one service?
      instructions:
      - text: List monitor runs for service {serviceId} in environment {systemEnvironmentId}.
        slots:
          serviceId: path.serviceId
          systemEnvironmentId: query.systemEnvironmentId
      - text: Show service {serviceId}'s monitor runs with status {status} in environment {systemEnvironmentId}.
        slots:
          serviceId: path.serviceId
          status: query.status
          systemEnvironmentId: query.systemEnvironmentId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api-catalog/services/{serviceId}/spec-lints'].get
  update:
    x-apievangelist-phrasing:
      intent: List a service's spec lint results
      effect: read
      questions:
      - How many governance issues did the latest spec lint find on a service?
      - Can I filter a service's lint runs by severity?
      instructions:
      - text: Show the specification lint runs for service {serviceId}.
        slots:
          serviceId: path.serviceId
      - text: List {severity} lint issues on spec {specId} for service {serviceId}.
        slots:
          severity: query.severity
          specId: query.specId
          serviceId: path.serviceId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api-catalog/services/{serviceId}/ci-runs'].get
  update:
    x-apievangelist-phrasing:
      intent: List a service's CI collection runs
      effect: read
      questions:
      - Which CI pipeline runs executed collections against a service, and did they pass?
      - Can I filter a service's CI runs by Git branch or repository?
      instructions:
      - text: List CI runs for service {serviceId} in environment {systemEnvironmentId}.
        slots:
          serviceId: path.serviceId
          systemEnvironmentId: query.systemEnvironmentId
      - text: Show CI runs on branch {branch} for service {serviceId} in environment {systemEnvironmentId}.
        slots:
          branch: query.branch
          serviceId: path.serviceId
          systemEnvironmentId: query.systemEnvironmentId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api-catalog/system-environments'].get
  update:
    x-apievangelist-phrasing:
      intent: List the team's system environments
      effect: read
      questions:
      - What system environments has my team set up in the API Catalog?
      - Can I list only the production system environments?
      instructions:
      - text: List all of my team's system environments.
      - text: Show system environments where production is {isProduction}.
        slots:
          isProduction: query.isProduction
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api-catalog/system-environments'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a system environment
      effect: write
      questions:
      - How do I set up a new system environment like staging in the API Catalog?
      - Can I mark a new system environment as production when creating it?
      instructions:
      - text: Create a system environment named {name} with color {color}.
        slots:
          name: requestBody.name
          color: requestBody.color
      - text: Add a production system environment called {name} colored {color}.
        slots:
          name: requestBody.name
          color: requestBody.color
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api-catalog/system-environments/{systemEnvironmentId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a system environment
      effect: read
      questions:
      - What are the settings of one system environment?
      - Is a given system environment flagged as production?
      instructions:
      - text: Get system environment {systemEnvironmentId}.
        slots:
          systemEnvironmentId: path.systemEnvironmentId
      - text: Show the name, color and production flag of system environment {systemEnvironmentId}.
        slots:
          systemEnvironmentId: path.systemEnvironmentId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api-catalog/system-environments/{systemEnvironmentId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a system environment
      effect: write
      questions:
      - How do I rename or recolor a system environment?
      - Does a renamed system environment need a unique name within the team?
      instructions:
      - text: Rename system environment {systemEnvironmentId} to {name}.
        slots:
          systemEnvironmentId: path.systemEnvironmentId
          name: requestBody.name
      - text: Change the color of system environment {systemEnvironmentId} to {color}.
        slots:
          systemEnvironmentId: path.systemEnvironmentId
          color: requestBody.color
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api-catalog/system-environments/{systemEnvironmentId}/associations'].get
  update:
    x-apievangelist-phrasing:
      intent: List workspace environments linked to a system environment
      effect: read
      questions:
      - Which workspace environments are mapped to a system environment?
      - Can I see the associations for a single workspace only?
      instructions:
      - text: List the workspace-environment associations of system environment {systemEnvironmentId}.
        slots:
          systemEnvironmentId: path.systemEnvironmentId
      - text: Show which environments in workspace {workspaceId} map to system environment {systemEnvironmentId}.
        slots:
          workspaceId: query.workspaceId
          systemEnvironmentId: path.systemEnvironmentId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api-catalog/system-environments/{systemEnvironmentId}/associations'].post
  update:
    x-apievangelist-phrasing:
      intent: Link workspace environments to a system environment
      effect: write
      questions:
      - How do I map my Postman workspace environments to a system environment?
      - Can I allow a partial success when some environment associations fail?
      instructions:
      - text: Associate workspace environments {workspaceEnvironmentIds} with system environment {systemEnvironmentId}.
        slots:
          workspaceEnvironmentIds: requestBody.workspaceEnvironmentIds
          systemEnvironmentId: path.systemEnvironmentId
      - text: Link environments {workspaceEnvironmentIds} to system environment {systemEnvironmentId} with allowPartial set to {allowPartial}.
        slots:
          workspaceEnvironmentIds: requestBody.workspaceEnvironmentIds
          systemEnvironmentId: path.systemEnvironmentId
          allowPartial: query.allowPartial
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api-catalog/system-environments/{systemEnvironmentId}/associations'].delete
  update:
    x-apievangelist-phrasing:
      intent: Unlink workspace environments from a system environment
      effect: destructive
      questions:
      - How do I detach workspace environments from a system environment?
      - Can I remove several environment associations at once?
      instructions:
      - text: Remove workspace environments {workspaceEnvironmentIds} from system environment {systemEnvironmentId}.
        slots:
          workspaceEnvironmentIds: requestBody.workspaceEnvironmentIds
          systemEnvironmentId: path.systemEnvironmentId
      - text: Unlink {workspaceEnvironmentIds} from system environment {systemEnvironmentId}.
        slots:
          workspaceEnvironmentIds: requestBody.workspaceEnvironmentIds
          systemEnvironmentId: path.systemEnvironmentId
      method: generated
      generated: '2026-09-26'