> ## Documentation Index > Fetch the complete documentation index at: https://docs.skyvexsoftware.com/llms.txt > Use this file to discover all available pages before exploring further. # Position and phase update > Sent by the desktop client at the pilot's chosen position-update interval (currently 15, 30, or 60 seconds) while a flight is active. Each call appends a FLIGHT_PATH point to the PIREP and updates the PIREP's status based on the reported `phase`. The server maps Stratos flight phases to phpVMS PIREP statuses: | Stratos phase | phpVMS status | |---|---| | `boarding` | BOARDING | | `push_back` | PUSHBACK_TOW | | `taxi` | TAXI | | `take_off` | TAKEOFF | | `rejected_take_off` | TAXI | | `climb` / `cruise` | ENROUTE | | `descent` | APPROACH | | `approach` | APPROACH_ICAO | | `final` | LANDING | | `landed` / `taxi_in` | LANDED | | `go_around` | APPROACH | | `arrived` / `deboarding` | ARRIVED | The first update that transitions into a takeoff/climb/cruise status sets `block_off_time`. The first update transitioning into `LANDED`/`ARRIVED` sets `block_on_time`. The server's running flight time is recomputed from the first ACARS row's `created_at` each update. Either `uuid` or `tracking_id` may carry the PIREP ID (the client uses them interchangeably). ## OpenAPI ````yaml /api-reference/openapi.json post /flights/update openapi: 3.1.0 info: title: Stratos Core API version: 0.3.0 summary: >- The Stratos VA API contract — auth, pilot identity, reference data, and the flight lifecycle. description: >- The contract every Stratos desktop client speaks to a virtual airline's crew system. The reference implementation is the open-source [stratos-core-api phpVMS 7 module](https://github.com/SkyvexSoftware/stratos-core-api), but any backend can implement these endpoints — they're framework-agnostic. Every endpoint in this reference is documented under `/api/stratos` — that's the convention the phpVMS module uses, and what we recommend for consistency. You're free to mount the surface anywhere you like; the desktop client just uses whatever base URL is set in your Stratos airline configuration. ## Authentication Most endpoints require a Bearer token — the pilot's API key, obtained via `POST /pilot/login` or your OAuth flow. Send as `Authorization: Bearer ` on every authenticated request. Public (no token): `GET /` and `POST /pilot/login`. ## Conventions - JSON, `snake_case` field names. - Distances in nautical miles, weights in pounds, flight times in decimal hours (unless suffixed `_minutes`). - Coordinates are decimal degrees (WGS84). - CORS is wide-open; the client preflights every method. servers: - url: '{baseUrl}' description: >- Your VA's Stratos API base — set this to whatever URL the Stratos client is pointed at, including any path prefix you chose to mount the surface under. variables: baseUrl: default: https://crew.example.com/api/stratos description: >- Full base URL including the path prefix (no trailing slash). The phpVMS reference module mounts under `/api/stratos`; if you mounted yours somewhere else (e.g. `https://api.youva.com/stratos/v1`), use that. security: - BearerAuth: [] tags: - name: Pilot description: Authentication, profile, and career statistics. - name: Reference Data description: Static lookup data the client renders in UI. - name: Flights description: >- Browse the schedule, manage bids, and run the active-flight lifecycle (start, update, complete, cancel). paths: /flights/update: post: tags: - Flights summary: Position and phase update description: >- Sent by the desktop client at the pilot's chosen position-update interval (currently 15, 30, or 60 seconds) while a flight is active. Each call appends a FLIGHT_PATH point to the PIREP and updates the PIREP's status based on the reported `phase`. The server maps Stratos flight phases to phpVMS PIREP statuses: | Stratos phase | phpVMS status | |---|---| | `boarding` | BOARDING | | `push_back` | PUSHBACK_TOW | | `taxi` | TAXI | | `take_off` | TAKEOFF | | `rejected_take_off` | TAXI | | `climb` / `cruise` | ENROUTE | | `descent` | APPROACH | | `approach` | APPROACH_ICAO | | `final` | LANDING | | `landed` / `taxi_in` | LANDED | | `go_around` | APPROACH | | `arrived` / `deboarding` | ARRIVED | The first update that transitions into a takeoff/climb/cruise status sets `block_off_time`. The first update transitioning into `LANDED`/`ARRIVED` sets `block_on_time`. The server's running flight time is recomputed from the first ACARS row's `created_at` each update. Either `uuid` or `tracking_id` may carry the PIREP ID (the client uses them interchangeably). operationId: updateFlight requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateFlightRequest' responses: '200': description: Update accepted. The reference implementation returns an empty body. content: application/json: schema: type: object nullable: true '400': $ref: '#/components/responses/MissingTrackingId' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/PirepNotFound' components: schemas: UpdateFlightRequest: type: object required: - phase - latitude - longitude - altitude - heading properties: uuid: type: string format: uuid description: >- PIREP ID returned by `/flights/start`. Use either this or `tracking_id`. tracking_id: type: string format: uuid description: Synonym for `uuid` — supplied for backwards compatibility. phase: $ref: '#/components/schemas/FlightPhase' latitude: type: number format: double minimum: -90 maximum: 90 longitude: type: number format: double minimum: -180 maximum: 180 altitude: type: number description: Indicated altitude in feet. heading: type: number format: float minimum: 0 maximum: 360 description: True heading in degrees. ground_speed: type: number format: float description: Ground speed in knots. Defaults to 0 if omitted. distance_remaining: type: number format: float description: >- Nautical miles remaining to destination. Used to compute the cumulative `distance` written to the FLIGHT_PATH row. FlightPhase: type: string enum: - boarding - push_back - taxi - take_off - rejected_take_off - climb - cruise - descent - approach - final - landed - go_around - taxi_in - arrived - deboarding description: >- Current flight phase. Unknown values are treated as `cruise` (PirepStatus::ENROUTE) by the reference implementation. Error: type: object properties: error: type: string success: type: boolean message: type: string responses: MissingTrackingId: description: Required `uuid` / `tracking_id` was not supplied. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: tracking_id is required Unauthorized: description: Missing or invalid Bearer token. content: application/json: schema: $ref: '#/components/schemas/Error' example: success: false error: Invalid Token PirepNotFound: description: No PIREP exists for the supplied tracking ID. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: PIREP not found securitySchemes: BearerAuth: type: http scheme: bearer description: >- The pilot's API key, obtained via `POST /pilot/login` or your OAuth flow. Send as `Authorization: Bearer ` on every authenticated request. ````