Skip to main content
we-fly.cloud
Start logging →
Developers
reference · 3 min read

Saved airspace files

List and download the OpenAir files a pilot saved from the XC planner briefing: private, kept 30 days, OpenAir v1 or v2.1.

Pilots finish the XC planner (/xc-planner) with a briefing step that bundles the airspaces and NOTAMs they picked into one OpenAir file. Besides downloading it, a signed-in pilot can name it, pick OpenAir v1 or v2.1, and save it to their account. Saved files are what these endpoints serve, so a flight instrument or another tool can pull the pilot's planned airspace without a manual copy.

The contract in short

  • Private. A pilot only ever sees their own files. Another pilot's id answers 404, exactly like an id that never existed.
  • Short-lived. A file is deleted 30 days after it was saved (expiresAt). An expired file answers 404 straight away, even before the database purge removes it. Re-list instead of caching ids for weeks.
  • Immutable. A saved file never changes. Saving again creates a new file with a new id, so the id doubles as the ETag of the text.
  • Read-only. Files are created from the planner on the web. The API lists and downloads them; the pilot deletes them from the planner.
  • Scope: airspace:read (available to pending apps and personal API keys).

Endpoints

MethodPathScopeReturns
GET/api/v1/airspace/filesairspace:readThe pilot's live files, newest first. ?version=1|2.1, ?page, ?pageSize (max 100)
GET/api/v1/airspace/files/{id}airspace:readOne file's metadata
GET/api/v1/airspace/files/{id}/openairairspace:readThe OpenAir text, text/plain; charset=utf-8

The file object

{
  "id": "6710c3f2a8b4e1d2c3f4a5b6",
  "name": "Annecy task 3",
  "version": "2.1",
  "sizeBytes": 18234,
  "featureCount": 14,
  "flightDate": "2026-10-20",
  "createdAt": "2026-10-15T08:12:44.000Z",
  "expiresAt": "2026-11-14T08:12:44.000Z",
  "links": {
    "self": "/api/v1/airspace/files/6710c3f2a8b4e1d2c3f4a5b6",
    "openair": "/api/v1/airspace/files/6710c3f2a8b4e1d2c3f4a5b6/openair"
  }
}
FieldMeaning
nameThe name the pilot typed (at most 80 characters). Use it as the file name on the device, plus .txt
version"2.1" (extended: AY, AI, AF/AG, AA activation windows) or "1" (core records only)
featureCountAirspace polygons in the file, counted when it was saved
flightDateThe day the pilot planned for (YYYY-MM-DD), or null
expiresAtWhen the file disappears. Show it to the pilot if you keep a copy
linksRoot-relative; resolve them against the host you called

List

GET /api/v1/airspace/files?version=2.1 HTTP/1.1
Authorization: Bearer wf_at_...

{
  "data": [ { "id": "...", "name": "Annecy task 3", "version": "2.1", "...": "..." } ],
  "pagination": { "page": 1, "pageSize": 25, "totalCount": 1, "totalPages": 1 }
}

A version other than 1 or 2.1 answers 400 invalid_request.

Download the OpenAir text

GET /api/v1/airspace/files/6710c3f2a8b4e1d2c3f4a5b6/openair HTTP/1.1
Authorization: Bearer wf_at_...
If-None-Match: "6710c3f2a8b4e1d2c3f4a5b6"
HeaderValue
Content-Typetext/plain; charset=utf-8
Content-Dispositionattachment; filename="Annecy task 3.txt"; filename*=UTF-8''Annecy%20task%203.txt. filename is an ASCII fallback (other characters become _); read filename* for the real name
ETag"<id>". Send it back as If-None-Match to get a body-free 304
X-OpenAir-Version1 or 2.1
X-Expires-AtSame as expiresAt

The text uses \n line endings and ends with a newline. See the OpenAir airspace format for the records a v2.1 file may carry.

Errors

StatuserrorWhen
400invalid_requestThe id is not a valid id, or version is not 1 / 2.1
401invalid_tokenMissing, expired or revoked token
403insufficient_scopeThe token lacks airspace:read
404not_foundNo such file, someone else's file, or the file expired
429(none, see Retry-After)Your tier's rate limit; see Rate limits

A typical instrument sync

  1. GET /api/v1/airspace/files?version=2.1 (or 1 if your parser only reads the core records).
  2. For each file you do not have yet, GET its links.openair and store it in the instrument's airspace folder under name + .txt.
  3. Delete local copies whose id is no longer listed: the pilot deleted them or they expired.