# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Config API v1 Subscription API
  version: 1.0.0
extends: openapi/here-subscription-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: 8
- target: $.paths['/subscriptions'].get
  update:
    x-apievangelist-phrasing:
      intent: List an organization's subscriptions
      effect: read
      questions:
      - Which catalog subscriptions does my account have access to?
      - Can I page through subscriptions in smaller batches?
      instructions:
      - text: List all subscriptions my account can see.
      - text: List subscriptions, {limit} per page, starting at page token {pageToken}.
        slots:
          limit: query.limit
          pageToken: query.pageToken
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a catalog-to-catalog subscription
      effect: write
      questions:
      - How do I subscribe a target catalog layer to a source layer?
      - Can I safely retry a subscription request without creating duplicates?
      instructions:
      - text: Create a subscription from the source layer to the target layer with idempotency key {idempotencyKey}.
        slots:
          idempotencyKey: header.x-idempotency-key
      - text: Subscribe my target catalog to a source catalog, using retry key {idempotencyKey}.
        slots:
          idempotencyKey: header.x-idempotency-key
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionHrn}'].get
  update:
    x-apievangelist-phrasing:
      intent: View a subscription's configuration
      effect: read
      questions:
      - What source and target does a particular subscription connect?
      - Can I look up a subscription's configuration by its HRN?
      instructions:
      - text: Show the configuration of subscription {subscriptionHrn}.
        slots:
          subscriptionHrn: path.subscriptionHrn
      - text: Get the details of subscription {subscriptionHrn}.
        slots:
          subscriptionHrn: path.subscriptionHrn
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionHrn}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a subscription
      effect: destructive
      questions:
      - How do I stop and remove a catalog subscription?
      - Does deleting a subscription require an idempotency key?
      instructions:
      - text: Delete subscription {subscriptionHrn} with idempotency key {idempotency_key}.
        slots:
          subscriptionHrn: path.subscriptionHrn
          idempotency_key: header.x-idempotency-key
      - text: Remove the catalog subscription {subscriptionHrn}, key {idempotency_key}.
        slots:
          subscriptionHrn: path.subscriptionHrn
          idempotency_key: header.x-idempotency-key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionHrn}'].head
  update:
    x-apievangelist-phrasing:
      intent: Check that a subscription exists
      effect: read
      questions:
      - Is there a quick existence check for a subscription HRN?
      - Can I confirm a subscription still exists without fetching its configuration?
      instructions:
      - text: Check whether subscription {subscriptionHrn} exists.
        slots:
          subscriptionHrn: path.subscriptionHrn
      - text: Confirm subscription {subscriptionHrn} is still there.
        slots:
          subscriptionHrn: path.subscriptionHrn
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/status/{statusToken}'].get
  update:
    x-apievangelist-phrasing:
      intent: Track a subscription create or delete
      effect: read
      questions:
      - How do I know when my subscription creation or deletion has finished?
      - What do I do with the status token returned when creating a subscription?
      instructions:
      - text: Check the progress of subscription request {statusToken}.
        slots:
          statusToken: path.statusToken
      - text: Tell me whether the subscription create or delete behind token {statusToken} is done.
        slots:
          statusToken: path.statusToken
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/batch'].post
  update:
    x-apievangelist-phrasing:
      intent: Create many subscriptions at once
      effect: write
      questions:
      - Can I create several catalog subscriptions in a single request?
      - How do I subscribe multiple target layers to their sources in bulk?
      instructions:
      - text: 'Create these subscriptions in one batch: {items}.'
        slots:
          items: requestBody.items
      - text: Bulk-subscribe the source and target layer pairs {items}.
        slots:
          items: requestBody.items
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/batch/status/{statusToken}'].get
  update:
    x-apievangelist-phrasing:
      intent: Track a batch subscription creation
      effect: read
      questions:
      - Has my batch of subscriptions finished being created?
      - Where do I check the result of a bulk subscription request?
      instructions:
      - text: Get the status of batch subscription job {statusToken}.
        slots:
          statusToken: path.statusToken
      - text: Check whether bulk subscription request {statusToken} completed.
        slots:
          statusToken: path.statusToken
      method: generated
      generated: '2026-09-26'