Skip to main content

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.

V1 has one mutating endpoint, PATCH /v1/devices/{id}. Production clients should send an Idempotency-Key header so retries after a network blip don’t double-apply the update.

​
How it works

Set Idempotency-Key to any string from 1 to 255 characters. A UUID per request is the standard choice: 
curl -X PATCH https://api.1st.app/v1/devices/DEVICE_ID \
  -H "Authorization: Bearer $ST_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"display_name":"Player A room","metadata":{"hudl_player_id":"12345"}}'
The first request runs the update and caches the response, keyed on (api_key_id, Idempotency-Key). The cache lives for 24 hours. A repeat request with the same key and same body returns the cached response and includes Idempotent-Replayed: true in the headers. Your update did not run a second time. A repeat request with the same key but a different body returns a 422, the API assumes you accidentally reused a key for a different intent. 
{
  "error": {
    "type": "invalid_request_error",
    "code": "validation_failed",
    "param": "Idempotency-Key",
    "message": "Idempotency-Key already used with a different request body. Use a fresh key, or send the exact same body to replay the cached response."
  }
}

​
When to use it

Always, for production PATCH calls. Generate a fresh UUID per logical request. If your code retries on network failure, the retry should reuse the same UUID so the second attempt either replays the cached response or, if the first call never landed, runs cleanly the second time. If you don’t send Idempotency-Key, PATCH still works, but two concurrent retries can both mutate the row, and the second one wins silently.

​
Hashed scope

The cache also includes the request method and full path, so reusing the same Idempotency-Key across PATCH /v1/devices/A and PATCH /v1/devices/B doesn’t accidentally replay device A’s response for device B.