Help centre · For airline staff

Integrations: API keys, webhooks and the Operations API

Your airline's data can feed your own tools: a Discord bot, your website, a spreadsheet. Everything here is on the Integrations tab of Staff → Airline settings → Settings. You need the Airline settings and the operations key permission; staff who only manage Discord don't see this tab.

The Operations API key

Create key gives the airline one key that can read everything in the Operations API but change nothing. It's shown once; only a fingerprint is kept, so copy it straight away. If you lose it, make a new one (the old one stops working). The key belongs to the staff member who made it: if they leave the airline or lose staff access or these permissions, it stops working and someone with the permission makes a new one.

Send it with each request as the header Authorization: Bearer your-key. Open /api/v1/ops on the site to see every address; the main ones are:

/api/v1/ops/flights: flights in the air now and the ones filed in the last minutes, with the PIREP result.
/api/v1/ops/pireps: the history of decided PIREPs (accepted, rejected and so on), oldest decision first, with route, times, aircraft, landing rate and points.
/api/v1/ops/pilots and /api/v1/ops/pilots/FCV0002: the roster, and one pilot's rank, hub, hours and location.
/api/v1/ops/routes, /api/v1/ops/fleet, /api/v1/ops/events and /api/v1/ops/ranks: the schedule, the fleet (types and each aircraft), upcoming events and the rank ladder, for your own website.

Every address only reads. Each key can make up to 120 requests a minute.

Examples

Your roster, 100 pilots at a time: curl -H "Authorization: Bearer your-key" "https://vaeroly.com/api/v1/ops/pilots?limit=100&offset=0"
The next 100: the same with offset=100. The answer's next_offset says where the next page starts, and is null on the last page; total says how many there are. Without limit you get the whole list at once.
Your fleet: curl -H "Authorization: Bearer your-key" https://vaeroly.com/api/v1/ops/fleet
PIREPs decided since 1 October: curl -H "Authorization: Bearer your-key" "https://vaeroly.com/api/v1/ops/pireps?since=2026-10-01&limit=200"
The page after that: add cursor= with the next_cursor of the answer. Keep the last next_cursor you got, and your tool can catch up from there after a break. A PIREP whose decision changes later comes again with its new status. A decision is listed once it is 2 minutes old, so a page never skips one that was still being saved.

What the API never shows

The API never gives out email addresses or anything else private. Pilots' privacy choices count here as on the site:

A pilot who hides their flights from live maps doesn't appear in /flights or /pireps.
A pilot who stays off leaderboards is listed in /pireps without a name ("pilot": null), so their flights can't be ranked.
Pilots whose account is about to be deleted are left out everywhere.

Named API keys

With Named API keys on (Optional features), make one key per tool, each allowed only what it needs: Flights, Pilots, Schedule, or Pilot changes (turning a pilot's activity exemption on or off). Flights covers /flights and /pireps; Schedule covers routes, fleet, events and ranks. A key can expire on a date and can be revoked on its own. Up to 10 per airline; the list shows when each was last used.

Webhooks

With Webhooks on, your own server gets a message within seconds when something happens: a PIREP filed or reviewed, a pilot joining or leaving, a rank change, a booking made or cancelled, a flight taking off. Each message is signed, so your server can check it came from Vaeroly (the X-Vaeroly-Signature header, an HMAC of the timestamp and body with the webhook's secret).

Webhooks follow pilots' privacy choices as the API does. A pilot who hides their flights from live maps, or whose account is about to be deleted, sends no booking, take-off or PIREP messages. A pilot who stays off leaderboards comes without a name in PIREP messages ("pilot": null). Messages about pilots joining, leaving or changing rank are sent for everyone, as /pilots lists them.

Check two more things on your server. The X-Vaeroly-Timestamp header is the time the message was signed, in Unix seconds: turn away a message whose timestamp is more than 5 minutes from your server's clock, so a copied message can't be played back to you later (each try is signed afresh, so retries pass). And the same message can reach you more than once, for example when your server took the message but answered too slowly and it was tried again: every try of a message carries the same X-Vaeroly-Delivery number, so keep the numbers you have handled for a few days and skip one you have already seen. A delivery sent again with Send again in the log is a new delivery with a new number.

Failed deliveries are retried for about 15 hours. Each webhook has a delivery log and a Send a test button. A webhook that has failed for 3 days is switched off and the owner gets an email. Up to 5 per airline (open Log & settings on a webhook for its log and the test button). Each webhook can send a test, or resend a delivery, once every 30 seconds, and an airline can send 20 tests and resends an hour.