VATSIM API research

Which VATSIM endpoints vCareer reads, what each is good for, and why we picked this set over the alternatives. Pull-only — no webhooks anywhere, because VATSIM doesn't offer them.

VATSIM Connect (OAuth 2.0)

The identity provider. OAuth 2.0 authorization-code flow against auth.vatsim.net (production) or auth-dev.vatsim.net (sandbox). We register one client per environment.

• What we get back: CID, full name, country, optionally email. Read-only scope.
• How often: exactly once per sign-in. The token is discarded after the user-info fetch; we don't store it.
• Lifetime: our session cookie lives 7 days. No refresh — sign in again at expiry.

See Sign in with VATSIM for the user-visible flow.

Core Member API (default flight history)

Endpoints under api.vatsim.net/v2/members/:cid/. Public, no auth, reliable. We use two endpoints:

• /history — connection sessions (when the pilot was online, callsign, dep/arr if filed).
• /flightplans — filed flight plans, joinable to history by connection_id.

Joining the two gives us callsign + dep + arr per session, which is enough to verify mission completion in the common case. The default FLIGHT_HISTORY_SOURCE is member-api.

v3 data feed (live state)

data.vatsim.net/v3/vatsim-data.json — the public live snapshot of every pilot and controller currently online. We poll it every 15 seconds and persist position samples for known users.

• Polling cadence: 15s. Cloudflare Workers cron tier fires every minute; we then sleep+poll four times inside the invocation.
• What we sample: pilot position (lat, lon, altitude, groundspeed, callsign) for any CID with an accepted IN_PROGRESS mission.
• What we filter: only known users (those with an active mission). The public feed contains hundreds of pilots; we don't store strangers.

The position pipe is what drives takeoff / landing / disconnect detection without needing a third-party tracking service. See Mission completion.

METAR

• Primary: VATSIM's own METAR endpoint, queried alongside the data feed.
• Fallback: aviationweather.gov for fields VATSIM doesn't carry.

Read on-demand at generation time and at completion time. Not persisted beyond the per-mission completion-log snapshot. See Weather and METAR.

Why pull, not push

VATSIM does not publish webhooks. There is no "tell me when CID X completes a flight" subscription. Every signal vCareer uses is read via polling:

• 15-second position-sample polls (live state).
• 60-second completion ticks (decide which missions transitioned state).
• On-demand Member API reads when the tick needs more history than samples alone provide.

The pull-only model is what lets us survive VATSIM upstream changes — a webhook contract would break on any upstream API rewrite; polling public endpoints is robust to schema versions and rate-limit changes.