# 1st Sensor Platform API

> Real-time room-environment data (CO2, temp, humidity, light, sound) for elite sports facilities. Multi-tenant REST API with API-key auth, designed for AI-augmented integrators.

This is the lightweight index. For the full single-context-window dump, see [llms-full.txt](https://docs.1st.app/llms-full.txt).

## Getting started

- [Quickstart](https://docs.1st.app/quickstart): From zero to first API request in under five minutes.
- [Authentication](https://docs.1st.app/authentication): API key format, rotation, leak response.
- [Scopes](https://docs.1st.app/scopes): Read vs Read+Write — what each key can do.
- [Pagination](https://docs.1st.app/pagination): Cursor pagination pattern.
- [Idempotency](https://docs.1st.app/idempotency): Safe retries on PATCH via Idempotency-Key.
- [Errors](https://docs.1st.app/errors): All stable error codes.

## Guides

- [Build with AI](https://docs.1st.app/guides/build-with-ai): Five copy-paste prompts that turn AI tools into your integration developer.
- [Google Sheets recipe](https://docs.1st.app/guides/google-sheets-recipe): IMPORTDATA template + Apps Script alternative.
- [CSV export](https://docs.1st.app/guides/csv-export): Bulk historical pulls.
- [AMS integration](https://docs.1st.app/guides/ams-integration): Map sensors to players via metadata.
- [Common gotchas](https://docs.1st.app/guides/common-gotchas): Timezones, missing sensors, rate-limit timing.

## API reference

- [GET /v1/team](https://docs.1st.app/api-reference/get-team): Echo the team this key is scoped to.
- [GET /v1/sensors](https://docs.1st.app/api-reference/list-sensors): List sensors with status + metadata. Supports `?metadata.<k>=<v>` filter.
- [GET /v1/sensors/current](https://docs.1st.app/api-reference/list-sensors-current): Latest reading per sensor in one call.
- [GET /v1/sensors/{sensor_id}](https://docs.1st.app/api-reference/get-sensor): Single sensor.
- [PATCH /v1/sensors/{sensor_id}](https://docs.1st.app/api-reference/update-sensor): Update display_name + metadata (requires read_write scope, supports Idempotency-Key).
- [GET /v1/sensors/{sensor_id}/readings](https://docs.1st.app/api-reference/list-readings): Time-series readings, cursor-paginated.
- [GET /v1/readings.csv](https://docs.1st.app/api-reference/readings-csv): Bulk CSV export. Supports `?shape=wide` and `?key=...` for Sheets/Excel.

## Error codes

- [api_key_missing](https://docs.1st.app/errors/api_key_missing): 401 — no Authorization header.
- [api_key_invalid](https://docs.1st.app/errors/api_key_invalid): 401 — header malformed or wrong secret.
- [api_key_revoked](https://docs.1st.app/errors/api_key_revoked): 401 — key was revoked.
- [api_key_expired](https://docs.1st.app/errors/api_key_expired): 401 — key passed its expiry date.
- [insufficient_scope](https://docs.1st.app/errors/insufficient_scope): 403 — read-only key calling PATCH.
- [rate_limit_exceeded](https://docs.1st.app/errors/rate_limit_exceeded): 429 — 600/10min/key.
- [cursor_invalid](https://docs.1st.app/errors/cursor_invalid): 400 — malformed cursor.
- [cursor_team_mismatch](https://docs.1st.app/errors/cursor_team_mismatch): 400 — cursor issued under another key.
- [time_range_too_wide](https://docs.1st.app/errors/time_range_too_wide): 400 — over 90 days.
- [time_range_invalid](https://docs.1st.app/errors/time_range_invalid): 400 — bad ISO 8601.
- [sensor_not_found](https://docs.1st.app/errors/sensor_not_found): 404 — sensor not in your team.
- [validation_failed](https://docs.1st.app/errors/validation_failed): 400 — generic input rejection (includes Idempotency-Key conflicts).
- [internal_error](https://docs.1st.app/errors/internal_error): 500 — backend hiccup, retry.

## Reference

- [Changelog](https://docs.1st.app/changelog): Release history + deprecation policy.
- [OpenAPI spec](https://docs.1st.app/api/openapi.yaml): Direct YAML link (the SDK for AI codegen).