Flight Data API

Free-form, server-side persistent storage attached to an imported OFP. Use it to back the journey log, fuel log, post-flight report, free notes — anything the client wants to keep across sessions and devices, with built-in optimistic locking to avoid lost updates.

Overview

Every entry is uniquely keyed by (userId, ofpId, dataKey). The payload is opaque from the server's perspective — the backend never inspects it, so you can evolve your schema entirely in the client. Each row carries a monotonic version and updatedAt timestamp so concurrent edits can be detected and surfaced to the user.

Concepts & Conflict Strategy

The dataKey

A short client-defined section name (max 64 chars, allowed: A-Z a-z 0-9 . _ -). One OFP can carry as many keys as you need — for example:

• journeyLog — pilot's filled journey log
• fuelLog — fuel uplift / fuel-on-board history
• notes — free-text notes
• postFlightReport — post-flight write-up

If you omit dataKey, the key "default" is used.

Optimistic locking

flightDataSave accepts two markers describing what the client believes is the latest state on the server:

Both fields are optional. Sending neither effectively asks for last-write-wins; sending both is the recommended belt-and- suspenders approach.

Authorization scope

Today only the OFP owner — the user who originally imported it — can read or write its Flight Data. Cross-account sharing (sharing a flight with another pilot) is delivered by the upcoming OFP Sharing endpoints; once enabled, Flight Data access will automatically follow the share's permission level.

flightDataList

List every saved dataKey attached to a given OFP, including the current version, timestamps and payload size. Useful for the client to detect "there is a newer version of this section on the server".

curl -X POST "https://api.virtualperformancetool.com/api" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "flightDataList",
    "data": { "ofpId": "12345_4" }
  }'

{
  "success": true,
  "ofpId": "12345_4",
  "count": 2,
  "items": [
    {
      "dataKey": "journeyLog",
      "version": 9,
      "createdAt": "2026-05-27 18:02:11",
      "updatedAt": "2026-05-27 19:31:08",
      "createdByUserId": 9576,
      "updatedByUserId": 9576,
      "payloadBytes": 4821
    },
    {
      "dataKey": "fuelLog",
      "version": 2,
      "createdAt": "2026-05-27 18:14:00",
      "updatedAt": "2026-05-27 18:47:33",
      "createdByUserId": 9576,
      "updatedByUserId": 9576,
      "payloadBytes": 312
    }
  ]
}

flightDataGet

Fetch the full payload for one (ofpId, dataKey). Returns the raw payload (decoded from JSON if possible) plus version metadata.

{
  "success": true,
  "data": {
    "ofpId": "12345_4",
    "dataKey": "journeyLog",
    "payload": { "...": "client-defined object" },
    "version": 9,
    "createdAt": "2026-05-27 18:02:11",
    "updatedAt": "2026-05-27 19:31:08",
    "createdByUserId": 9576,
    "updatedByUserId": 9576
  }
}

flightDataSave

Create or update one (ofpId, dataKey). Returns the newly saved row including its bumped version and server-side updatedAt. On conflict, returns HTTP 409 with the server's current copy.

curl -X POST "https://api.virtualperformancetool.com/api" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "flightDataSave",
    "data": {
      "ofpId": "12345_4",
      "dataKey": "journeyLog",
      "payload": { "blockOut": "1832Z", "takeoff": "1844Z" },
      "expectedVersion": 0
    }
  }'

curl -X POST "https://api.virtualperformancetool.com/api" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "flightDataSave",
    "data": {
      "ofpId": "12345_4",
      "dataKey": "journeyLog",
      "payload": { "blockOut": "1832Z", "takeoff": "1844Z", "landing": "2014Z" },
      "expectedVersion": 1,
      "lastDownloadedAt": "2026-05-27T19:14:22Z"
    }
  }'

{
  "success": true,
  "data": {
    "ofpId": "12345_4",
    "dataKey": "journeyLog",
    "payload": { "...": "echoed back" },
    "version": 2,
    "createdAt": "2026-05-27 18:02:11",
    "updatedAt": "2026-05-27 19:36:54",
    "createdByUserId": 9576,
    "updatedByUserId": 9576
  }
}

{
  "success": false,
  "error": {
    "message": "A newer version exists on the server.",
    "code": "VERSION_CONFLICT",
    "status": 409
  },
  "current": {
    "ofpId": "12345_4",
    "dataKey": "journeyLog",
    "payload": { "...": "server's current copy" },
    "version": 9,
    "createdAt": "2026-05-27 18:02:11",
    "updatedAt": "2026-05-27 19:31:08",
    "createdByUserId": 9576,
    "updatedByUserId": 9576
  }
}

flightDataDelete

Remove one (ofpId, dataKey). Returns 404 if no such row exists.

{
  "success": true,
  "ofpId": "12345_4",
  "dataKey": "journeyLog",
  "deleted": true
}

flightDataHistory

Read the append-only audit log of every change made through flightDataSave and flightDataDelete for one (ofpId, dataKey). Useful for showing “who changed what” in shared flights and for building an “undo last change” affordance on the client. Requires view access.

{
  "success": true,
  "ofpId": "12345_4",
  "dataKey": "journeyLog",
  "count": 3,
  "items": [
    { "id": 314, "version": 9, "changeType": "update", "payloadBytes": 4821,
      "changedAt": "2026-05-27 19:31:08", "changedByUserId": 11203 },
    { "id": 290, "version": 8, "changeType": "update", "payloadBytes": 4117,
      "changedAt": "2026-05-27 19:14:22", "changedByUserId": 9576  },
    { "id": 117, "version": 1, "changeType": "insert", "payloadBytes": 312,
      "changedAt": "2026-05-27 18:02:11", "changedByUserId": 9576  }
  ]
}

Error codes