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": {},
  "last_seen_at": "2023-11-07T05:31:56Z",
  "signal": {
    "rssi_dbm": 123,
    "bars": 2
  },
  "active_assignment": {
    "assignment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "label": "<string>",
    "started_at": "2023-11-07T05:31:56Z",
    "external_ref": "<string>"
  }
}

Devices

Rename or tag a device

Update a device’s display name, or tag it with metadata you control (player IDs from your AMS, room codes, anything).

This is the only mutating endpoint. It needs a key with read_write scope. A read-only key gets a 403.

Both fields are optional, but the body must have at least one. Pass display_name: null to clear the name. Pass metadata: null to clear all tags.

Metadata replaces, doesn’t merge

Sending {"metadata": {"player_id": "42"}} removes any other metadata that was set before. To preserve other tags, fetch the device first, merge your new keys client-side, and send the full set back.

Idempotency

For production code, include an Idempotency-Key header. If your request times out and you retry with the same key, you get back the original response instead of accidentally applying the update twice. Cache lives for 24 hours.

Limits

display_name: max 200 chars
metadata: max 20 keys
Each metadata key: max 64 chars
Each metadata value: max 500 chars, must be a string (stringify your IDs client-side: String(playerId))

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": {},
  "last_seen_at": "2023-11-07T05:31:56Z",
  "signal": {
    "rssi_dbm": 123,
    "bars": 2
  },
  "active_assignment": {
    "assignment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "label": "<string>",
    "started_at": "2023-11-07T05:31:56Z",
    "external_ref": "<string>"
  }
}

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. Most integrators should use assignment.label instead — it ties the name to a specific period of usage, which keeps historical readings attributed correctly across rotations.

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).

Show child attributes

assignment

any

Reserved for V1.1. Sending this field returns 501 Not Implemented with a forward-pointing message.

Today: manage assignments via the dashboard at /devices/{id} — the assign / transfer / unassign dialog is wired to the same SECURITY DEFINER RPCs that the V1.1 API path will use.

Read-side endpoints (the active_assignment embed on GET /v1/devices, the dedicated GET /v1/devices/{id}/assignments history, and ?assignment_id= on readings + CSV) are fully operational and good to integrate against today.

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>.

Show child attributes

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.

Show child attributes

active_assignment

object

The currently-open assignment, when the device is in use. null when the device is Available (no active assignment).

An assignment ties readings to a person ("L. Marchetti") or a room ("Recovery Bed 3") so historical data stays meaningful after the device moves on. Past assignments are visible via GET /v1/devices/{device_id}/assignments.

Changes via PATCH /v1/devices/{device_id} with an assignment object in the body. See that endpoint for the full transfer / unassign semantics.

Show child attributes

Look up one device Assignment history for one device

Documentation Index

Authorizations

Headers

Path Parameters

Body

Response