Checklist Management API

Create, edit, delete and list user, virtual-airline and community-shared checklists, and let aircraft profiles reference any checklist — built-in or custom — by a single stable id.

Overview

A checklist is a titled set of challenge/response pages (see the Checklist JSON Format for the full schema). There are four kinds of checklists:

Concepts & Data Model

Every checklist — regardless of where it is stored — is identified by a single checklist id, the value that aircraft profiles reference (see Aircraft Profile Integration):

Fields

Storage Model & Unified Resolver

User, VA and community checklists are stored in the database (full JSON + metadata), keyed by a UUID checklistId. The built-in default checklists are deliberately not migrated into the database — they remain version-folder files (AcftChecklists/*.json), exactly like every other version-scoped asset in this API, so they stay git-authored, version-isolated, and fully backward-compatible with older clients.

What makes this "one way of handling it" despite the two storage locations is that every read — every endpoint below and the aircraft profile loader — goes through a single resolver function, and every write is validated by a single structure validator. Only the storage location differs; the code path does not.

VA & Admin Rules

VA checklist writes (checklistSave / checklistDelete with isVA: true) use the exact same admin gate as VA fleet management:

• VA-scoped admin (va_scope = VA_ONLY): can only manage checklists for their own virtual airline. vaName is optional; it must match their VA if provided.
• Full-scope admin / superadmin (va_scope = FULL): can manage any VA's checklists, but must pass vaName explicitly.

Regular users attempting isVA: true receive 403 FORBIDDEN. VA members who are not admins can read their VA's checklists but cannot edit or delete them.

Community Sharing & Ratings

Sharing is opt-in: a checklist only appears in communityChecklists when its owner sets shareCommunity: true. Community checklists (and every default checklist) can be rated 1–5 stars via checklistRate. Rules:

• You cannot rate a checklist you own.
• A non-shared user or VA checklist cannot be rated by anyone other than its owner — and owners cannot rate their own.
• Re-rating updates your existing rating rather than adding a duplicate (one rating per user per checklist).
• communityChecklists is sorted by average rating, then by rating count, so the best-rated shared checklists surface first.

checklistList

Return the authenticated user's checklists, their active VA's checklists, the community pool, and the built-in default checklists shipped with the active API version.

curl -X POST "https://api.virtualperformancetool.com/api" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "query": "checklistList" }'

{
  "success": true,
  "data": {
    "userChecklists": [
      {
        "checklist_id": "15c60bc5-57b9-47bd-af0f-f250f903798c",
        "name": "737-600W Custom",
        "version": "1.1",
        "share_community": 0,
        "ratingAverage": 0,
        "rating_count": 0,
        "isMine": true
      }
    ],
    "vaChecklists": [],
    "communityChecklists": [],
    "defaultChecklists": [
      {
        "file": "380_generic_checklist",
        "checklistId": "default:API_1_3_6:380_generic_checklist",
        "name": "380 Airbus Checklist",
        "description": "A generic checklist for the Airbus 380.",
        "version": "1.0",
        "ratingAverage": 0,
        "ratingCount": 0
      }
    ]
  }
}

checklistGet

Fetch one checklist by id — a database uuid, a default synthetic id, or (for back-compat) a bare default filename.

curl -X POST "https://api.virtualperformancetool.com/api" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "checklistGet",
    "data": { "checklistId": "default:API_1_3_6:380_generic_checklist" }
  }'

{
  "success": true,
  "data": {
    "checklistId": "default:API_1_3_6:380_generic_checklist",
    "name": "380 Airbus Checklist",
    "version": "1.0",
    "description": "A generic checklist for the Airbus 380.",
    "basedOn": null,
    "isDefault": true,
    "isMine": false,
    "shareCommunity": true,
    "ratingAverage": 0,
    "ratingCount": 0,
    "checklist": {
      "name": "380 Airbus Checklist",
      "checklists": [
        {
          "title": "BEFORE START",
          "order": 0,
          "items": [
            { "challenge": "SECURITY INSPECTION", "order": 0, "response": "COMPLETE (BOTH)", "isLine": false, "selfDetected": false, "note": null }
          ]
        }
      ]
    }
  }
}

checklistSave

Create a new checklist (omit checklistId) or update an existing one you own. The full checklist JSON is validated for structural integrity before being stored — see Checklist JSON Format.

curl -X POST "https://api.virtualperformancetool.com/api" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "checklistSave",
    "data": {
      "name": "737-600W Custom",
      "version": "1.1",
      "shareCommunity": false,
      "checklist": {
        "version": "1.1",
        "checklists": [
          {
            "title": "COCKPIT PREPARATION",
            "order": 0,
            "items": [
              { "challenge": "FUEL QUANTITY", "order": 0, "response": "___KG/LB" }
            ]
          }
        ]
      }
    }
  }'

{
  "success": true,
  "data": {
    "checklistId": "15c60bc5-57b9-47bd-af0f-f250f903798c",
    "saved": true
  }
}

checklistDelete

Remove a checklist you own (or, with isVA: true, one your VA owns). Also removes its ratings. Default checklists cannot be deleted — the request is rejected with READ_ONLY_DEFAULT.

curl -X POST "https://api.virtualperformancetool.com/api" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "checklistDelete",
    "data": { "checklistId": "15c60bc5-57b9-47bd-af0f-f250f903798c" }
  }'

{
  "success": true,
  "data": {
    "checklistId": "15c60bc5-57b9-47bd-af0f-f250f903798c",
    "deleted": true
  }
}

checklistRate

Rate a community-shared or default checklist 1–5 stars. Re-rating updates your existing rating.

curl -X POST "https://api.virtualperformancetool.com/api" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "checklistRate",
    "data": {
      "checklistId": "default:API_1_3_6:380_generic_checklist",
      "rating": 5
    }
  }'

{
  "success": true,
  "data": {
    "checklistId": "default:API_1_3_6:380_generic_checklist",
    "rating": 5,
    "ratingAverage": 5,
    "ratingCount": 1
  }
}

Aircraft Profile Integration

An aircraft profile's checklists block gains an optional checklistId field. When present, the performance API resolves it through the exact same unified resolver used by checklistGet, and populates checklists.data with the result:

{
  "checklists": {
    "isChecklistAvailable": true,
    "isChecklistActive": true,
    "checklistId": "15c60bc5-57b9-47bd-af0f-f250f903798c"
  }
}

When checklistId is omitted, profiles fall back to the legacy checklists.file field (a bare default filename) — existing profiles keep working unchanged.

Error Codes