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.

Every API key carries one scope, chosen at mint time:
ScopeWhat it can do
read (default)List sensors, read current conditions, pull time-series readings, export CSV. Cannot mutate anything. Use this for dashboards, monitoring scripts, spreadsheet feeds, Slack bots — the vast majority of integrations.
read_writeEverything read does, plus PATCH /v1/sensors/{id} to update display names and metadata. Needed when your AMS or coach app should write back into 1st — e.g. tagging a sensor with a Hudl player_id.
Pick the smaller scope when in doubt. A leaked read key reveals data but can’t mutate anything; a leaked read_write key can rename rooms and rewrite metadata.

​
Why this isn’t OAuth

V1 uses static API keys instead of OAuth because the persona is an analyst pasting a key into Sheets / AMS / a Bubble app, not a backend developer wiring up an OAuth flow. Static keys with strong rotation ergonomics (revoke + reissue in two clicks) win on UX for that user. OAuth is on the roadmap for partner integrations once 1st has a catalog of approved consumer apps.

​
Errors

Trying to call PATCH /v1/sensors/{id} with a read-scope key returns: 
{
  "error": {
    "type": "invalid_request_error",
    "code": "insufficient_scope",
    "message": "This API key does not have write scope. Mint a new key with `read_write` scope under /developers in the app.",
    "doc_url": "https://docs.1st.app/errors/insufficient_scope",
    "request_id": "req_..."
  }
}
The fix: mint a new key with Read and write scope, swap it in, leave the read-only key in place for your dashboards.