# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Acquia Cloud API Documentation Subscriptions API
  version: 1.0.0
extends: openapi/acquia-subscriptions-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: 31
- target: $.paths['/subscriptions'].get
  update:
    x-apievangelist-phrasing:
      intent: List my subscriptions
      effect: read
      questions:
      - Which Acquia subscriptions do I belong to?
      - Can I page through all of my subscriptions?
      instructions:
      - text: List all of my subscriptions.
      - text: Show subscriptions matching {filter}.
        slots:
          filter: query.filter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionUuid}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get details of a subscription
      effect: read
      questions:
      - What details are stored on a single subscription?
      - Can I look up one subscription by its UUID?
      instructions:
      - text: Show subscription {subscriptionUuid}.
        slots:
          subscriptionUuid: path.subscriptionUuid
      - text: Get the details of subscription {subscriptionUuid}.
        slots:
          subscriptionUuid: path.subscriptionUuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionUuid}'].put
  update:
    x-apievangelist-phrasing:
      intent: Rename a subscription
      effect: write
      questions:
      - Can I change the name of a subscription?
      - How do I rename my subscription?
      instructions:
      - text: Rename subscription {subscriptionUuid} to {name}.
        slots:
          subscriptionUuid: path.subscriptionUuid
          name: requestBody.name
      - text: Set the name of subscription {subscriptionUuid} to {name}.
        slots:
          subscriptionUuid: path.subscriptionUuid
          name: requestBody.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionUuid}/applications'].get
  update:
    x-apievangelist-phrasing:
      intent: List applications in a subscription
      effect: read
      questions:
      - Which applications are part of this subscription?
      - Can I filter the apps that belong to a subscription?
      instructions:
      - text: List applications in subscription {subscriptionUuid}.
        slots:
          subscriptionUuid: path.subscriptionUuid
      - text: Show subscription {subscriptionUuid} applications matching {filter}.
        slots:
          subscriptionUuid: path.subscriptionUuid
          filter: query.filter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionUuid}/code-studio'].get
  update:
    x-apievangelist-phrasing:
      intent: Get Code Studio metadata for a subscription
      effect: read
      questions:
      - Is Code Studio provisioned on my subscription?
      - What Code Studio details are recorded for a subscription?
      instructions:
      - text: Show Code Studio metadata for subscription {subscriptionUuid}.
        slots:
          subscriptionUuid: path.subscriptionUuid
      - text: Get the Code Studio status of subscription {subscriptionUuid}.
        slots:
          subscriptionUuid: path.subscriptionUuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionUuid}/code-studio'].options
  update:
    x-apievangelist-phrasing:
      intent: Show Code Studio options for a subscription
      effect: read
      questions:
      - What Code Studio options are available on my subscription?
      - Which actions does the subscription Code Studio resource allow?
      instructions:
      - text: Display the Code Studio options for subscription {subscriptionUuid}.
        slots:
          subscriptionUuid: path.subscriptionUuid
      - text: Check which Code Studio operations subscription {subscriptionUuid} supports.
        slots:
          subscriptionUuid: path.subscriptionUuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionUuid}/code-studio/actions/enable'].post
  update:
    x-apievangelist-phrasing:
      intent: Enable Code Studio on a subscription
      effect: write
      questions:
      - How do I turn on Code Studio for my whole subscription?
      - Can I provision Code Studio at the subscription level?
      instructions:
      - text: Enable Code Studio for subscription {subscriptionUuid}.
        slots:
          subscriptionUuid: path.subscriptionUuid
      - text: Provision Code Studio on subscription {subscriptionUuid}.
        slots:
          subscriptionUuid: path.subscriptionUuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionUuid}/code-studio/applications'].get
  update:
    x-apievangelist-phrasing:
      intent: List Code Studio-enabled applications
      effect: read
      questions:
      - Which of my subscription's applications use Code Studio?
      - Can I see only the apps with Code Studio turned on?
      instructions:
      - text: List Code Studio-enabled applications in subscription {subscriptionUuid}.
        slots:
          subscriptionUuid: path.subscriptionUuid
      - text: Show which apps in subscription {subscriptionUuid} have Code Studio.
        slots:
          subscriptionUuid: path.subscriptionUuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionUuid}/code-studio/users'].get
  update:
    x-apievangelist-phrasing:
      intent: List users holding Code Studio seats
      effect: read
      questions:
      - Who is using a Code Studio seat on my subscription?
      - How many Code Studio seats are assigned right now?
      instructions:
      - text: List Code Studio users for subscription {subscriptionUuid}.
        slots:
          subscriptionUuid: path.subscriptionUuid
      - text: Show everyone assigned a Code Studio seat in subscription {subscriptionUuid}.
        slots:
          subscriptionUuid: path.subscriptionUuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionUuid}/code-studio/users'].post
  update:
    x-apievangelist-phrasing:
      intent: Assign a user a Code Studio seat
      effect: write
      questions:
      - How do I give a teammate a Code Studio seat?
      - Can I assign a role when adding someone to Code Studio?
      instructions:
      - text: Assign user {user_id} a Code Studio seat in subscription {subscriptionUuid}.
        slots:
          user_id: requestBody.user_id
          subscriptionUuid: path.subscriptionUuid
      - text: Add {user_id} to Code Studio on subscription {subscriptionUuid} with role {role}.
        slots:
          user_id: requestBody.user_id
          subscriptionUuid: path.subscriptionUuid
          role: requestBody.role
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionUuid}/code-studio/users/{userUuid}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one Code Studio user
      effect: read
      questions:
      - What role does a particular person have in Code Studio?
      - Can I check the seat details for one Code Studio user?
      instructions:
      - text: Show Code Studio user {userUuid} in subscription {subscriptionUuid}.
        slots:
          userUuid: path.userUuid
          subscriptionUuid: path.subscriptionUuid
      - text: Get the Code Studio seat details for {userUuid} on subscription {subscriptionUuid}.
        slots:
          userUuid: path.userUuid
          subscriptionUuid: path.subscriptionUuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionUuid}/code-studio/users/{userUuid}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Unassign a user's Code Studio seat
      effect: destructive
      questions:
      - Can I free up a Code Studio seat from someone who left?
      - How do I remove a person from Code Studio?
      instructions:
      - text: Unassign {userUuid} from Code Studio in subscription {subscriptionUuid}.
        slots:
          userUuid: path.userUuid
          subscriptionUuid: path.subscriptionUuid
      - text: Release the Code Studio seat held by {userUuid} on subscription {subscriptionUuid}.
        slots:
          userUuid: path.userUuid
          subscriptionUuid: path.subscriptionUuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionUuid}/domains'].get
  update:
    x-apievangelist-phrasing:
      intent: List domains registered to a subscription
      effect: read
      questions:
      - Which email domains are registered on my subscription?
      - Can I filter a subscription's registered domains?
      instructions:
      - text: List domains registered with subscription {subscriptionUuid}.
        slots:
          subscriptionUuid: path.subscriptionUuid
      - text: Show registered domains in subscription {subscriptionUuid} matching {filter}.
        slots:
          subscriptionUuid: path.subscriptionUuid
          filter: query.filter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionUuid}/domains'].post
  update:
    x-apievangelist-phrasing:
      intent: Register a domain with a subscription
      effect: write
      questions:
      - How do I register a new sending domain on my subscription?
      - Can I add my company domain to a subscription for Platform Email?
      instructions:
      - text: Register domain {domain} with subscription {subscriptionUuid}.
        slots:
          domain: requestBody.domain
          subscriptionUuid: path.subscriptionUuid
      - text: Add {domain} as a registered domain on subscription {subscriptionUuid}.
        slots:
          domain: requestBody.domain
          subscriptionUuid: path.subscriptionUuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionUuid}/domains/{domainRegistrationUuid}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one registered domain
      effect: read
      questions:
      - What is the verification status of a domain I registered?
      - Can I see the DNS details for one registered domain?
      instructions:
      - text: Show domain registration {domainRegistrationUuid} on subscription {subscriptionUuid}.
        slots:
          domainRegistrationUuid: path.domainRegistrationUuid
          subscriptionUuid: path.subscriptionUuid
      - text: Get details of registered domain {domainRegistrationUuid} in subscription {subscriptionUuid}.
        slots:
          domainRegistrationUuid: path.domainRegistrationUuid
          subscriptionUuid: path.subscriptionUuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionUuid}/domains/{domainRegistrationUuid}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Unregister a domain from a subscription
      effect: destructive
      questions:
      - Can I remove a domain I registered on my subscription?
      - How do I unregister an email domain?
      instructions:
      - text: Unregister domain {domainRegistrationUuid} from subscription {subscriptionUuid}.
        slots:
          domainRegistrationUuid: path.domainRegistrationUuid
          subscriptionUuid: path.subscriptionUuid
      - text: Delete domain registration {domainRegistrationUuid} on subscription {subscriptionUuid}.
        slots:
          domainRegistrationUuid: path.domainRegistrationUuid
          subscriptionUuid: path.subscriptionUuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionUuid}/domains/{domainRegistrationUuid}/actions/verify'].post
  update:
    x-apievangelist-phrasing:
      intent: Re-verify a registered domain
      effect: write
      questions:
      - I've updated my DNS records; how do I get the domain re-checked?
      - Can I trigger a fresh verification of a registered domain?
      instructions:
      - text: Re-verify domain {domainRegistrationUuid} on subscription {subscriptionUuid}.
        slots:
          domainRegistrationUuid: path.domainRegistrationUuid
          subscriptionUuid: path.subscriptionUuid
      - text: Refresh the verification status of domain registration {domainRegistrationUuid} in subscription {subscriptionUuid}.
        slots:
          domainRegistrationUuid: path.domainRegistrationUuid
          subscriptionUuid: path.subscriptionUuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionUuid}/entitlements'].get
  update:
    x-apievangelist-phrasing:
      intent: List a subscription's entitlements
      effect: read
      questions:
      - What products and limits am I entitled to on my subscription?
      - Which entitlements come with a subscription?
      instructions:
      - text: List the entitlements of subscription {subscriptionUuid}.
        slots:
          subscriptionUuid: path.subscriptionUuid
      - text: Show what subscription {subscriptionUuid} is entitled to.
        slots:
          subscriptionUuid: path.subscriptionUuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionUuid}/ides'].get
  update:
    x-apievangelist-phrasing:
      intent: List Cloud IDEs in a subscription
      effect: read
      questions:
      - How many Cloud IDEs exist across my subscription?
      - Which Cloud IDEs are tied to a subscription?
      instructions:
      - text: List Cloud IDEs across subscription {subscriptionUuid}.
        slots:
          subscriptionUuid: path.subscriptionUuid
      - text: Show every IDE provisioned under subscription {subscriptionUuid}.
        slots:
          subscriptionUuid: path.subscriptionUuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionUuid}/metrics/usage'].get
  update:
    x-apievangelist-phrasing:
      intent: Get usage metric links for a subscription
      effect: read
      questions:
      - Where do I start to explore usage metrics for a whole subscription?
      - What subscription-level usage reports are available?
      instructions:
      - text: Get usage metric links for subscription {subscriptionUuid}.
        slots:
          subscriptionUuid: path.subscriptionUuid
      - text: Show available usage reports for subscription {subscriptionUuid}.
        slots:
          subscriptionUuid: path.subscriptionUuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionUuid}/metrics/usage/data'].get
  update:
    x-apievangelist-phrasing:
      intent: Get aggregate usage data for a subscription
      effect: read
      questions:
      - How much total traffic did my subscription use this period?
      - Can I filter subscription usage by date range and metric?
      instructions:
      - text: Get aggregate usage for subscription {subscriptionUuid}.
        slots:
          subscriptionUuid: path.subscriptionUuid
      - text: Show subscription {subscriptionUuid} usage filtered by {filter} at {resolution} resolution.
        slots:
          subscriptionUuid: path.subscriptionUuid
          filter: query.filter
          resolution: query.resolution
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionUuid}/metrics/usage/data-by-application'].get
  update:
    x-apievangelist-phrasing:
      intent: Get subscription usage broken down by application
      effect: read
      questions:
      - Which application consumes the most of my subscription's traffic?
      - Can I compare usage across apps in a subscription?
      instructions:
      - text: Break down usage for subscription {subscriptionUuid} by application.
        slots:
          subscriptionUuid: path.subscriptionUuid
      - text: Show per-application usage in subscription {subscriptionUuid} with filter {filter}.
        slots:
          subscriptionUuid: path.subscriptionUuid
          filter: query.filter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionUuid}/metrics/usage/{usageMetric}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one usage metric for a subscription
      effect: read
      questions:
      - What is my subscription's total for just visits or just views?
      - Can I pull a single metric across the whole subscription?
      instructions:
      - text: Get the {usageMetric} metric for subscription {subscriptionUuid}.
        slots:
          usageMetric: path.usageMetric
          subscriptionUuid: path.subscriptionUuid
      - text: Show aggregate {usageMetric} for subscription {subscriptionUuid} filtered by {filter}.
        slots:
          usageMetric: path.usageMetric
          subscriptionUuid: path.subscriptionUuid
          filter: query.filter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionUuid}/metrics/usage/views-by-application'].get
  update:
    x-apievangelist-phrasing:
      intent: Get subscription page views per application
      effect: read
      questions:
      - How many page views does each application in my subscription get?
      - Can I see views only, split by app?
      instructions:
      - text: Show page views per application for subscription {subscriptionUuid}.
        slots:
          subscriptionUuid: path.subscriptionUuid
      - text: Get views by application in subscription {subscriptionUuid} at {resolution} resolution.
        slots:
          subscriptionUuid: path.subscriptionUuid
          resolution: query.resolution
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionUuid}/metrics/usage/visits-by-application'].get
  update:
    x-apievangelist-phrasing:
      intent: Get subscription visits per application
      effect: read
      questions:
      - How many visits does each app in my subscription receive?
      - Can I see visits only, split by application?
      instructions:
      - text: Show visits per application for subscription {subscriptionUuid}.
        slots:
          subscriptionUuid: path.subscriptionUuid
      - text: Get visits by application in subscription {subscriptionUuid} at {resolution} resolution.
        slots:
          subscriptionUuid: path.subscriptionUuid
          resolution: query.resolution
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionUuid}/shield-acl'].get
  update:
    x-apievangelist-phrasing:
      intent: List Shield ACL rules
      effect: read
      questions:
      - What Shield access control rules are set on my subscription?
      - Which IP addresses are allowed by Shield right now?
      instructions:
      - text: List the Shield ACL rules for subscription {subscriptionUuid}.
        slots:
          subscriptionUuid: path.subscriptionUuid
      - text: Show {limit} Shield ACL rules on subscription {subscriptionUuid}.
        slots:
          limit: query.limit
          subscriptionUuid: path.subscriptionUuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionUuid}/shield-acl'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a Shield ACL rule
      effect: write
      questions:
      - How do I allow a new set of IP addresses through Shield?
      - Can I add a described Shield access rule to my subscription?
      instructions:
      - text: Create a Shield ACL rule on subscription {subscriptionUuid} allowing {addresses}.
        slots:
          subscriptionUuid: path.subscriptionUuid
          addresses: requestBody.addresses
      - text: Add Shield rule "{description}" for addresses {addresses} to subscription {subscriptionUuid}.
        slots:
          description: requestBody.description
          addresses: requestBody.addresses
          subscriptionUuid: path.subscriptionUuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionUuid}/shield-acl/{shieldAclUuid}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one Shield ACL rule
      effect: read
      questions:
      - Which addresses does a particular Shield rule cover?
      - Can I inspect a single Shield access control rule?
      instructions:
      - text: Show Shield ACL rule {shieldAclUuid} on subscription {subscriptionUuid}.
        slots:
          shieldAclUuid: path.shieldAclUuid
          subscriptionUuid: path.subscriptionUuid
      - text: Get the details of Shield rule {shieldAclUuid} in subscription {subscriptionUuid}.
        slots:
          shieldAclUuid: path.shieldAclUuid
          subscriptionUuid: path.subscriptionUuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionUuid}/shield-acl/{shieldAclUuid}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a Shield ACL rule
      effect: write
      questions:
      - Can I change the IP addresses on an existing Shield rule?
      - How do I edit the description of a Shield access rule?
      instructions:
      - text: Update Shield rule {shieldAclUuid} on subscription {subscriptionUuid} to allow {addresses}.
        slots:
          shieldAclUuid: path.shieldAclUuid
          subscriptionUuid: path.subscriptionUuid
          addresses: requestBody.addresses
      - text: Change the description of Shield rule {shieldAclUuid} in subscription {subscriptionUuid} to {description}.
        slots:
          shieldAclUuid: path.shieldAclUuid
          subscriptionUuid: path.subscriptionUuid
          description: requestBody.description
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionUuid}/shield-acl/{shieldAclUuid}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a Shield ACL rule
      effect: destructive
      questions:
      - Can I remove a single Shield rule without resetting all of them?
      - How do I delete an outdated Shield access rule?
      instructions:
      - text: Delete Shield rule {shieldAclUuid} from subscription {subscriptionUuid}.
        slots:
          shieldAclUuid: path.shieldAclUuid
          subscriptionUuid: path.subscriptionUuid
      - text: Remove Shield ACL entry {shieldAclUuid} on subscription {subscriptionUuid}.
        slots:
          shieldAclUuid: path.shieldAclUuid
          subscriptionUuid: path.subscriptionUuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionUuid}/shield-acl/actions/reset'].post
  update:
    x-apievangelist-phrasing:
      intent: Reset Shield ACL rules to defaults
      effect: destructive
      questions:
      - How do I wipe all custom Shield rules and go back to the defaults?
      - Is resetting Shield ACL rules reversible?
      instructions:
      - text: Reset all Shield ACL rules on subscription {subscriptionUuid} to defaults.
        slots:
          subscriptionUuid: path.subscriptionUuid
      - text: Clear every custom Shield rule from subscription {subscriptionUuid}.
        slots:
          subscriptionUuid: path.subscriptionUuid
      method: generated
      generated: '2026-09-26'