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

# Stratos VA API

> The HTTP contract every Stratos desktop client speaks to your virtual airline's crew system. Framework-agnostic — implement it in any language or stack.

The contract every Stratos desktop client speaks to a virtual airline's crew system.

If you're running **phpVMS 7**, the easiest way to expose it is the open-source [stratos-core-api module](/guide/stratos-api/core) — drop the zip into your phpVMS install, enable it, and you're done.

If you're running **anything else** — Laravel, Django, Rails, Node, .NET, Go, a bespoke crew system — implement these endpoints in whatever stack you like, point your Stratos airline configuration at the base URL, and Stratos clients will treat it identically to the reference.

## Base URL

Every endpoint in this reference is documented under `/api/stratos` — that's what the phpVMS module uses and what we recommend for consistency. You're free to mount the surface anywhere; the desktop client just uses whatever base URL is set in your Stratos airline configuration.

So a VA running the reference module ends up with something like `https://crew.youva.com/api/stratos`, but `https://api.youva.com/stratos/v1` or `https://crew.youva.com/integrations/stratos` works equally well.

## Authentication

Most endpoints require a Bearer token — the pilot's API key, obtained via `POST /pilot/login` or your OAuth flow.

```http theme={null}
Authorization: Bearer <api_key>
```

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.

## The flight lifecycle

<Steps>
  <Step title="POST /flights/start">
    The pilot clicks **Start Flight** on a bid. The server prefiles a PIREP and returns a `tracking_id`.
  </Step>

  <Step title="POST /flights/update">
    Sent at the pilot's chosen position-update interval (currently 15, 30, or 60 seconds) while the flight is active. Each update writes a flight-path point and advances the PIREP status based on the reported phase.
  </Step>

  <Step title="POST /flights/complete">
    At gate arrival, the server files the PIREP, attaches log entries and comments, and submits it for VA approval.
  </Step>
</Steps>

`POST /flights/cancel` discards the in-progress PIREP at any point before completion. `POST /flights/unbook` is **unrelated** — it just removes a bid the pilot no longer wants to fly.

## Minimum viable surface

To get a Stratos client booking and flying, you need:

1. `GET /` — handshake.
2. `POST /pilot/login` — issue the pilot an API key.
3. `GET /pilot/verify` — token re-validation on app launch.
4. `GET /data/aircraft` and `GET /data/airports` — reference data.
5. `GET /flights/bookings` — the pilot's current bids.
6. `POST /flights/start`, `/update`, `/complete` — the flight lifecycle.

The rest (`/pilot/statistics`, `/data/announcements`, `/flights/search`, `/flights/cancel`, `/flights/unbook`) is needed for full feature parity but not for a basic round-trip.

## Reference implementation

The canonical implementation is the [phpVMS 7 module](https://github.com/SkyvexSoftware/stratos-core-api) — MIT-licensed, \~1000 lines of Laravel controllers. When this reference and the module disagree, the module wins; please [file an issue](https://github.com/SkyvexSoftware/stratos-core-api/issues) so we can fix the docs.

<CardGroup cols={2}>
  <Card title="phpVMS module" icon="github" href="https://github.com/SkyvexSoftware/stratos-core-api">
    Drop-in reference implementation for phpVMS 7.
  </Card>

  <Card title="Install guide" icon="book-open" href="/guide/stratos-api/core">
    Step-by-step install and configuration walkthrough.
  </Card>
</CardGroup>