---
title: "A worked example for one device: the bytes it sends and the ACKs it gets (any member)"
method: GET
path: "/v1/projects/{project_id}/udp/devices/{device_id}/example"
tags: ["udp"]
---

# A worked example for one device: the bytes it sends and the ACKs it gets (any member)

`GET /v1/projects/{project_id}/udp/devices/{device_id}/example`

## Request

- Base URL: `https://api.wavehouse.cloud`
- URL: `https://api.wavehouse.cloud/v1/projects/{project_id}/udp/devices/{device_id}/example`
- Auth: one of:
  - API key in cookie `whc_session`
  - HTTP bearer
  - API key in header `X-API-Key`

Everything needed to write sender firmware for THIS device: a sample payload, a sample nonce of its own width, the resulting datagram in hex, the ACK for each status, and a field-by-field byte-offset table for both directions. The nonce and payload are samples and are labeled as such — `nonce_note` says what the device must send instead, which for every keyed suite is a value that NEVER repeats under its key. Everything else is the device's real row, so the datagram is byte for byte what it would put on the wire. The key is used to compute this and is never returned: it existed once, in the create response.

## Path parameters

- `project_id` string, required
- `device_id` string, required: the device's 16-hex-character id

## Response `200`

OK

- UDPExampleView
  - `ack_fields` UDPExampleFieldView[], required: the downlink's layout, in order
    - `field` string, required: device_id | nonce | payload | ciphertext | tag | status
    - `hex` string, required
    - `length` integer, required
    - `offset` integer, required: bytes from the start of the datagram
  - `acks` UDPExampleAckView[], required: one entry per status, in numeric order
    - `hex` string, required
    - `name` string, required: stored | throttled | disabled
    - `status` integer, required: 0 stored, 1 throttled (retry later), 2 disabled (stop)
  - `addresses` string[], required: the canonical static endpoint: anycast addresses, IPv4 and IPv6, that never change — hard-code one
  - `content_encoding` string
  - `content_type` string, required
  - `datagram_hex` string, required
  - `datagram_len` integer, required: bytes on the wire; keep a real datagram under about 1200 so it is never fragmented
  - `device_id` string, required
  - `encoding_note` string: present only when the device compresses: the sample payload stands in for compressed bytes
  - `fields` UDPExampleFieldView[], required: the uplink's layout, in order, covering every byte
    - `field` string, required: device_id | nonce | payload | ciphertext | tag | status
    - `hex` string, required
    - `length` integer, required
    - `offset` integer, required: bytes from the start of the datagram
  - `hostname` string: an optional DNS name for this deployment, when configured; addresses are the endpoint, not a fallback
  - `nonce_hex` string, required
  - `nonce_len` integer, required
  - `nonce_note` string, required: what the sample nonce is, and what the device must send in its place
  - `payload_hex` string, required
  - `payload_text` string, required: the sample payload as text — one NDJSON line, one JSON object, or one CSV row
  - `port` integer, required
  - `provisioned` boolean, required: false when this deployment has no UDP listener; the example is still exact
  - `sealed` boolean, required: the payload is encrypted, so the datagram carries ciphertext where the payload would be
  - `suite` string, required
  - `table` string, required
  - `tag_len` integer, required

## Other responses

- `429`: Rate limited, per client IP, API key or org; a client IP is also refused on every route for a while after repeated authentication failures. A limited operation carries RateLimit-Policy and RateLimit on every response; wait Retry-After seconds before retrying.
- `default`: Error

---

[API](https://skmtc.dev/wavehouse/apis/wavehouse-cloud-api.md) · [All operations](https://skmtc.dev/wavehouse/apis/wavehouse-cloud-api/llms.txt) · [OpenAPI document](https://skmtc.dev/wavehouse/apis/wavehouse-cloud-api/revisions/adea029bf505?raw)