openapi.json

{
  "openapi": "3.0.3",
  "info": {
    "title": "X-Plane Local Web API",
    "description": "Starting with version 12.1.1, X-Plane includes a built-in web server that provides a REST and WebSocket API for communicating with a running simulator instance.\n\nThis spec covers the **REST API** endpoints. For WebSocket message types, see the companion AsyncAPI spec.\n\nThe web server listens on `localhost:8086` by default. You can change the port with `--web_server_port=XXXX` when launching X-Plane. To disable the API entirely, set the network security policy to \"Disable Incoming Traffic\" in Settings > Network.\n\n**Note:** The `/api/capabilities` endpoint is unversioned (not under `/api/v3/`). All other endpoints are versioned under `/api/v3/`.\n\nThe web server is built on [Drogon](https://github.com/drogonframework/drogon) (C++). Requests to invalid paths return a default Drogon HTML 404 page, not JSON.\n\nFor more information, see the [official documentation](https://developer.x-plane.com/article/x-plane-web-api/).",
    "version": "3.0.0",
    "contact": {
      "name": "X-Plane Developer",
      "url": "https://developer.x-plane.com"
    }
  },
  "servers": [
    {
      "url": "http://localhost:8086/api/v3",
      "description": "X-Plane local web server (v3, default port)"
    }
  ],
  "tags": [
    {
      "name": "Capabilities",
      "description": "API version and X-Plane version information"
    },
    {
      "name": "Datarefs",
      "description": "Read and write simulator datarefs"
    },
    {
      "name": "Commands",
      "description": "List and activate simulator commands"
    },
    {
      "name": "Flight",
      "description": "Initialize or update a flight"
    }
  ],
  "paths": {
    "/capabilities": {
      "get": {
        "tags": ["Capabilities"],
        "summary": "Get API capabilities",
        "description": "Returns the supported API versions and the running X-Plane version.\n\n**Note:** This endpoint is unversioned. Use the `/api/capabilities` server, not `/api/v3/capabilities`.",
        "operationId": "getCapabilities",
        "servers": [
          {
            "url": "http://localhost:8086/api",
            "description": "Unversioned endpoint"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with API and X-Plane version info",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiCapabilities"
                },
                "example": {
                  "api": {
                    "versions": ["v1", "v2", "v3"]
                  },
                  "x-plane": {
                    "version": "12.4.0"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/datarefs": {
      "get": {
        "tags": ["Datarefs"],
        "summary": "List datarefs",
        "description": "Returns all registered datarefs in X-Plane at the moment of the request (both built-in and created by third parties). Supports filtering, pagination, and field selection.",
        "operationId": "listDatarefs",
        "parameters": [
          {
            "name": "filter[name]",
            "in": "query",
            "description": "Filter by exact dataref name. Repeatable — multiple values are joined with OR logic.",
            "schema": {
              "type": "string"
            },
            "example": "sim/time/zulu_time_sec"
          },
          {
            "name": "start",
            "in": "query",
            "description": "Index from where to start (inclusive, for pagination).",
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results to return (for pagination).",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "fields",
            "in": "query",
            "description": "Comma-separated list of fields to return per record. Available fields: `id`, `name`, `value_type`. Use `all` (default) to return all fields. Note: `is_writable` is always included automatically when present but cannot be used as a field selector.",
            "schema": {
              "type": "string",
              "default": "all"
            },
            "example": "id,name,value_type"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with array of datarefs",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Dataref"
                      }
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "id": 40003472032,
                      "is_writable": true,
                      "name": "sim/time/zulu_time_sec",
                      "value_type": "float"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "start_out_of_range": {
                    "value": {
                      "error_code": "start_out_of_range",
                      "error_message": "Start out of range"
                    }
                  },
                  "limit_out_of_range": {
                    "value": {
                      "error_code": "limit_out_of_range",
                      "error_message": "Limit out of range"
                    }
                  },
                  "invalid_field": {
                    "value": {
                      "error_code": "invalid_field",
                      "error_message": "Field name 'foo' does not exist"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Dataref name not found (when using filter[name])",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error_code": "invalid_dataref_name",
                  "error_message": "Dataref name 'foo' doesn't exist"
                }
              }
            }
          }
        }
      }
    },
    "/datarefs/count": {
      "get": {
        "tags": ["Datarefs"],
        "summary": "Get dataref count",
        "description": "Returns the number of registered datarefs in X-Plane at the moment (both built-in and created by third parties).",
        "operationId": "getDatarefCount",
        "responses": {
          "200": {
            "description": "Successful response with the dataref count",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "integer",
                      "description": "Total number of registered datarefs"
                    }
                  }
                },
                "example": {
                  "data": 7396
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/datarefs/{id}/value": {
      "get": {
        "tags": ["Datarefs"],
        "summary": "Get dataref value",
        "description": "Returns the current value of a dataref. For array datarefs, returns the full array or a single element if `index` is specified.\n\n**Note:** The official documentation shows a copy-pasted error table from List datarefs for this endpoint (with `start_out_of_range`, `limit_out_of_range`, etc.). The actual error codes for this endpoint are `index_out_of_range`, `not_an_array`, and `invalid_dataref_id`.",
        "operationId": "getDatarefValue",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Numeric ID of the dataref (obtained from List datarefs). This ID is stable within an X-Plane session but may change between sessions.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "index",
            "in": "query",
            "description": "Index to get on array datarefs.",
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with the dataref value. The value type depends on the dataref: a number for scalar datarefs, an array for array datarefs, or a base64 string for data datarefs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "The dataref value. Type depends on the dataref: number, array of numbers, or base64 string.",
                      "oneOf": [
                        { "type": "number" },
                        {
                          "type": "array",
                          "items": { "type": "number" }
                        },
                        { "type": "string" }
                      ]
                    }
                  }
                },
                "examples": {
                  "scalar": {
                    "summary": "Scalar value (float/double/int)",
                    "value": { "data": 43200.0 }
                  },
                  "array": {
                    "summary": "Array value (float_array/int_array)",
                    "value": { "data": [0.0, 0.0, 0.0, 0.0] }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "index_out_of_range": {
                    "value": {
                      "error_code": "index_out_of_range",
                      "error_message": "Dataref array index out of range"
                    }
                  },
                  "not_an_array": {
                    "value": {
                      "error_code": "not_an_array",
                      "error_message": "An index was provided but the dataref is not an array"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Dataref not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error_code": "invalid_dataref_id",
                  "error_message": "Dataref id 99999 doesn't exist"
                }
              }
            }
          }
        }
      },
      "patch": {
        "tags": ["Datarefs"],
        "summary": "Set dataref value",
        "description": "Set a dataref value. For array datarefs, you can set a specific index or the whole array at once (all values must be provided).",
        "operationId": "setDatarefValue",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Numeric ID of the dataref to update",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "index",
            "in": "query",
            "description": "Index to set on array datarefs.",
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["data"],
                "properties": {
                  "data": {
                    "description": "The value to set. A single number, an array of numbers, or a base64 encoded string.",
                    "oneOf": [
                      { "type": "number" },
                      {
                        "type": "array",
                        "items": { "type": "number" }
                      },
                      { "type": "string" }
                    ]
                  }
                }
              },
              "examples": {
                "scalar": {
                  "summary": "Set a scalar value",
                  "value": { "data": 43200 }
                },
                "array": {
                  "summary": "Set an entire array",
                  "value": { "data": [210, 220, 240] }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Value set successfully",
            "content": {
              "application/json": {
                "schema": {
                  "nullable": true,
                  "description": "Returns null on success"
                },
                "example": null
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "index_out_of_range": {
                    "value": {
                      "error_code": "index_out_of_range",
                      "error_message": "Dataref array index out of range"
                    }
                  },
                  "not_an_array": {
                    "value": {
                      "error_code": "not_an_array",
                      "error_message": "An index was provided but the dataref is not an array"
                    }
                  },
                  "incompatible_data": {
                    "value": {
                      "error_code": "incompatible_data",
                      "error_message": "Provided data is too much or not enough to set all elements of the dataref array, or sent an array to write to a non-array dataref."
                    }
                  },
                  "invalid_body": {
                    "value": {
                      "error_code": "invalid_body",
                      "error_message": "The request body is not valid JSON"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Dataref is read-only or incoming traffic is disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error_code": "dataref_is_readonly",
                  "error_message": "Attempted to write to a read-only dataref"
                }
              }
            }
          },
          "404": {
            "description": "Dataref not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error_code": "invalid_dataref_id",
                  "error_message": "Dataref id 99999 doesn't exist"
                }
              }
            }
          }
        }
      }
    },
    "/commands": {
      "get": {
        "tags": ["Commands"],
        "summary": "List commands",
        "description": "Returns all registered commands in X-Plane at the moment (built-in and third party). Supports filtering, pagination, and field selection. Introduced in API v2 (X-Plane 12.1.4+).",
        "operationId": "listCommands",
        "parameters": [
          {
            "name": "filter[name]",
            "in": "query",
            "description": "Filter by exact command name. Repeatable — multiple values are joined with OR logic.",
            "schema": {
              "type": "string"
            },
            "example": "sim/operation/pause"
          },
          {
            "name": "start",
            "in": "query",
            "description": "Index from where to start (inclusive, for pagination).",
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results to return (for pagination).",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "fields",
            "in": "query",
            "description": "Comma-separated list of fields to return per record. Available fields: `id`, `name`, `description`. Use `all` (default) to return all fields.",
            "schema": {
              "type": "string",
              "default": "all"
            },
            "example": "id,name"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with array of commands",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Command"
                      }
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "description": "Landing lights toggle.",
                      "id": 818,
                      "name": "sim/lights/landing_lights_toggle"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "start_out_of_range": {
                    "value": {
                      "error_code": "start_out_of_range",
                      "error_message": "Start out of range"
                    }
                  },
                  "limit_out_of_range": {
                    "value": {
                      "error_code": "limit_out_of_range",
                      "error_message": "Limit out of range"
                    }
                  },
                  "invalid_field": {
                    "value": {
                      "error_code": "invalid_field",
                      "error_message": "Field name 'foo' does not exist"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Command name not found (when using filter[name])",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error_code": "invalid_command_name",
                  "error_message": "Command name 'foo' doesn't exist"
                }
              }
            }
          }
        }
      }
    },
    "/commands/count": {
      "get": {
        "tags": ["Commands"],
        "summary": "Get command count",
        "description": "Returns the number of registered commands in X-Plane at the moment (built-in and third party). Introduced in API v2 (X-Plane 12.1.4+).",
        "operationId": "getCommandCount",
        "responses": {
          "200": {
            "description": "Successful response with the command count",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "integer",
                      "description": "Total number of registered commands"
                    }
                  }
                },
                "example": {
                  "data": 3171
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/command/{id}/activate": {
      "post": {
        "tags": ["Commands"],
        "summary": "Activate a command",
        "description": "Runs a command for a fixed duration. A zero duration triggers the command on and off immediately (like a button press). Maximum duration is 10 seconds.\n\nThis endpoint is intended for fire-and-forget commands (e.g., `sim/operation/pause`). For hardware integration or command up/down sequences, use the WebSocket interface instead.\n\nIntroduced in API v2 (X-Plane 12.1.4+).",
        "operationId": "activateCommand",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Numeric ID of the command to activate",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["duration"],
                "properties": {
                  "duration": {
                    "type": "number",
                    "format": "float",
                    "minimum": 0,
                    "maximum": 10,
                    "description": "Time in seconds after which the command will be deactivated. Use 0 for an immediate press-and-release."
                  }
                }
              },
              "examples": {
                "press_half_sec": {
                  "summary": "Press for half a second",
                  "value": { "duration": 0.5 }
                },
                "press_release": {
                  "summary": "Immediate press and release",
                  "value": { "duration": 0 }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Command activated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "nullable": true,
                  "description": "Returns null on success"
                },
                "example": null
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "invalid_body": {
                    "value": {
                      "error_code": "invalid_body",
                      "error_message": "The request body is not valid JSON"
                    }
                  },
                  "duration_out_of_range": {
                    "value": {
                      "error_code": "duration_out_of_range",
                      "error_message": "Duration is out of valid range"
                    }
                  },
                  "duration_missing": {
                    "value": {
                      "error_code": "duration_missing",
                      "error_message": "Duration parameter is missing"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Command not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error_code": "invalid_command_id",
                  "error_message": "Command id 99999 doesn't exist"
                }
              }
            }
          }
        }
      }
    },
    "/flight": {
      "post": {
        "tags": ["Flight"],
        "summary": "Start a flight",
        "description": "Starts a new flight with the specified configuration. Introduced in API v3 (X-Plane 12.4.0+).\n\nRequires: `aircraft` and exactly one start location key (`runway_start`, `ramp_start`, `lle_ground_start`, `lle_air_start`, or `boat_start`). All other keys are optional.\n\nSee the [Flight Initialization API documentation](https://developer.x-plane.com/article/flight-initialization-api/) for full details.",
        "operationId": "startFlight",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["data"],
                "properties": {
                  "data": {
                    "$ref": "#/components/schemas/FlightInit"
                  }
                }
              },
              "examples": {
                "minimal": {
                  "summary": "Minimal ramp start",
                  "value": {
                    "data": {
                      "ramp_start": {
                        "airport_id": "KPDX",
                        "ramp": "A1"
                      },
                      "aircraft": {
                        "path": "Aircraft/Laminar Research/Boeing 737-800/b738.acf"
                      }
                    }
                  }
                },
                "full": {
                  "summary": "Runway start with weather and time",
                  "value": {
                    "data": {
                      "runway_start": {
                        "airport_id": "KBOS",
                        "runway": "22L"
                      },
                      "aircraft": {
                        "path": "Aircraft/Laminar Research/Cessna 172SP/Cessna_172SP.acf",
                        "livery": "default"
                      },
                      "weight": {
                        "payload_weight_in_kilograms": [80, 80, 0, 0, 0, 0, 0, 0, 0],
                        "fueltank_weight_in_kilograms": [50, 50, 0, 0, 0, 0, 0, 0, 0]
                      },
                      "engine_status": {
                        "all_engines": { "running": true }
                      },
                      "local_time": {
                        "day_of_year": 150,
                        "time_in_24_hours": 14.5
                      },
                      "weather": {
                        "definition": "vfr_scattered",
                        "vertical_speed_in_thermal_in_feet_per_minute": 200,
                        "wave_height_in_meters": 1.5,
                        "wave_direction_in_degrees": 180,
                        "terrain_state": "dry",
                        "variation_across_region_percentage": 50,
                        "evolution_over_time_enum": "static"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Flight started successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FlightSuccessResponse"
                },
                "example": {
                  "error_code": "success"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "json_invalid_format": {
                    "value": {
                      "error_code": "json_invalid",
                      "error_message": "Failed to parse json, json format invalid"
                    }
                  },
                  "json_invalid_missing_keys": {
                    "value": {
                      "error_code": "json_invalid",
                      "error_message": "Provided json is invalid, to start a new flight both a start and an aircraft key must be present."
                    }
                  },
                  "missing_aircraft": {
                    "value": {
                      "error_code": "missing_aircraft",
                      "error_message": "Failed to parse aircraft_spec: no aircraft file found at path: fake.acf"
                    }
                  },
                  "missing_livery": {
                    "value": {
                      "error_code": "missing_livery",
                      "error_message": "Livery name doesn't exist"
                    }
                  },
                  "missing_scenery": {
                    "value": {
                      "error_code": "missing_scenery",
                      "error_message": "All or some scenery for the requested conditions is missing"
                    }
                  },
                  "missing_airport": {
                    "value": {
                      "error_code": "missing_airport",
                      "error_message": "Failed to parse ramp start, airport id 'XXXX' is not recognized"
                    }
                  },
                  "missing_ramp": {
                    "value": {
                      "error_code": "missing_ramp",
                      "error_message": "Specified ramp start not found"
                    }
                  },
                  "missing_runway": {
                    "value": {
                      "error_code": "missing_runway",
                      "error_message": "Specified runway not found"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      },
      "patch": {
        "tags": ["Flight"],
        "summary": "Update flight",
        "description": "Updates the current flight configuration. You cannot change the start location or aircraft during an update — these require starting a new flight. All keys are optional; omitted keys leave corresponding parameters unchanged. Introduced in API v3 (X-Plane 12.4.0+).\n\nSee the [Flight Initialization API documentation](https://developer.x-plane.com/article/flight-initialization-api/) for full details.",
        "operationId": "updateFlight",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["data"],
                "properties": {
                  "data": {
                    "type": "object",
                    "description": "Partial flight configuration update. All keys are optional. Cannot include start location or aircraft keys."
                  }
                }
              },
              "example": {
                "data": {
                  "local_time": {
                    "day_of_year": 100,
                    "time_in_24_hours": 15.9
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Flight updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FlightSuccessResponse"
                },
                "example": {
                  "error_code": "success"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "json_invalid": {
                    "value": {
                      "error_code": "json_invalid",
                      "error_message": "Failed to parse json, json format invalid"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Dataref": {
        "type": "object",
        "description": "Represents a dataref in the simulator. The `id` is stable within an X-Plane session but may change between sessions.",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64",
            "description": "Numeric identifier of the dataref for the current simulator session",
            "example": 40003472032
          },
          "name": {
            "type": "string",
            "description": "Fully qualified name of the dataref",
            "example": "sim/time/zulu_time_sec"
          },
          "value_type": {
            "type": "string",
            "description": "The data type of the dataref value",
            "enum": ["float", "double", "int", "int_array", "float_array", "data"],
            "example": "float"
          },
          "is_writable": {
            "type": "boolean",
            "description": "Whether this dataref can be written to",
            "example": false
          }
        }
      },
      "Command": {
        "type": "object",
        "description": "Represents a command in the simulator. The `id` is stable within an X-Plane session but may change between sessions.",
        "properties": {
          "id": {
            "type": "integer",
            "description": "Numeric identifier of the command for the current simulator session",
            "example": 818
          },
          "name": {
            "type": "string",
            "description": "Fully qualified name of the command",
            "example": "sim/lights/landing_lights_toggle"
          },
          "description": {
            "type": "string",
            "description": "Human-readable description of what the command does",
            "example": "Landing lights toggle."
          }
        }
      },
      "ApiCapabilities": {
        "type": "object",
        "description": "API version and X-Plane version information",
        "properties": {
          "api": {
            "type": "object",
            "properties": {
              "versions": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "List of supported API versions",
                "example": ["v1", "v2", "v3"]
              }
            }
          },
          "x-plane": {
            "type": "object",
            "properties": {
              "version": {
                "type": "string",
                "description": "Running X-Plane version",
                "example": "12.4.0"
              }
            }
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "description": "Error response returned when a request fails",
        "properties": {
          "error_code": {
            "type": "string",
            "description": "Machine-readable error code"
          },
          "error_message": {
            "type": "string",
            "description": "Human-readable error message"
          }
        }
      },
      "FlightSuccessResponse": {
        "type": "object",
        "description": "Success response returned by flight endpoints. Unlike other endpoints (which return `null`), flight endpoints return `{\"error_code\": \"success\"}`.",
        "properties": {
          "error_code": {
            "type": "string",
            "const": "success",
            "description": "Always \"success\" for successful flight operations"
          }
        }
      },
      "FlightInit": {
        "type": "object",
        "description": "Flight initialization structure. Requires `aircraft` and exactly one start location key. See the [Flight Initialization API docs](https://developer.x-plane.com/article/flight-initialization-api/) for full details.",
        "properties": {
          "aircraft": {
            "type": "object",
            "description": "Aircraft specification (required for new flights)",
            "required": ["path"],
            "properties": {
              "path": {
                "type": "string",
                "description": "Path to .acf file relative to X-Plane root directory",
                "example": "Aircraft/Laminar Research/Cessna 172SP/Cessna_172SP.acf"
              },
              "livery": {
                "type": "string",
                "description": "Name of livery subdirectory in the aircraft's liveries folder"
              }
            }
          },
          "runway_start": {
            "type": "object",
            "description": "Start on a runway. Cannot combine `final_distance_in_nautical_miles` with `tow_type`.",
            "required": ["airport_id", "runway"],
            "properties": {
              "airport_id": {
                "type": "string",
                "description": "Valid X-Plane airport ID"
              },
              "runway": {
                "type": "string",
                "description": "Runway ID at the specified airport"
              },
              "final_distance_in_nautical_miles": {
                "type": "number",
                "description": "If present, starts on final approach at this distance. Otherwise starts at runway threshold."
              },
              "tow_type": {
                "type": "string",
                "description": "Tow type for glider launch",
                "enum": ["tug", "winch", "none"],
                "default": "none"
              },
              "tow_aircraft": {
                "type": "object",
                "description": "Aircraft specification for tow plane. Required if tow_type is 'tug'.",
                "properties": {
                  "path": { "type": "string" }
                }
              }
            }
          },
          "ramp_start": {
            "type": "object",
            "description": "Start at an airport ramp/gate",
            "required": ["airport_id", "ramp"],
            "properties": {
              "airport_id": {
                "type": "string",
                "description": "Valid X-Plane airport ID",
                "example": "KPDX"
              },
              "ramp": {
                "type": "string",
                "description": "Name of the ramp start location",
                "example": "A1"
              }
            }
          },
          "lle_ground_start": {
            "type": "object",
            "description": "Start on the ground at a lat/lon/heading",
            "required": ["latitude", "longitude", "heading_true"],
            "properties": {
              "latitude": {
                "type": "number",
                "description": "Latitude in degrees (-90 to 90)"
              },
              "longitude": {
                "type": "number",
                "description": "Longitude in degrees (-180 to 180)"
              },
              "heading_true": {
                "type": "number",
                "description": "True heading in degrees (0 to 360)"
              }
            }
          },
          "lle_air_start": {
            "type": "object",
            "description": "Start in the air at a lat/lon/elevation. Must provide either `speed_in_meters_per_second` or `speed_enum`.",
            "required": ["latitude", "longitude", "elevation_in_meters", "heading_true"],
            "properties": {
              "latitude": {
                "type": "number",
                "description": "Latitude in degrees (-90 to 90)"
              },
              "longitude": {
                "type": "number",
                "description": "Longitude in degrees (-180 to 180)"
              },
              "elevation_in_meters": {
                "type": "number",
                "description": "Elevation MSL in meters"
              },
              "heading_true": {
                "type": "number",
                "description": "True heading in degrees (0 to 360)"
              },
              "speed_in_meters_per_second": {
                "type": "number",
                "description": "Speed in m/s (provide this OR speed_enum)"
              },
              "speed_enum": {
                "type": "string",
                "description": "Speed preset (provide this OR speed_in_meters_per_second)",
                "enum": ["short_field_approach", "normal_approach", "cruise"]
              },
              "pitch_in_degrees": {
                "type": "number",
                "description": "Aircraft pitch (default: 0)"
              }
            }
          },
          "boat_start": {
            "type": "object",
            "description": "Start on a carrier or frigate. Cannot combine `start_position` with `final_distance_in_nautical_miles`.",
            "required": ["boat_name"],
            "properties": {
              "boat_name": {
                "type": "string",
                "enum": ["carrier", "frigate"]
              },
              "start_position": {
                "type": "string",
                "description": "Deck position. Required for carrier deck starts. Not allowed with final_distance_in_nautical_miles.",
                "enum": ["catapult_1", "catapult_2", "catapult_3", "catapult_4", "deck"]
              },
              "boat_location": {
                "type": "object",
                "description": "Relocate the boat to this position",
                "properties": {
                  "latitude": { "type": "number" },
                  "longitude": { "type": "number" }
                }
              },
              "final_distance_in_nautical_miles": {
                "type": "number",
                "description": "Start on final approach at this distance"
              }
            }
          },
          "weight": {
            "type": "object",
            "description": "Weight and balance configuration",
            "properties": {
              "payload_weight_in_kilograms": {
                "type": "array",
                "items": { "type": "number" },
                "description": "Up to 9 payload station weights"
              },
              "fueltank_weight_in_kilograms": {
                "type": "array",
                "items": { "type": "number" },
                "description": "1-9 fuel tank weights in kilograms"
              },
              "jato_weight_in_kilograms": {
                "type": "number"
              },
              "slung_load": {
                "type": "object",
                "properties": {
                  "path_to_obj": { "type": "string" },
                  "weight_in_kilograms": { "type": "number" }
                }
              },
              "jettisonable_weight_in_kilograms": { "type": "number" },
              "shiftable_weight_in_kilograms": { "type": "number" },
              "deice_holdover_time_in_minutes": { "type": "number" },
              "oxygen_pressure_in_millibars": { "type": "number" },
              "deice_fluid_in_liters": { "type": "number" },
              "external_fueltank_weight_in_kilograms": {
                "type": "array",
                "items": { "type": "number" }
              }
            }
          },
          "engine_status": {
            "type": "object",
            "description": "Engine configuration",
            "properties": {
              "all_engines": {
                "type": "object",
                "properties": {
                  "running": {
                    "type": "boolean",
                    "description": "Whether all engines should be running"
                  }
                },
                "required": ["running"]
              }
            }
          },
          "weapons": {
            "type": "array",
            "description": "Weapon loadout specifications",
            "items": {
              "type": "object",
              "required": ["index", "filename"],
              "properties": {
                "index": {
                  "type": "integer",
                  "description": "Hardpoint index from Plane Maker"
                },
                "filename": {
                  "type": "string",
                  "description": "Name of .wpn file"
                }
              }
            }
          },
          "failures": {
            "type": "object",
            "description": "System failure configuration",
            "properties": {
              "fix_everything": {
                "type": "boolean",
                "description": "Fix all systems before applying new failures (default: true)"
              },
              "mean_time_between_failures_in_hours": {
                "type": "number",
                "description": "MTBF for random failures (0 = disabled)"
              },
              "operation_failures": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": ["name", "status"],
                  "properties": {
                    "name": {
                      "type": "string",
                      "description": "Failure system name"
                    },
                    "status": {
                      "type": "string",
                      "enum": ["always_work", "fail_mean_time_in_hours", "fail_exact_time_in_hours", "fail_at_speed_in_knots", "fail_at_altitude_in_feet", "fail_at_command_trigger", "inoperative"]
                    },
                    "value": {
                      "type": "number",
                      "description": "Required for time/speed/altitude failure types"
                    }
                  }
                }
              }
            }
          },
          "ai_aircraft": {
            "type": "array",
            "description": "AI aircraft specifications",
            "items": {
              "type": "object",
              "required": ["aircraft", "mission"],
              "properties": {
                "aircraft": {
                  "type": "object",
                  "properties": {
                    "path": { "type": "string" }
                  }
                },
                "mission": {
                  "type": "string",
                  "enum": ["atc", "combat_team_red", "combat_team_blue", "combat_team_green", "combat_team_gold"]
                }
              }
            }
          },
          "formation_aircraft": {
            "type": "object",
            "description": "AI aircraft for formation flying",
            "properties": {
              "path": {
                "type": "string",
                "description": "Path to .acf file"
              }
            }
          },
          "incursion": {
            "type": "object",
            "description": "Runway incursion configuration",
            "properties": {
              "aircraft": {
                "type": "object",
                "properties": {
                  "path": { "type": "string" }
                }
              },
              "type": {
                "type": "string",
                "enum": ["flight_incursion", "runway_incursion_arm", "runway_incursion_execute", "clear_incursion"]
              }
            }
          },
          "use_system_time": {
            "type": "boolean",
            "description": "Use system time. Mutually exclusive with local_time, gmt_time, and time_enum."
          },
          "local_time": {
            "type": "object",
            "description": "Set local time. Mutually exclusive with use_system_time, gmt_time, and time_enum.",
            "required": ["day_of_year", "time_in_24_hours"],
            "properties": {
              "day_of_year": {
                "type": "integer",
                "description": "Day of year (0 = January 1)"
              },
              "time_in_24_hours": {
                "type": "number",
                "description": "Time of day in hours (e.g. 13.5 = 1:30 PM)"
              }
            }
          },
          "gmt_time": {
            "type": "object",
            "description": "Set GMT time. Mutually exclusive with use_system_time, local_time, and time_enum.",
            "required": ["day_of_year", "time_in_24_hours"],
            "properties": {
              "day_of_year": {
                "type": "integer",
                "description": "Day of year (0 = January 1)"
              },
              "time_in_24_hours": {
                "type": "number",
                "description": "Time of day in hours (e.g. 13.5 = 1:30 PM)"
              }
            }
          },
          "time_enum": {
            "type": "string",
            "description": "Time preset. Mutually exclusive with use_system_time, local_time, and gmt_time.",
            "enum": ["day", "sunset", "evening", "night"]
          },
          "weather": {
            "description": "Weather configuration. Either the string `\"use_real_weather\"` or a weather definition object.",
            "oneOf": [
              {
                "type": "string",
                "const": "use_real_weather"
              },
              {
                "type": "object",
                "description": "Weather scenario definition",
                "required": ["definition", "vertical_speed_in_thermal_in_feet_per_minute", "wave_height_in_meters", "wave_direction_in_degrees", "terrain_state", "variation_across_region_percentage", "evolution_over_time_enum"],
                "properties": {
                  "definition": {
                    "description": "Weather preset name or custom weather definition object",
                    "oneOf": [
                      {
                        "type": "string",
                        "enum": ["vfr_few_clouds", "vfr_scattered", "vfr_broken", "marginal_vfr_overcast", "ifr_non_precision", "ifr_precision", "convective", "large_cell_thunderstorm"]
                      },
                      {
                        "type": "object",
                        "description": "Custom weather definition",
                        "required": ["latitude_in_degrees", "longitude_in_degrees", "elevation_in_meters", "visibility_in_kilometers"],
                        "properties": {
                          "latitude_in_degrees": { "type": "number" },
                          "longitude_in_degrees": { "type": "number" },
                          "elevation_in_meters": { "type": "number" },
                          "visibility_in_kilometers": { "type": "number" },
                          "temperature_in_degrees_celsius": { "type": "number" },
                          "altimeter_setting_in_hpa": { "type": "number" },
                          "precipitation_ratio": { "type": "number", "minimum": 0, "maximum": 1 },
                          "clouds": {
                            "type": "array",
                            "maxItems": 3,
                            "items": {
                              "type": "object",
                              "required": ["type", "cover_ratio", "bases_in_feet_msl", "tops_in_feet_msl"],
                              "properties": {
                                "type": { "type": "string", "enum": ["cirrus", "stratus", "cumulus", "cumulunimbus"] },
                                "cover_ratio": { "type": "number", "minimum": 0, "maximum": 1 },
                                "bases_in_feet_msl": { "type": "number" },
                                "tops_in_feet_msl": { "type": "number" }
                              }
                            }
                          },
                          "wind": {
                            "type": "array",
                            "maxItems": 13,
                            "items": {
                              "type": "object",
                              "required": ["altitude_in_feet_msl", "speed_in_knots", "direction_in_degrees_true"],
                              "properties": {
                                "altitude_in_feet_msl": { "type": "number" },
                                "speed_in_knots": { "type": "number" },
                                "direction_in_degrees_true": { "type": "number" },
                                "gust_increase_in_knots": { "type": "number" },
                                "shear_in_degrees": { "type": "number" },
                                "turbulence_ratio": { "type": "number", "minimum": 0, "maximum": 1 }
                              }
                            }
                          }
                        }
                      }
                    ]
                  },
                  "vertical_speed_in_thermal_in_feet_per_minute": { "type": "number" },
                  "wave_height_in_meters": { "type": "number" },
                  "wave_direction_in_degrees": { "type": "number", "description": "True heading" },
                  "terrain_state": {
                    "type": "string",
                    "enum": ["dry", "lightly_wet", "medium_wet", "very_wet", "lightly_puddly", "medium_puddly", "very_puddly", "lightly_snowy", "medium_snowy", "very_snowy", "lightly_icy", "medium_icy", "very_icy", "lightly_snowy_and_icy", "medium_snowy_and_icy", "very_snowy_and_icy"]
                  },
                  "variation_across_region_percentage": { "type": "number" },
                  "evolution_over_time_enum": {
                    "type": "string",
                    "enum": ["rapidly_improving", "improving", "gradually_improving", "static", "gradually_deteriorating", "deteriorating", "rapidly_deteriorating"]
                  }
                }
              }
            ]
          }
        }
      }
    },
    "responses": {
      "Forbidden": {
        "description": "Incoming traffic is disabled in X-Plane Settings > Network"
      }
    }
  }
}