# 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 — Packet Broker Agent Pba API
  version: 1.0.0
extends: openapi/the-things-network-pba-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: 24
- target: $.paths['/pba/forwarders/policies'].get
  update:
    x-apievangelist-phrasing:
      intent: List routing policies forwarders set toward my network
      effect: read
      questions:
      - Which forwarders on Packet Broker have configured routing policies toward my network as Home Network?
      - Can I see the policies that other networks' forwarders apply to traffic they send to us?
      - Is there a way to filter inbound forwarder policies by a specific home NetID and tenant?
      instructions:
      - text: List the routing policies forwarders have configured for my network as Home Network.
      - text: Show forwarder routing policies aimed at home NetID {net_id}, page {page}.
        slots:
          net_id: query.home_network_id.net_id
          page: query.page
      - text: List up to {limit} forwarder policies targeting tenant {tenant_id} of NetID {net_id}.
        slots:
          limit: query.limit
          tenant_id: query.home_network_id.tenant_id
          net_id: query.home_network_id.net_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/pba/home-networks'].get
  update:
    x-apievangelist-phrasing:
      intent: List home networks available for routing policies
      effect: read
      questions:
      - What home networks are listed on Packet Broker that I can configure routing policies for?
      - Can I find a listed home network by part of its name?
      - Which home networks have a tenant ID containing a given string?
      instructions:
      - text: List the home networks I can set routing policies for.
      - text: Find listed home networks whose name contains {name}.
        slots:
          name: query.name_contains
      - text: List home networks with a tenant ID containing {tenant}, {limit} per page.
        slots:
          tenant: query.tenant_id_contains
          limit: query.limit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/pba/home-networks/gateway-visibilities/default'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the default gateway visibility
      effect: read
      questions:
      - What gateway information do we share with home networks by default through Packet Broker?
      - How can I check the current default gateway visibility setting?
      instructions:
      - text: Show the default gateway visibility for Packet Broker home networks.
      - text: Get the gateway visibility that applies to home networks by default.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/pba/home-networks/gateway-visibilities/default'].put
  update:
    x-apievangelist-phrasing:
      intent: Set the default gateway visibility (PUT)
      effect: write
      questions:
      - How do I change which gateway details home networks see by default, using PUT?
      - Can I replace the default gateway visibility with a PUT request?
      instructions:
      - text: Set the default gateway visibility to {visibility} using PUT.
        slots:
          visibility: requestBody.visibility
      - text: PUT a new default gateway visibility of {visibility} for all home networks.
        slots:
          visibility: requestBody.visibility
      method: generated
      generated: '2026-09-26'
- target: $.paths['/pba/home-networks/gateway-visibilities/default'].post
  update:
    x-apievangelist-phrasing:
      intent: Set the default gateway visibility (POST)
      effect: write
      questions:
      - Is there a POST variant for setting the default gateway visibility?
      - Can I post a default gateway visibility instead of using PUT?
      instructions:
      - text: POST the default gateway visibility {visibility} to Packet Broker Agent.
        slots:
          visibility: requestBody.visibility
      - text: Use the POST endpoint to set default gateway visibility to {visibility}.
        slots:
          visibility: requestBody.visibility
      method: generated
      generated: '2026-09-26'
- target: $.paths['/pba/home-networks/gateway-visibilities/default'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove the default gateway visibility
      effect: destructive
      questions:
      - How do I clear the default gateway visibility so no default is set?
      - Can I delete the default gateway visibility setting entirely?
      instructions:
      - text: Delete the default gateway visibility.
      - text: Remove the default gateway visibility setting from Packet Broker Agent.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/pba/home-networks/policies'].get
  update:
    x-apievangelist-phrasing:
      intent: List my routing policies toward home networks
      effect: read
      questions:
      - Which routing policies has our Packet Broker Agent, as Forwarder, set for home networks?
      - Can I page through the per-home-network policies we configured as a forwarder?
      instructions:
      - text: List the routing policies we configured as Forwarder for home networks.
      - text: Show page {page} of our forwarder routing policies, {limit} at a time.
        slots:
          page: query.page
          limit: query.limit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/pba/home-networks/policies/default'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the default routing policy
      effect: read
      questions:
      - What uplink and downlink routing applies by default to home networks without their own policy?
      - How can I see the default Packet Broker routing policy?
      instructions:
      - text: Show the default routing policy for home networks.
      - text: Get the default Packet Broker routing policy.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/pba/home-networks/policies/default'].put
  update:
    x-apievangelist-phrasing:
      intent: Set the default routing policy (PUT)
      effect: write
      questions:
      - How do I set the default uplink and downlink routing policy with PUT?
      - Can I replace the default routing policy's downlink rules via a PUT request?
      instructions:
      - text: PUT a default routing policy with uplink {uplink} and downlink {downlink}.
        slots:
          uplink: requestBody.uplink
          downlink: requestBody.downlink
      - text: Update the default routing policy uplink settings to {uplink} using PUT.
        slots:
          uplink: requestBody.uplink
      method: generated
      generated: '2026-09-26'
- target: $.paths['/pba/home-networks/policies/default'].post
  update:
    x-apievangelist-phrasing:
      intent: Set the default routing policy (POST)
      effect: write
      questions:
      - Is there a POST endpoint for setting the default routing policy?
      - Can I post new default uplink and downlink routing rules?
      instructions:
      - text: POST a default routing policy with uplink {uplink} and downlink {downlink}.
        slots:
          uplink: requestBody.uplink
          downlink: requestBody.downlink
      - text: Use POST to set the default routing policy downlink to {downlink}.
        slots:
          downlink: requestBody.downlink
      method: generated
      generated: '2026-09-26'
- target: $.paths['/pba/home-networks/policies/default'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete the default routing policy
      effect: destructive
      questions:
      - How do I remove the default routing policy so home networks have no default?
      - What happens if I delete the default Packet Broker routing policy?
      instructions:
      - text: Delete the default routing policy.
      - text: Remove the default Packet Broker routing policy for home networks.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/pba/home-networks/policies/{home_network_id.net_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Set a home network's routing policy (PUT)
      effect: write
      questions:
      - How do I set a routing policy for one specific home network by its NetID using PUT?
      - Can I give a single NetID its own uplink routing rules instead of the default?
      instructions:
      - text: PUT a routing policy for home NetID {net_id} with uplink {uplink}.
        slots:
          net_id: path.home_network_id.net_id
          uplink: requestBody.uplink
      - text: Set the downlink policy for home network {net_id} to {downlink} via PUT.
        slots:
          net_id: path.home_network_id.net_id
          downlink: requestBody.downlink
      method: generated
      generated: '2026-09-26'
- target: $.paths['/pba/home-networks/policies/{home_network_id.net_id}'].post
  update:
    x-apievangelist-phrasing:
      intent: Set a home network's routing policy (POST)
      effect: write
      questions:
      - Is there a POST variant for setting a NetID-specific routing policy?
      - Can I post routing rules for a home network identified only by NetID?
      instructions:
      - text: POST a routing policy for home NetID {net_id} with uplink {uplink} and downlink {downlink}.
        slots:
          net_id: path.home_network_id.net_id
          uplink: requestBody.uplink
          downlink: requestBody.downlink
      - text: Use POST to set home network {net_id}'s uplink rules to {uplink}.
        slots:
          net_id: path.home_network_id.net_id
          uplink: requestBody.uplink
      method: generated
      generated: '2026-09-26'
- target: $.paths['/pba/home-networks/policies/{home_network_id.net_id}/{home_network_id.tenant_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Set a tenant home network's routing policy (PUT)
      effect: write
      questions:
      - How do I set a routing policy for a specific tenant inside a NetID using PUT?
      - Can routing policies target a tenant that leases DevAddr blocks from a NetID?
      instructions:
      - text: PUT a routing policy for tenant {tenant_id} of NetID {net_id} with uplink {uplink}.
        slots:
          tenant_id: path.home_network_id.tenant_id
          net_id: path.home_network_id.net_id
          uplink: requestBody.uplink
      - text: Set the downlink rules for tenant {tenant_id} on NetID {net_id} to {downlink} via PUT.
        slots:
          tenant_id: path.home_network_id.tenant_id
          net_id: path.home_network_id.net_id
          downlink: requestBody.downlink
      method: generated
      generated: '2026-09-26'
- target: $.paths['/pba/home-networks/policies/{home_network_id.net_id}/{home_network_id.tenant_id}'].post
  update:
    x-apievangelist-phrasing:
      intent: Set a tenant home network's routing policy (POST)
      effect: write
      questions:
      - Is there a POST endpoint for a NetID-plus-tenant routing policy?
      - Can I post uplink and downlink routing for one tenant of a home NetID?
      instructions:
      - text: POST a routing policy for NetID {net_id} tenant {tenant_id} with downlink {downlink}.
        slots:
          net_id: path.home_network_id.net_id
          tenant_id: path.home_network_id.tenant_id
          downlink: requestBody.downlink
      - text: Use POST to set uplink {uplink} for tenant {tenant_id} of home NetID {net_id}.
        slots:
          uplink: requestBody.uplink
          tenant_id: path.home_network_id.tenant_id
          net_id: path.home_network_id.net_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/pba/home-networks/policies/{net_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a home network's routing policy by NetID
      effect: read
      questions:
      - What routing policy do we apply to a given home NetID?
      - Can I look up a home network's policy by NetID and optionally filter by tenant as a query parameter?
      instructions:
      - text: Show the routing policy for home NetID {net_id}.
        slots:
          net_id: path.net_id
      - text: Get the routing policy for NetID {net_id} with tenant {tenant_id} passed as a query filter.
        slots:
          net_id: path.net_id
          tenant_id: query.tenant_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/pba/home-networks/policies/{net_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a home network's routing policy by NetID
      effect: destructive
      questions:
      - How do I remove the custom routing policy for a home NetID so it falls back to the default?
      - Can I delete a NetID's routing policy while passing the tenant as a query parameter?
      instructions:
      - text: Delete the routing policy for home NetID {net_id}.
        slots:
          net_id: path.net_id
      - text: Remove the routing policy for NetID {net_id}, tenant {tenant_id} given as a query value.
        slots:
          net_id: path.net_id
          tenant_id: query.tenant_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/pba/home-networks/policies/{net_id}/{tenant_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a tenant home network's routing policy
      effect: read
      questions:
      - Which routing policy applies to a specific tenant within a home NetID, addressed in the path?
      - How do I read the policy for a NetID and tenant pair?
      instructions:
      - text: Show the routing policy for NetID {net_id} and tenant {tenant_id} using the tenant path.
        slots:
          net_id: path.net_id
          tenant_id: path.tenant_id
      - text: Get the policy we apply to tenant {tenant_id} under home NetID {net_id}.
        slots:
          tenant_id: path.tenant_id
          net_id: path.net_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/pba/home-networks/policies/{net_id}/{tenant_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a tenant home network's routing policy
      effect: destructive
      questions:
      - How do I delete the routing policy for one tenant of a home NetID via the tenant path?
      - Can I remove a tenant-specific policy without touching the rest of the NetID?
      instructions:
      - text: Delete the routing policy for tenant {tenant_id} of NetID {net_id} using the tenant path.
        slots:
          tenant_id: path.tenant_id
          net_id: path.net_id
      - text: Remove the NetID {net_id} tenant {tenant_id} routing policy.
        slots:
          net_id: path.net_id
          tenant_id: path.tenant_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/pba/info'].get
  update:
    x-apievangelist-phrasing:
      intent: Get Packet Broker registration info
      effect: read
      questions:
      - What does our Packet Broker registration look like right now?
      - Is our network registered with Packet Broker, and with what settings?
      instructions:
      - text: Show our Packet Broker registration information.
      - text: Get the Packet Broker Agent registration details.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/pba/networks'].get
  update:
    x-apievangelist-phrasing:
      intent: List networks listed on Packet Broker
      effect: read
      questions:
      - Which networks are listed on Packet Broker?
      - Can I list only networks that have a routing policy configured?
      - How can I search listed networks by name or tenant ID?
      instructions:
      - text: List all networks listed on Packet Broker.
      - text: List listed networks where routing policy presence is {with_routing_policy}.
        slots:
          with_routing_policy: query.with_routing_policy
      - text: Search all Packet Broker networks, not just home networks, for names containing {name}.
        slots:
          name: query.name_contains
      method: generated
      generated: '2026-09-26'
- target: $.paths['/pba/registration'].put
  update:
    x-apievangelist-phrasing:
      intent: Register with Packet Broker (PUT)
      effect: write
      questions:
      - How do I register or update our network's Packet Broker registration using PUT?
      - Can I choose whether our network is listed publicly when registering?
      instructions:
      - text: Register with Packet Broker via PUT and set listed to {listed}.
        slots:
          listed: requestBody.listed
      - text: Create or update our Packet Broker registration using PUT.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/pba/registration'].post
  update:
    x-apievangelist-phrasing:
      intent: Register with Packet Broker (POST)
      effect: write
      questions:
      - Is there a POST endpoint for registering our network with Packet Broker?
      - Can I post a registration that makes our network unlisted?
      instructions:
      - text: POST a Packet Broker registration with listed set to {listed}.
        slots:
          listed: requestBody.listed
      - text: Use the POST registration endpoint to register with Packet Broker.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/pba/registration'].delete
  update:
    x-apievangelist-phrasing:
      intent: Deregister from Packet Broker
      effect: destructive
      questions:
      - How do I remove our tenant's registration from Packet Broker?
      - Who is allowed to deregister from Packet Broker?
      instructions:
      - text: Deregister our network from Packet Broker.
      - text: Delete our Packet Broker registration.
      method: generated
      generated: '2026-09-26'