> ## 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.

# Begin tracking a booked flight

> Prefiles a PIREP for the chosen bid and returns a `tracking_id` (the new PIREP's UUID) that subsequent `/flights/update` and `/flights/complete` calls reference.

If `bid_id` is omitted, the phpVMS reference implementation falls back to the pilot's most recent bid — this exists for older client builds that send an empty body. New integrations should always send `bid_id`.

Aircraft selection priority on the server:
1. SimBrief-attached aircraft (if the pilot has a SimBrief OFP for this flight)
2. The bid's `aircraft_id` (if the bid was made against a specific airframe)
3. The first available aircraft from the flight's subfleets

If none can be resolved, the server returns 500 with `"No aircraft attached to bid"`.



## OpenAPI

````yaml /api-reference/openapi.json post /flights/start
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
    <api_key>` 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/start:
    post:
      tags:
        - Flights
      summary: Begin tracking a booked flight
      description: >-
        Prefiles a PIREP for the chosen bid and returns a `tracking_id` (the new
        PIREP's UUID) that subsequent `/flights/update` and `/flights/complete`
        calls reference.


        If `bid_id` is omitted, the phpVMS reference implementation falls back
        to the pilot's most recent bid — this exists for older client builds
        that send an empty body. New integrations should always send `bid_id`.


        Aircraft selection priority on the server:

        1. SimBrief-attached aircraft (if the pilot has a SimBrief OFP for this
        flight)

        2. The bid's `aircraft_id` (if the bid was made against a specific
        airframe)

        3. The first available aircraft from the flight's subfleets


        If none can be resolved, the server returns 500 with `"No aircraft
        attached to bid"`.
      operationId: startFlight
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartFlightRequest'
      responses:
        '200':
          description: PIREP prefiled. Use `tracking_id` on subsequent flight calls.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartFlightResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  schemas:
    StartFlightRequest:
      type: object
      properties:
        bid_id:
          type: integer
          description: >-
            Bid to start flying. Omit to fall back to the pilot's most recent
            bid (legacy behaviour).
    StartFlightResponse:
      type: object
      required:
        - tracking_id
      properties:
        tracking_id:
          type: string
          format: uuid
          description: >-
            PIREP UUID. Send this back as `uuid` or `tracking_id` on
            `/flights/update`, `/flights/complete`, and `/flights/cancel`.
    Error:
      type: object
      properties:
        error:
          type: string
        success:
          type: boolean
        message:
          type: string
  responses:
    Unauthorized:
      description: Missing or invalid Bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error: Invalid Token
    ServerError:
      description: >-
        Unhandled server error. The `error` field carries the message; check
        server logs for the trace.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  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 <api_key>` on every authenticated
        request.

````