The Things Network / The Things Stack · OpenAPI Overlay 1.0.0

API Evangelist conversational phrasing for Things Stack — End Device Registry Device Repository API

21 actions 21 updates phrasing extends openapi/the-things-network-devicerepository-api-openapi.yml
Generated by API Evangelist Written by API Evangelist tooling for The Things Network / The Things Stack's API. It is a proposal applied on top of the contract, not a document The Things Network / The Things Stack publishes.
View Overlay File View on GitHub Overlay Specification

What the actions change

x-apievangelist-phrasing

Targets 21 · first 16 shown; the file carries all of them

$.info
$.paths['/dr/applications/{application_ids.application_id}/brands'].get
$.paths['/dr/applications/{application_ids.application_id}/brands/{brand_id}'].get
$.paths['/dr/applications/{application_ids.application_id}/brands/{brand_id}/models'].get
$.paths['/dr/applications/{application_ids.application_id}/brands/{brand_id}/models/{model_id}'].get
$.paths['/dr/applications/{application_ids.application_id}/brands/{version_ids.brand_id}/models/{version_ids.model_id}/{version_ids.firmware_version}/{version_ids.band_id}/formatters/downlink/decoder'].get
$.paths['/dr/applications/{application_ids.application_id}/brands/{version_ids.brand_id}/models/{version_ids.model_id}/{version_ids.firmware_version}/{version_ids.band_id}/formatters/downlink/encoder'].get
$.paths['/dr/applications/{application_ids.application_id}/brands/{version_ids.brand_id}/models/{version_ids.model_id}/{version_ids.firmware_version}/{version_ids.band_id}/formatters/uplink/decoder'].get
$.paths['/dr/applications/{application_ids.application_id}/brands/{version_ids.brand_id}/models/{version_ids.model_id}/{version_ids.firmware_version}/{version_ids.band_id}/template'].get
$.paths['/dr/applications/{application_ids.application_id}/models'].get
$.paths['/dr/applications/{application_ids.application_id}/vendors/{end_device_profile_ids.vendor_id}/profiles/{end_device_profile_ids.vendor_profile_id}/template'].get
$.paths['/dr/brands'].get
$.paths['/dr/brands/{brand_id}'].get
$.paths['/dr/brands/{brand_id}/models'].get
$.paths['/dr/brands/{brand_id}/models/{model_id}'].get
$.paths['/dr/brands/{version_ids.brand_id}/models/{version_ids.model_id}/{version_ids.firmware_version}/{version_ids.band_id}/formatters/downlink/decoder'].get

OpenAPI Overlay

Raw ↑ 
# 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 — End Device Registry Device Repository API
  version: 1.0.0
extends: openapi/the-things-network-devicerepository-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: 20
- target: $.paths['/dr/applications/{application_ids.application_id}/brands'].get
  update:
    x-apievangelist-phrasing:
      intent: List device brands as seen by an application
      effect: read
      questions:
      - Which device manufacturers can I pick from when adding devices to my Things Stack application?
      - Can I search the brand list by name within one application's view of the Device Repository?
      instructions:
      - text: List the device brands available to application {application_id}.
        slots:
          application_id: path.application_ids.application_id
      - text: Search brands matching {search} for application {application_id}.
        slots:
          search: query.search
          application_id: path.application_ids.application_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/dr/applications/{application_ids.application_id}/brands/{brand_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a device brand in an application context
      effect: read
      questions:
      - What details does the repository hold about one brand when I look it up through my application?
      - Can I fetch a single manufacturer's profile scoped to a specific application?
      instructions:
      - text: Show brand {brand_id} as seen from application {application_id}.
        slots:
          brand_id: path.brand_id
          application_id: path.application_ids.application_id
      - text: Fetch only {field_mask} for brand {brand_id} via application {application_id}.
        slots:
          field_mask: query.field_mask
          brand_id: path.brand_id
          application_id: path.application_ids.application_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/dr/applications/{application_ids.application_id}/brands/{brand_id}/models'].get
  update:
    x-apievangelist-phrasing:
      intent: List a brand's models for an application
      effect: read
      questions:
      - Which device models does one manufacturer offer, as listed for my application?
      - Can I page through a single brand's models from inside an application context?
      instructions:
      - text: List the models of brand {brand_id} for application {application_id}.
        slots:
          brand_id: path.brand_id
          application_id: path.application_ids.application_id
      - text: Search brand {brand_id}'s models for {search} in application {application_id}.
        slots:
          brand_id: path.brand_id
          search: query.search
          application_id: path.application_ids.application_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/dr/applications/{application_ids.application_id}/brands/{brand_id}/models/{model_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a device model in an application context
      effect: read
      questions:
      - What does the Device Repository say about one specific model when accessed through my application?
      - Can I read a model's spec sheet scoped to an application ID?
      instructions:
      - text: Show model {model_id} of brand {brand_id} for application {application_id}.
        slots:
          model_id: path.model_id
          brand_id: path.brand_id
          application_id: path.application_ids.application_id
      - text: Get the {field_mask} fields of model {model_id} by {brand_id}, scoped to application {application_id}.
        slots:
          field_mask: query.field_mask
          model_id: path.model_id
          brand_id: path.brand_id
          application_id: path.application_ids.application_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/dr/applications/{application_ids.application_id}/brands/{version_ids.brand_id}/models/{version_ids.model_id}/{version_ids.firmware_version}/{version_ids.band_id}/formatters/downlink/decoder'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a model's downlink decoder for an application
      effect: read
      questions:
      - Where can I get the payload formatter that decodes downlinks for a device model in my application?
      - Is the downlink decoder tied to firmware version and band when fetched per application?
      instructions:
      - text: Get the downlink decoder for {brand_id} {model_id} firmware {firmware_version} band {band_id} in application {application_id}.
        slots:
          brand_id: path.version_ids.brand_id
          model_id: path.version_ids.model_id
          firmware_version: path.version_ids.firmware_version
          band_id: path.version_ids.band_id
          application_id: path.application_ids.application_id
      - text: For application {application_id}, get the downlink decoder of {brand_id} {model_id} hardware {hardware_version}, firmware {firmware_version}, band {band_id}.
        slots:
          application_id: path.application_ids.application_id
          brand_id: path.version_ids.brand_id
          model_id: path.version_ids.model_id
          hardware_version: query.version_ids.hardware_version
          firmware_version: path.version_ids.firmware_version
          band_id: path.version_ids.band_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/dr/applications/{application_ids.application_id}/brands/{version_ids.brand_id}/models/{version_ids.model_id}/{version_ids.firmware_version}/{version_ids.band_id}/formatters/downlink/encoder'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a model's downlink encoder for an application
      effect: read
      questions:
      - How can my application get the formatter that encodes downlink messages for a given device model?
      - Does the downlink encoder differ by hardware version when looked up for an application?
      instructions:
      - text: Get the downlink encoder for {brand_id} {model_id} firmware {firmware_version} band {band_id} in application {application_id}.
        slots:
          brand_id: path.version_ids.brand_id
          model_id: path.version_ids.model_id
          firmware_version: path.version_ids.firmware_version
          band_id: path.version_ids.band_id
          application_id: path.application_ids.application_id
      - text: For application {application_id}, get the downlink encoder of {brand_id} {model_id} hardware {hardware_version}, firmware {firmware_version}, band {band_id}.
        slots:
          application_id: path.application_ids.application_id
          brand_id: path.version_ids.brand_id
          model_id: path.version_ids.model_id
          hardware_version: query.version_ids.hardware_version
          firmware_version: path.version_ids.firmware_version
          band_id: path.version_ids.band_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/dr/applications/{application_ids.application_id}/brands/{version_ids.brand_id}/models/{version_ids.model_id}/{version_ids.firmware_version}/{version_ids.band_id}/formatters/uplink/decoder'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a model's uplink decoder for an application
      effect: read
      questions:
      - Can my application pull the ready-made uplink payload decoder for the sensor model I use?
      - Which uplink decoder applies to a model's specific firmware and band within my application?
      instructions:
      - text: Get the uplink decoder for {brand_id} {model_id} firmware {firmware_version} band {band_id} in application {application_id}.
        slots:
          brand_id: path.version_ids.brand_id
          model_id: path.version_ids.model_id
          firmware_version: path.version_ids.firmware_version
          band_id: path.version_ids.band_id
          application_id: path.application_ids.application_id
      - text: For application {application_id}, get the uplink decoder of {brand_id} {model_id} hardware {hardware_version}, firmware {firmware_version}, band {band_id}.
        slots:
          application_id: path.application_ids.application_id
          brand_id: path.version_ids.brand_id
          model_id: path.version_ids.model_id
          hardware_version: query.version_ids.hardware_version
          firmware_version: path.version_ids.firmware_version
          band_id: path.version_ids.band_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/dr/applications/{application_ids.application_id}/brands/{version_ids.brand_id}/models/{version_ids.model_id}/{version_ids.firmware_version}/{version_ids.band_id}/template'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an end device template by model for an application
      effect: read
      questions:
      - Can I get a pre-filled end device template for a model and firmware to onboard into my application?
      - What registration template does the repository give my application for a given band and firmware?
      instructions:
      - text: Get the end device template for {brand_id} {model_id} firmware {firmware_version} band {band_id} in application {application_id}.
        slots:
          brand_id: path.version_ids.brand_id
          model_id: path.version_ids.model_id
          firmware_version: path.version_ids.firmware_version
          band_id: path.version_ids.band_id
          application_id: path.application_ids.application_id
      - text: Build an onboarding template in application {application_id} for {brand_id} {model_id} hardware {hardware_version}, firmware {firmware_version}, band {band_id}.
        slots:
          application_id: path.application_ids.application_id
          brand_id: path.version_ids.brand_id
          model_id: path.version_ids.model_id
          hardware_version: query.version_ids.hardware_version
          firmware_version: path.version_ids.firmware_version
          band_id: path.version_ids.band_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/dr/applications/{application_ids.application_id}/models'].get
  update:
    x-apievangelist-phrasing:
      intent: List all device models for an application
      effect: read
      questions:
      - Which device models across every brand can I browse for my application?
      - Can I filter the application-scoped model catalog by brand or a search term?
      instructions:
      - text: List every device model available to application {application_id}.
        slots:
          application_id: path.application_ids.application_id
      - text: Search all models for {search} in application {application_id}.
        slots:
          search: query.search
          application_id: path.application_ids.application_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/dr/applications/{application_ids.application_id}/vendors/{end_device_profile_ids.vendor_id}/profiles/{end_device_profile_ids.vendor_profile_id}/template'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a template by vendor profile for an application
      effect: read
      questions:
      - Can my application get an end device template from a vendor ID and vendor profile ID instead of a model?
      - How do I turn a LoRaWAN vendor profile into a device template inside one application?
      instructions:
      - text: Get the template for vendor {vendor_id} profile {vendor_profile_id} in application {application_id}.
        slots:
          vendor_id: path.end_device_profile_ids.vendor_id
          vendor_profile_id: path.end_device_profile_ids.vendor_profile_id
          application_id: path.application_ids.application_id
      - text: Resolve LoRaWAN vendor profile {vendor_profile_id} from vendor {vendor_id} into a band {band_id} template for app {application_id}.
        slots:
          application_id: path.application_ids.application_id
          vendor_id: path.end_device_profile_ids.vendor_id
          vendor_profile_id: path.end_device_profile_ids.vendor_profile_id
          band_id: query.version_ids.band_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/dr/brands'].get
  update:
    x-apievangelist-phrasing:
      intent: List brands in the global Device Repository
      effect: read
      questions:
      - What LoRaWAN device manufacturers are in The Things Stack Device Repository?
      - Can I sort or search the full brand catalog without naming an application?
      instructions:
      - text: List all brands in the Device Repository.
      - text: Search the global brand catalog for {search}.
        slots:
          search: query.search
      method: generated
      generated: '2026-09-26'
- target: $.paths['/dr/brands/{brand_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a brand from the global repository
      effect: read
      questions:
      - Where do I look up one manufacturer's profile in the shared device catalog?
      - What information is stored for a brand without an application context?
      instructions:
      - text: Look up brand {brand_id} in the global Device Repository.
        slots:
          brand_id: path.brand_id
      - text: Get just the {field_mask} of catalog brand {brand_id}.
        slots:
          field_mask: query.field_mask
          brand_id: path.brand_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/dr/brands/{brand_id}/models'].get
  update:
    x-apievangelist-phrasing:
      intent: List a brand's models in the global repository
      effect: read
      questions:
      - Which models does a given manufacturer have in the global repository?
      - Can I search one brand's model list by keyword outside any application?
      instructions:
      - text: List the global catalog's models for brand {brand_id}.
        slots:
          brand_id: path.brand_id
      - text: Find models of brand {brand_id} matching {search} in the global catalog.
        slots:
          brand_id: path.brand_id
          search: query.search
      method: generated
      generated: '2026-09-26'
- target: $.paths['/dr/brands/{brand_id}/models/{model_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a device model from the global repository
      effect: read
      questions:
      - What specs does the global Device Repository list for a particular device model?
      - Can I read one model's details straight from the shared catalog?
      instructions:
      - text: Look up model {model_id} from brand {brand_id} in the global repository.
        slots:
          model_id: path.model_id
          brand_id: path.brand_id
      - text: Get only {field_mask} for catalog model {model_id} of brand {brand_id}.
        slots:
          field_mask: query.field_mask
          model_id: path.model_id
          brand_id: path.brand_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/dr/brands/{version_ids.brand_id}/models/{version_ids.model_id}/{version_ids.firmware_version}/{version_ids.band_id}/formatters/downlink/decoder'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a model's downlink decoder from the global catalog
      effect: read
      questions:
      - Where is the downlink decoder for a device model published in the shared repository?
      - Can I download a model's downlink decoder without referencing an application?
      instructions:
      - text: Fetch the global downlink decoder for {brand_id} {model_id} firmware {firmware_version} on band {band_id}.
        slots:
          brand_id: path.version_ids.brand_id
          model_id: path.version_ids.model_id
          firmware_version: path.version_ids.firmware_version
          band_id: path.version_ids.band_id
      - text: Download the catalog downlink decoder for {brand_id} {model_id} hardware {hardware_version} firmware {firmware_version} band {band_id}.
        slots:
          brand_id: path.version_ids.brand_id
          model_id: path.version_ids.model_id
          hardware_version: query.version_ids.hardware_version
          firmware_version: path.version_ids.firmware_version
          band_id: path.version_ids.band_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/dr/brands/{version_ids.brand_id}/models/{version_ids.model_id}/{version_ids.firmware_version}/{version_ids.band_id}/formatters/downlink/encoder'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a model's downlink encoder from the global catalog
      effect: read
      questions:
      - Is there a shared downlink encoder script for my device model and firmware?
      - Can I get the downlink encoder for a hardware version from the global catalog?
      instructions:
      - text: Fetch the global downlink encoder for {brand_id} {model_id} firmware {firmware_version} on band {band_id}.
        slots:
          brand_id: path.version_ids.brand_id
          model_id: path.version_ids.model_id
          firmware_version: path.version_ids.firmware_version
          band_id: path.version_ids.band_id
      - text: Download the catalog downlink encoder for {brand_id} {model_id} hardware {hardware_version} firmware {firmware_version} band {band_id}.
        slots:
          brand_id: path.version_ids.brand_id
          model_id: path.version_ids.model_id
          hardware_version: query.version_ids.hardware_version
          firmware_version: path.version_ids.firmware_version
          band_id: path.version_ids.band_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/dr/brands/{version_ids.brand_id}/models/{version_ids.model_id}/{version_ids.firmware_version}/{version_ids.band_id}/formatters/uplink/decoder'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a model's uplink decoder from the global catalog
      effect: read
      questions:
      - How do I find the official uplink payload decoder for a device model?
      - Does the global repository publish uplink decoders per firmware version and frequency band?
      instructions:
      - text: Fetch the global uplink decoder for {brand_id} {model_id} firmware {firmware_version} on band {band_id}.
        slots:
          brand_id: path.version_ids.brand_id
          model_id: path.version_ids.model_id
          firmware_version: path.version_ids.firmware_version
          band_id: path.version_ids.band_id
      - text: Download the catalog uplink decoder for {brand_id} {model_id} hardware {hardware_version} firmware {firmware_version} band {band_id}.
        slots:
          brand_id: path.version_ids.brand_id
          model_id: path.version_ids.model_id
          hardware_version: query.version_ids.hardware_version
          firmware_version: path.version_ids.firmware_version
          band_id: path.version_ids.band_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/dr/brands/{version_ids.brand_id}/models/{version_ids.model_id}/{version_ids.firmware_version}/{version_ids.band_id}/template'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an end device template by model from the catalog
      effect: read
      questions:
      - Can I generate a device registration template from the global catalog for a model and firmware?
      - What end device template does the shared repository hold for a model on a given band?
      instructions:
      - text: Fetch the global end device template for {brand_id} {model_id} firmware {firmware_version} on band {band_id}.
        slots:
          brand_id: path.version_ids.brand_id
          model_id: path.version_ids.model_id
          firmware_version: path.version_ids.firmware_version
          band_id: path.version_ids.band_id
      - text: Download the catalog end device template for {brand_id} {model_id} hardware {hardware_version} firmware {firmware_version} band {band_id}.
        slots:
          brand_id: path.version_ids.brand_id
          model_id: path.version_ids.model_id
          hardware_version: query.version_ids.hardware_version
          firmware_version: path.version_ids.firmware_version
          band_id: path.version_ids.band_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/dr/models'].get
  update:
    x-apievangelist-phrasing:
      intent: List all models in the global Device Repository
      effect: read
      questions:
      - What device models across all manufacturers are in the global Device Repository?
      - Can I narrow the full model catalog to one brand with a query filter?
      instructions:
      - text: List every model in the global Device Repository.
      - text: List global catalog models filtered to brand {brand_id}.
        slots:
          brand_id: query.brand_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/dr/vendors/{end_device_profile_ids.vendor_id}/profiles/{end_device_profile_ids.vendor_profile_id}/template'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a template by vendor profile from the catalog
      effect: read
      questions:
      - Can I resolve a LoRaWAN vendor ID and vendor profile ID to a device template in the global repository?
      - What template does the shared catalog return for a vendor profile?
      instructions:
      - text: Fetch the global template for vendor {vendor_id} profile {vendor_profile_id}.
        slots:
          vendor_id: path.end_device_profile_ids.vendor_id
          vendor_profile_id: path.end_device_profile_ids.vendor_profile_id
      - text: Get the catalog template for vendor {vendor_id} profile {vendor_profile_id} on band {band_id}.
        slots:
          vendor_id: path.end_device_profile_ids.vendor_id
          vendor_profile_id: path.end_device_profile_ids.vendor_profile_id
          band_id: query.version_ids.band_id
      method: generated
      generated: '2026-09-26'