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

# Handshake — version and discovery

> Returns the implementing module's version, the handler name (always `Stratos`), and a link back to this documentation.

Used by the Stratos airline admin area to verify a newly-entered VA API base URL is reachable and speaking the Stratos contract — if the response shape matches and `handler` is `Stratos`, the setup is good.



## OpenAPI

````yaml /api-reference/openapi.json get /
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:
  /:
    get:
      summary: Handshake — version and discovery
      description: >-
        Returns the implementing module's version, the handler name (always
        `Stratos`), and a link back to this documentation.


        Used by the Stratos airline admin area to verify a newly-entered VA API
        base URL is reachable and speaking the Stratos contract — if the
        response shape matches and `handler` is `Stratos`, the setup is good.
      operationId: handshake
      responses:
        '200':
          description: Server is up and speaks the Stratos API.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandshakeResponse'
              examples:
                default:
                  value:
                    api_version: 0.2.3
                    handler: Stratos
      security: []
components:
  schemas:
    HandshakeResponse:
      type: object
      required:
        - api_version
        - handler
      properties:
        api_version:
          type: string
          description: Semver of the implementing module.
          example: 0.2.3
        handler:
          type: string
          description: Always `Stratos` — confirms the server speaks the Stratos contract.
          example: Stratos
  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.

````