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.

You probably already have a player roster somewhere: Hudl, Catapult, Kitman, an internal spreadsheet. This guide shows you how to connect each 1st device to the player it belongs to, so when you pull data you can say “give me Sarah’s room conditions” instead of “give me device 8a72a1c7’s conditions.”

​
The idea in one sentence

Each device has a place where you can stick your own labels. You tag the device with the player’s ID from your AMS, and later you ask 1st to find devices by that label.

​
A concrete example

Sarah is your goalkeeper. Her player ID in Hudl is 12345. She sleeps in the room with the device whose ID is 8a72a1c7-3c91-4f5b-b39e-1d2c4e3f5a7b. You want to:
  1. Tag that device so 1st knows it belongs to Sarah (Hudl ID 12345).
  2. Later, find that device by saying “the one tagged Hudl 12345”.
  3. Pull her room’s data for the night.
That’s the whole flow. The rest of this page shows you how to ask an AI to do each step.

​
Step 1: Tag the device

The fastest way is to ask Claude or ChatGPT. Paste this prompt: 
Read https://dev.1st.app/llms-full.txt.

Then write a one-time Python script that tags 1st device
8a72a1c7-3c91-4f5b-b39e-1d2c4e3f5a7b with:
  hudl_player_id = 12345
  position = GK
  player_name = Sarah Mitchell

My read_write API key is in env var ST_API_KEY_RW.
You’ll need a Read and write API key for this step. Read-only keys can’t change anything. Create one at dashboard.1st.app/integrations/api-keys if you don’t have one yet. The AI will produce something like this, which you save as a file and run once: 
import os, requests, uuid

API_KEY = os.environ["ST_API_KEY_RW"]
DEVICE_ID = "8a72a1c7-3c91-4f5b-b39e-1d2c4e3f5a7b"

resp = requests.patch(
    f"https://api.1st.app/v1/devices/{DEVICE_ID}",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "metadata": {
            "hudl_player_id": "12345",
            "position": "GK",
            "player_name": "Sarah Mitchell",
        }
    },
)
resp.raise_for_status()
print("Tagged:", resp.json())
Save it as tag_device.py, set ST_API_KEY_RW in your terminal, and run python3 tag_device.py. Done. The device is now linked to Sarah.
Setting tags overwrites the old ones. If the device already had labels and you call this with just hudl_player_id, the others are gone. To keep the existing labels, ask the AI to “merge the new tags with the existing ones”: it’ll read the device first, combine the values, then save them back.

​
Step 2: Find Sarah’s device later

Once tagged, you can find the device by its Hudl ID anytime: 
https://api.1st.app/v1/devices?metadata.hudl_player_id=12345
That URL returns the device tagged with that exact value. Same pattern with any tag you set: ?metadata.position=GK returns every keeper’s device, ?metadata.player_name=Sarah+Mitchell returns Sarah’s (URL-encoded space). To combine conditions (say, “GK who is on the senior squad”): 
https://api.1st.app/v1/devices?metadata.position=GK&metadata.squad=senior
You’ll only get devices that match both tags.

​
Step 3: Pull Sarah’s room data

You now have her device’s ID. Ask the AI for whatever shape you want: 
Read https://dev.1st.app/llms-full.txt.

Pull last night's CO2 and temperature readings for device
8a72a1c7-3c91-4f5b-b39e-1d2c4e3f5a7b, group them into hourly
averages, and write the result to a CSV named "sarah-last-night.csv".

Key in env var ST_API_KEY.
For a whole month or many players at once, ask for the bulk CSV endpoint instead, it pulls everything in one request: 
Read https://dev.1st.app/llms-full.txt.

Download a CSV of May's CO2 + temp for every keeper (devices tagged
with metadata.position=GK). Use the /v1/readings.csv endpoint with
shape=wide and the devices= filter.

​
What to tag, and what not to

Tags are just strings: keys up to 64 characters, values up to 500 characters, 20 tags per device. Use them however you want, but a few patterns that work well across teams we’ve worked with: Tag the room, not the person. A device lives in a physical room. If Sarah moves rooms, retag the device in her new room with her player ID. Don’t try to make the tag travel with the player. Use one tag per system you sync with. If you push data to both Hudl and your own internal Airtable, use hudl_player_id=12345 and airtable_player_id=ABC-12. That way each system can find its own devices without stepping on the other. Name your read-write key after the system using it. Create a key called “Hudl sync” if that’s what it’s for. When you look at your key list later, you’ll know which one runs which integration. If one breaks or leaks, you only rotate that one.

​
If you have a lot of devices to tag at once

Same idea, just loop. Ask the AI: 
Read https://dev.1st.app/llms-full.txt.

I have a CSV at /Users/me/roster.csv with columns: device_id,
hudl_player_id, player_name, position. Write a Python script that
sets tags on each device with these values. Use Idempotency-Key
per row so retries are safe.

Key in env var ST_API_KEY_RW.
You’ll get back a script that reads your roster and applies all the tags in one run.

​
What happens if two scripts tag the same device at the same time

Last write wins. There’s no smart merge. If your Hudl sync and your Airtable sync both try to tag the same device in the same minute with different keys, only one of them survives. If you run multiple sync jobs against the same fleet, either:
  • Make each sync responsible for different devices (so they never collide).
  • Stagger them on different schedules.
  • Have one master sync that pulls from all sources and writes a merged tag set.
For most teams, this never comes up: you have one AMS, one sync job, one schedule. But it’s the kind of thing that bites at scale.