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.

The 1st API gives you the same data your dashboard shows. CO2, temperature, humidity, light, and sound, for every device on your team. You don’t write integrations from this page. You give an AI the docs and it writes the integration for you.

​
Two words to know

  • A device is the plug-in unit that lives in a room. It measures the room every 5 minutes.
  • A reading is one of those measurements. The API returns readings; you don’t talk to the device directly.

​
Build your first integration with AI

Paste this prompt into Claude, ChatGPT, or Cursor. Fill in what you actually want: 
Read https://dev.1st.app/llms-full.txt, that's the complete
reference for the 1st sensor platform API.

Build me a [Google Apps Script | Airtable Script | Bubble plugin |
Python script | n8n workflow] that [describe what you want].

The API key is in [PropertiesService.ST_API_KEY | env var
ST_API_KEY | Airtable secret]. Don't put the key in the code.
The AI reads the docs, asks any clarifying questions, then writes working code. Run it where it tells you to. If something goes wrong, paste the error response back to the AI and ask it to fix the issue. Our error messages include the fix inline, so the AI self-corrects on the first try.

​
What the AI is reading

When the AI calls the API on your behalf, this is what it sees and sends. You don’t need to memorize any of it, but it’s here if you want to check what the AI is doing.

​
Base URL

https://api.1st.app/v1

​
Authentication

Every request carries your API key in an Authorization header: 
Authorization: Bearer YOUR_API_KEY
The key already knows which team you’re on. You never pass a team ID anywhere.

​
A sample response

GET /v1/team returns: 
{
  "team": {
    "id": "9b3a3b6e-0f9c-4f3a-9b6c-2c0b8a9d0e10",
    "name": "Brooklyn FC"
  },
  "api_key": {
    "key_id": "abcdwxyz23456789",
    "scopes": ["read"]
  }
}

​
What can I do with the API?

I want to…Page
See every device on my teamSee all your devices
Show what every device is reading right nowLive snapshot of every device
Look up one specific device by its IDLook up one device
See who or what each device is assigned toSee all your devices (the active_assignment field)
Get the assignment history for one deviceAssignment history for one device
Pull readings for one athlete’s session, even after they hand the device backPull one athlete’s last block of readings
Rename a device or tag it with a player IDRename or tag a device
Get the reading history for one deviceHistory for one device
Pull a month of data into a spreadsheetDownload everything as a CSV

​
When something goes wrong

Errors all look the same: 
{
  "error": {
    "type": "invalid_request_error",
    "code": "device_not_found",
    "message": "No device with this ID exists in your team. List devices via GET /v1/devices first.",
    "doc_url": "https://dev.1st.app/errors/device_not_found",
    "request_id": "req_1a2b3c4d5e6f7a8b"
  }
}
Paste the response into your AI tool and ask it to fix the issue. The message field is written so the AI can self-correct without needing more context. Full code list: Errors.