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.

​
2026-05-14 — V2 surface (pre-launch reshape)

Public API reshape. Pre-launch reset: no customer integrations existed against the V1 shape, so the legacy /api/v1/teams/{team_id}/... paths and 1st_pk_ prefix are gone. New surface:
  • GET /v1/team — echo the team this key is scoped to.
  • GET /v1/sensors (+ ?metadata.<k>=<v> filter) — list sensors.
  • GET /v1/sensors/current — latest reading per sensor in one call.
  • GET /v1/sensors/{id} — single sensor.
  • PATCH /v1/sensors/{id} — update display_name and metadata (requires read_write scope, supports Idempotency-Key for safe retries).
  • GET /v1/sensors/{id}/readings — time-series, cursor-paginated.
  • GET /v1/readings.csv — bulk CSV. ?shape=wide for spreadsheet pivot, ?key=... query-param auth for Google Sheets / Excel connectors.
Key format renamed 1st_pk_<id>.<secret> → 1st_sk_<id>.<secret>. The sk_ prefix matches Stripe convention for secret keys — pk_ reads as publishable in Stripe docs, which would tell any AI agent trained on Stripe to treat the key as safe-to-share. New error codes: api_key_expired, insufficient_scope. Removed: team_mismatch, team_not_found. Path-based team mismatch is gone because team_id no longer appears in the URL — the key alone scopes the request. Endpoints removed in this pass: async exports (POST /teams/{id}/exports, GET /teams/{id}/exports/{id}) and alerts (GET /teams/{id}/alerts). Async exports replaced by streaming /v1/readings.csv (250k-row cap). Alerts removed pending the customer-facing alerts UI.

​
Deprecation policy

Stable contract:
  • Error code strings.
  • Endpoint paths.
  • Response field names that exist today.
  • HTTP status codes per error condition.
May change in patch releases:
  • Error message text (tuning for clarity / AI legibility).
  • Doc URLs.
Will be announced at least 90 days before breaking:
  • Adding required fields to request bodies.
  • Removing endpoints.
  • Changing response field types.
We’ll announce on this changelog page and email all teams with active keys. For 60 days after a breaking change ships, the old behaviour stays available under the previous URL prefix (e.g. /v1.0/...) when a backwards-compatible path is feasible.