API overview

Where Is Tereza? exposes two surfaces:

  1. Ingest endpoints — the URLs your GPS device or app POSTs to. These are per-organization and authenticated via a token in the URL.
  2. Public read endpoints — for embedding trip data, building custom dashboards, or pulling weather/locations for downstream use.

This section documents both. All examples use curl, but any HTTP client works.

Base URL

Each organization is reachable at:

https://app.whereistereza.com/o/{your-org-slug}

If you have a custom domain configured (Nomad plan), you can also use https://yourdomain.com directly.

Authentication

Ingest endpoints

Each GPS source you add in the admin gives you a URL with a unique token embedded in the path. Treat the URL itself as the secret — anyone with it can publish location updates to your account.

The token is per-source (you can have many: one for OwnTracks, one for inReach®, one for a friend's phone). Revoking a token disconnects that source without affecting the others.

Public read endpoints

Public trips are world-readable and need no authentication. Unlisted trips need the share token in the URL path. Private trips ask for the trip password (HTTP Basic, or a ?key= query parameter).

Member-only endpoints

Some endpoints (anything that mutates data) require an authenticated session — see the magic-link sign-in flow at /auth/login.

Rate limits

  • Ingest: 60 requests per minute per token. Bursts to 120/minute are tolerated; sustained excess returns HTTP 429.
  • Public reads: 600 requests per minute per IP. Reach out if you need higher limits for an embed.
  • Auth requests (magic links): 5 per IP per 5 minutes.

Response formats

JSON unless otherwise stated. All timestamps are ISO 8601 with timezone (we always include a Z for UTC or an offset). Distances in metres unless documented otherwise; speeds in metres per second.

Error format

{
  "detail": "Human-readable error message"
}

HTTP status follows convention:

  • 400 — bad input (validation failure).
  • 401 — missing or invalid auth.
  • 402 — quota exceeded for the org's plan.
  • 404 — resource not found.
  • 429 — rate-limited.
  • 5xx — our problem; please report.

Versioning

The API is unversioned today. Breaking changes are announced in the Changelog at least four weeks in advance. Additive changes ship without notice.

Need help? Contact support · Where Is Tereza?