Skip to main content
PATCH
/
devices
/
{device_id}
Rename or tag a device
import requests

url = "https://api.1st.app/v1/devices/{device_id}"

payload = {
    "display_name": "Locker Room North",
    "metadata": {
        "hudl_player_id": "12345",
        "position": "GK"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)
{
  "device_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "hardware_id": "<string>",
  "display_name": "<string>",
  "firmware_version": "<string>",
  "metadata": {},
  "status": "online",
  "last_seen_at": "2023-11-07T05:31:56Z",
  "signal": {
    "rssi_dbm": 123,
    "bars": 2
  }
}

Documentation Index

Fetch the complete documentation index at: https://dev.1st.app/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
Authorization
string
header
required

Your API key. Create one at dashboard.1st.app/integrations/api-keys.

Headers

​
Idempotency-Key
string

Optional but recommended. A unique string you generate (a UUID works well) so that if your code retries after a network error, the second call gets back the original response instead of changing the device twice.

Same value + same body returns the cached response. Same value + different body returns a 422 (we assume you reused the key by mistake). We cache for 24 hours.

Maximum string length: 255
Example:

"550e8400-e29b-41d4-a716-446655440000"

Path Parameters

​
device_id
string<uuid>
required

The UUID of the device you want. You get a device's ID from GET /v1/devices (look at the device_id field) or by copying it from the dashboard URL.

Example:

"8a72a1c7-3c91-4f5b-b39e-1d2c4e3f5a7b"

Body

application/json
​
display_name
string | null

Human-readable name shown in dashboards and CSV exports. Set to null to clear.

Maximum string length: 200
​
metadata
object

Your own tags on the device, for linking it to IDs in your other systems (player IDs, room numbers, position codes).

Response

The updated device.

​
device_id
string<uuid>
required

The device's permanent ID. Use this anywhere the API asks for a device_id. It stays the same across firmware updates and hardware swaps.

​
hardware_id
string
required

The serial number on the physical device, looks like dev:868050050000123. Most integrations can ignore this. We surface it so you can cross-reference against your own inventory spreadsheet if you keep one. You can't pass hardware_id anywhere in the API; everywhere we ask for an ID, it wants device_id.

​
display_name
string | null
required

The friendly name shown in the dashboard, like "Locker Room. North". You set this with PATCH /v1/devices/{id}. null if you haven't named it yet.

​
firmware_version
string | null
required

Which version of our firmware the device is running, like 1.4.2. Bumped automatically by over-the-air updates.

​
metadata
object
required

Your own tags on this device, player IDs, room numbers, position codes, whatever you need to link the device back to your own systems. You set these with PATCH /v1/devices/{id}, and you filter /v1/devices with ?metadata.<key>=<value>.

​
status
enum<string>
required

How fresh the device's data is.

online, sent data in the last hour.

stale, last data was 1–24 hours ago.

offline, over 24 hours since last data, or the device has never reported.

Available options:
online,
stale,
offline
​
last_seen_at
string<date-time> | null
required

When the device last uploaded data, in UTC. null if the device has never reported (e.g. you registered it but never plugged it in).

​
signal
object
required

How strong the device's cellular signal was on its last upload. A weak signal doesn't drop readings, the device buffers locally, but it does mean data lands later.