API reference

Read telemetry

GET /api/telemetry returns an array of public records. Set resource to devices or telemetry, and provide an explicit comma-separated select list. A successful request with no matches returns [].

List devices:

/api/telemetry?resource=devices&select=device_id,launcher_name,status,launched_at&order=device_id.asc

Read one balloon’s latest 100 packets:

/api/telemetry?resource=telemetry&select=id,device_id,time,lat,lon,altitude_m,pressure,battery_voltage&device_id=eq.stratolink-3&order=time.desc,id.desc&limit=100

Use the same origin as the site. You do not need a database key to call these public read routes. They accept GET only, return JSON, and use Cache-Control: no-store.

Other query parameters return 400. There is no count envelope or cursor token; paginate using a stable order and offset. Fields supported by one resource are not automatically valid on the other.

Time ranges and pagination

This browser example reads a bounded UTC interval. Replace the ID and times with the flight you need. The upper bound limits the query to a fixed window while pages load.

const params = new URLSearchParams({
  resource: 'telemetry',
  select: 'id,device_id,time,lat,lon,pressure',
  device_id: 'eq.stratolink-3',
  order: 'time.asc,id.asc',
  limit: '1000'
});
params.append('time', 'gte.2026-05-17T00:00:00Z');
params.append('time', 'lte.2026-05-19T00:00:00Z');

const rows = [];
for (let offset = 0; ; offset += 1000) {
  params.set('offset', String(offset));
  const response = await fetch('/api/telemetry?' + params);
  if (!response.ok) throw new Error('Telemetry: ' + response.status);
  const page = await response.json();
  if (!Array.isArray(page)) throw new Error('Expected an array');
  rows.push(...page);
  if (page.length < 1000) break;
}

Offset pagination is not a database snapshot. Backfilled or deleted rows can move between pages; deduplicate by id if your analysis needs that protection. For a quick map query, add lat=not.is.null and lon=not.is.null. Omitting those filters preserves packets with useful sensors but no position.

Device fields

The read route does not expose account credentials, a registration write operation, or proof of device ownership.

Telemetry fields

Request these fields by name in select, except location_approximate, which the response adds when applicable. Preserve null; replacing missing GPS, a saturated sensor, or an unavailable channel with zero changes the meaning of the data.

The public API applies location privacy before returning records. Approximate positions can also suppress heading and derived velocity. Receiver coordinates and identifiers receive the same privacy treatment where applicable. The API does not apply every outlier filter used by the rendered flight track.

For acquisition and encoding, see Packets and data flow. For interpreting the charts, see the dashboard guide.

Forecasts

GET /api/forecast?device=stratolink-3 returns the available forecast for one device. It does not return a new measured location. Add &view=path to return only generated_at and nominal_path when drawing a fleet map.

Add &view=history to return only generated_at and the reconstructed track for a balloon that is no longer flying. Successful responses may be served from a shared cache for up to five minutes (Cache-Control: public, s-maxage=300, stale-while-revalidate=3600) and carry an ETag derived from generated_at; a request with a matching If-None-Match header receives 304 Not Modified. Pending, unknown-device and error responses are not cached.

Coordinate order is longitude first. Longitudes can extend past ±180° to keep paths continuous across the date line. Empty arrays and absent optional fields are valid. Location privacy also applies to forecast geometry.

Check the HTTP status before interpreting JSON. A 202 response means no stored forecast is available; it is not a complete forecast object. A 404 means the device is unknown or unconnected. A 503 means the forecast service could not complete the read. An unavailable forecast leaves the recorded telemetry intact.

Errors

Error responses contain a message string. The forecast endpoint reads the stored result; it does not start a new calculation. A 202 response is a pending result, not an error or a complete forecast. Do not treat an error object as an empty telemetry array.

TTN webhooks

Complete Connect TTN in the dashboard first. It provides a webhook URL and a separate Authorization header for the verified radio identity.

1. In the same TTN application and cluster, open Integrations → Webhooks and add a custom webhook.
2. Choose JSON. Paste the complete Webhook URL from the dashboard into Base URL.
3. Enable Uplink message and leave its path empty. The copied base URL already ends in /api/ttn-webhook. Leave the other event types disabled.
4. Leave Filter event data empty so the complete device identity, raw bytes, and reception metadata are forwarded.
5. Add a header named Authorization. Paste the dashboard’s complete value, including Bearer , into its value field.
6. Save and send a real payload uplink. Check successful delivery in TTN and Last received under Your balloons.

Copy the webhook credential before closing the result. Stratolink stores its hash, so the credential cannot be shown again. If it is lost or exposed, select Reconnect, verify the device again, then replace the header in TTN. Replacing it immediately invalidates the old credential.

The webhook credential is separate from the TTN API key used for verification, the radio’s AppKey, and your GitHub session. Never substitute one for another.

Run your own backend

The website and its Node API handlers live in web. Supabase stores accounts, device identities, and telemetry. The forecast worker writes to private Vercel Blob storage.

cd web
cp .env.example .env.local
ONNXRUNTIME_NODE_INSTALL=skip npm ci
npm run dev

Use Node 22. Set your Supabase URL, public authentication key, server-only database key, Mapbox token, and site origin in .env.local. Configure GitHub sign-in with a redirect back to your site’s /dashboard. Keep server credentials out of public environment variables.

Apply the database schema and migrations for the same source revision. The historical schema.sql alone is insufficient. Follow the migration instructions in the repository before connecting devices.

For Vercel, use web as the project root and dist as the build output. The included configuration serves the static pages and Node APIs. Configure the private forecast store and scheduled worker if you need projected paths.

Run npm run verify before deploying. npm run test:backend also checks the database contracts in a disposable local PostgreSQL container; it requires Docker.