API Evangelist conversational phrasing for Things Stack — Gateway Server Gateway Registry API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Things Stack — Gateway Server Gateway Registry API
  version: 1.0.0
extends: openapi/the-things-network-gatewayregistry-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: 11
- target: $.paths['/gateways'].get
  update:
    x-apievangelist-phrasing:
      intent: List gateways I can access
      effect: read
      questions:
      - Which gateways do I have access to on The Things Stack?
      - Can I include recently deleted gateways when listing?
      - What gateways is a given user a direct collaborator on?
      instructions:
      - text: List all gateways I have access to.
      - text: List gateways where user {user_id} is a direct collaborator.
        slots:
          user_id: query.collaborator.user_ids.user_id
      - text: List deleted gateways too, with deleted set to {deleted}.
        slots:
          deleted: query.deleted
      method: generated
      generated: '2026-09-26'
- target: $.paths['/gateways/filter'].post
  update:
    x-apievangelist-phrasing:
      intent: List gateways with filters
      effect: read
      questions:
      - Can I list gateways using filter criteria in a request body?
      - Is there a way to apply structured filters when listing gateways?
      instructions:
      - text: Filter my gateways using {filters}.
        slots:
          filters: requestBody.filters
      - text: List gateways matching filters {filters}, limited to {limit}.
        slots:
          filters: requestBody.filters
          limit: requestBody.limit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/gateways/{gateway.ids.gateway_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a gateway's settings
      effect: write
      questions:
      - How do I change a gateway's name, frequency plan or other settings?
      - Can I update only certain fields of a gateway using a field mask?
      instructions:
      - text: Update gateway {gateway_id} with {gateway}.
        slots:
          gateway_id: path.gateway.ids.gateway_id
          gateway: requestBody.gateway
      - text: Change fields {field_mask} on gateway {gateway_id}.
        slots:
          field_mask: requestBody.field_mask
          gateway_id: path.gateway.ids.gateway_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/gateways/{gateway_ids.gateway_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a gateway
      effect: read
      questions:
      - What are the details of one of my gateways?
      - Can I pick which fields of a gateway come back?
      instructions:
      - text: Show gateway {gateway_id}.
        slots:
          gateway_id: path.gateway_ids.gateway_id
      - text: Get fields {field_mask} for gateway {gateway_id}.
        slots:
          field_mask: query.field_mask
          gateway_id: path.gateway_ids.gateway_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/gateways/{gateway_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a gateway (restorable)
      effect: destructive
      questions:
      - What happens to the gateway EUI when I delete a gateway?
      - Can a deleted gateway be restored later?
      instructions:
      - text: Delete gateway {gateway_id}.
        slots:
          gateway_id: path.gateway_id
      - text: Soft-delete gateway {gateway_id} and release its EUI.
        slots:
          gateway_id: path.gateway_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/gateways/{gateway_id}/purge'].delete
  update:
    x-apievangelist-phrasing:
      intent: Permanently purge a gateway
      effect: destructive
      questions:
      - How do I permanently remove a gateway so both its ID and EUI can be reused?
      - Is purging a gateway different from deleting it?
      instructions:
      - text: Purge gateway {gateway_id} permanently.
        slots:
          gateway_id: path.gateway_id
      - text: Free up the ID of gateway {gateway_id} by purging it.
        slots:
          gateway_id: path.gateway_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/gateways/{gateway_id}/restore'].post
  update:
    x-apievangelist-phrasing:
      intent: Restore a recently deleted gateway
      effect: write
      questions:
      - Can I undo deleting a gateway?
      - Does restoring a deleted gateway bring back its EUI?
      instructions:
      - text: Restore deleted gateway {gateway_id}.
        slots:
          gateway_id: path.gateway_id
      - text: Undo the deletion of gateway {gateway_id}.
        slots:
          gateway_id: path.gateway_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/organizations/{collaborator.organization_ids.organization_id}/gateways'].get
  update:
    x-apievangelist-phrasing:
      intent: List an organization's gateways
      effect: read
      questions:
      - Which gateways does my organization collaborate on?
      - Can I list an organization's gateways including deleted ones?
      instructions:
      - text: List the gateways of organization {organization_id}.
        slots:
          organization_id: path.collaborator.organization_ids.organization_id
      - text: Show {limit} gateways per page for organization {organization_id}.
        slots:
          limit: query.limit
          organization_id: path.collaborator.organization_ids.organization_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/organizations/{collaborator.organization_ids.organization_id}/gateways'].post
  update:
    x-apievangelist-phrasing:
      intent: Register a gateway under an organization
      effect: write
      questions:
      - How do I register a new gateway owned by an organization?
      - Does the organization get full rights on a gateway it creates?
      instructions:
      - text: Create gateway {gateway} under organization {organization_id}.
        slots:
          gateway: requestBody.gateway
          organization_id: path.collaborator.organization_ids.organization_id
      - text: Register a new gateway owned by organization {organization_id}.
        slots:
          organization_id: path.collaborator.organization_ids.organization_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{collaborator.user_ids.user_id}/gateways'].get
  update:
    x-apievangelist-phrasing:
      intent: List a user's gateways
      effect: read
      questions:
      - Which gateways is a specific user a direct collaborator on?
      - Can I list gateways for a user by their user ID in the path?
      instructions:
      - text: List gateways belonging to user {user_id}.
        slots:
          user_id: path.collaborator.user_ids.user_id
      - text: Show gateways for user {user_id} sorted by {order}.
        slots:
          user_id: path.collaborator.user_ids.user_id
          order: query.order
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{collaborator.user_ids.user_id}/gateways'].post
  update:
    x-apievangelist-phrasing:
      intent: Register a gateway under a user
      effect: write
      questions:
      - How do I register a new gateway on my personal user account?
      - What rights does the user get on a gateway they create?
      instructions:
      - text: Create gateway {gateway} for user {user_id}.
        slots:
          gateway: requestBody.gateway
          user_id: path.collaborator.user_ids.user_id
      - text: Register a new gateway on user account {user_id}.
        slots:
          user_id: path.collaborator.user_ids.user_id
      method: generated
      generated: '2026-09-26'