API help

Power users can connect TailTracker to scripts and apps with JSON and Bearer tokens.

Authentication

Add this header to every request:

Authorization: Bearer YOUR_API_KEY

Quick example

curl -H "Authorization: Bearer YOUR_API_KEY" \
https://tailtracker.app/api/planes

Endpoints

GET/apiHealth check

GET/api/meCurrent user information

GET/api/planesYour aircraft history

GET/api/statsEntry counts by status

GET/api/insightsAdvanced collection insights for the signed-in user

GET/api/planes/lookup?tail=XX-XXXAircraft lookup with operator, photo, and whether it is already in your history

Response format example

{
  "planes": [
    {
      "id": 123,
      "tail_number": "HB-JVJ",
      "type": "A320",
      "aircraft_type": {
        "id": 3,
        "icao": "A20N",
        "manufacturer": "Airbus",
        "model": "A320neo",
        "family": "A320 family",
        "display_name": "Airbus A320neo",
        "is_missing": false,
        "is_legacy": false
      },
      "tag": "on board",
      "flight_number": "SWR1069",
      "destination": "ZRH",
      "flight_date": "2025-07-06",
      "operator": "Helvetic Airways",
      "image_url": "/uploads/xxxx.jpg"
    }
  ]
}

Aircraft type fields

Aircraft objects include a structured aircraft_type object. Prefer this over the older free-text type field.

aircraft_type.icao: ICAO aircraft type code, e.g. A320, A20N, B77W.
aircraft_type.display_name: human-friendly model name, e.g. Airbus A320neo.
aircraft_type.family: aircraft family, e.g. A320 family.

Older records may temporarily return a legacy type field while TailTracker migrates to structured aircraft types.

Lookup response note

/api/planes/lookup?tail=XX-XXX returns the same aircraft_type object on plane, plus missing-data flags including missing.aircraft_type. This is suitable for future integrations that need tail + type + photo + user-history matching.

Common errors

missing_api_key: the Authorization header is missing.
invalid_api_key: the token is invalid or revoked.
rate_limited: too many requests. Wait and retry.

Tip: keep your API key secret. Regenerate it if it leaks.