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/sensors/{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 opaque string between 1 and 255 chars (a UUID per logical request is the standard choice): 
curl -X PATCH https://api.1st.app/v1/sensors/SENSOR_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 key includes the request method and full path in addition to Idempotency-Key, so the same opaque string used on PATCH /v1/sensors/A and PATCH /v1/sensors/B doesn’t accidentally replay sensor A’s response for sensor B.