> ## 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 Logbook API

> Install the Stratos Logbook API module on your phpVMS 7 install — adds the pilot flight history endpoints (list, detail, stats) the Stratos client uses for the in-app logbook.

The **Stratos Logbook API** is a phpVMS 7 module that exposes the pilot's flight history to the Stratos desktop client. It adds three endpoints — paginated list, single-PIREP detail with route and log timelines, and aggregate stats — and reads exclusively from phpVMS-native tables.

* **Repository:** [github.com/SkyvexSoftware/stratos-logbook-api](https://github.com/SkyvexSoftware/stratos-logbook-api)
* **Latest release:** [GitHub Releases](https://github.com/SkyvexSoftware/stratos-logbook-api/releases/latest)
* **License:** MIT
* **Depends on:** [Stratos Core API](/guide/stratos-api/core) (must be installed and enabled first)

## What it adds

The module mounts these endpoints under `/api/stratos/logbook` on your phpVMS install. All require a Bearer token — the same `users.api_key` Core uses, via Core's `StratosAuth` middleware.

```
GET    /api/stratos/logbook/pireps           paginated PIREP list
GET    /api/stratos/logbook/pireps/{id}      single PIREP detail with route + log
GET    /api/stratos/logbook/stats            aggregate stats
```

### `GET /pireps` — list

Paginated, sortable, searchable list of the authenticated pilot's PIREPs. Excludes in-progress flights, drafts, cancellations, and deleted records — only `PENDING`, `ACCEPTED`, and `REJECTED` states are returned.

Query parameters:

| Param    | Type      | Notes                                                                                                 |
| -------- | --------- | ----------------------------------------------------------------------------------------------------- |
| `limit`  | int 1–100 | Page size. Default 25.                                                                                |
| `offset` | int       | Page offset. Default 0.                                                                               |
| `sort`   | enum      | One of `date`, `route`, `aircraft`, `duration`, `distance`, `landing_rate`, `status`. Default `date`. |
| `order`  | enum      | `asc` or `desc`. Default `desc`.                                                                      |
| `q`      | string    | Free-text search across flight number, departure ICAO, and arrival ICAO.                              |
| `status` | enum      | Filter to a single state: `pending`, `accepted`, or `rejected`.                                       |

### `GET /pireps/{id}` — detail

A single PIREP scoped to the authenticated pilot (404s if the ID belongs to another pilot, or if the PIREP is still in progress). Includes the full polyline (`route`) sourced from the `acars` table's `FLIGHT_PATH` rows, and the log timeline (`log`) from the `LOG` rows.

### `GET /stats` — aggregate stats

Lifetime totals (sourced from the denormalised columns on `users.flights` and `users.flight_time`) plus computed slices (flights this month, hours this year, sum of accepted-flight distance, average landing rate, current rank).

## Install

<Steps>
  <Step title="Install Core first">
    If you haven't already, install [Stratos Core API](/guide/stratos-api/core) and verify the handshake endpoint responds. Logbook will refuse to load without it.
  </Step>

  <Step title="Download the Logbook module">
    Grab the latest `module.zip` from the [Logbook releases page](https://github.com/SkyvexSoftware/stratos-logbook-api/releases/latest).
  </Step>

  <Step title="Upload via the admin UI">
    In your phpVMS admin, navigate to **Admin → Modules → Add New Module** and upload the `module.zip`. phpVMS extracts it to `modules/StratosLogbook/`.
  </Step>

  <Step title="Enable the module">
    On the **Modules** list, find `StratosLogbook` and click **Enable**.
  </Step>

  <Step title="Clear caches">
    ```bash theme={null}
    php artisan optimize:clear
    ```
  </Step>

  <Step title="Verify">
    With a valid pilot `api_key` in hand:

    ```bash theme={null}
    curl -H "Authorization: Bearer <pilot_api_key>" \
      https://crew.youva.com/api/stratos/logbook/stats
    ```

    You should get a JSON response with `total_flights`, `hours_flown`, etc.
  </Step>
</Steps>

## What pilots see

Once Logbook is installed, the Stratos desktop client surfaces it automatically — there's no per-pilot configuration. Pilots get:

* A **Logbook** entry in the sidebar
* A scrollable, sortable list of every PIREP they've filed
* A detail view per PIREP with the route plotted on a map and the in-flight event log replayed
* A stats panel showing their lifetime totals and recent activity

The data comes straight from phpVMS — the same numbers you see in the pilot's profile in the phpVMS admin will appear in Stratos.

## What's excluded from the list

By design, the list endpoint **only returns historical states**:

* `PENDING` — filed but not yet reviewed by an admin
* `ACCEPTED` — approved
* `REJECTED` — rejected by an admin

The following are excluded and will not appear in the logbook even if rows exist in the `pireps` table:

* `IN_PROGRESS` — pilot is currently flying
* `PAUSED` — pilot has paused their flight
* `DRAFT` — never submitted
* `CANCELLED` — pilot cancelled mid-flight
* `DELETED` — soft-deleted

If a pilot reports a missing flight in their logbook, check its `state` in the `pireps` table first.

## Troubleshooting

### `Class not found` errors mentioning `Modules\StratosCore\...`

The Logbook module imports Core's `StratosAuth` middleware. If Core isn't installed and enabled, Logbook can't boot. Confirm via:

```bash theme={null}
php artisan module:list | grep -E "StratosCore|StratosLogbook"
```

Both should show as `Enabled`. If `StratosCore` isn't listed, install it before Logbook (see [Stratos Core API](/guide/stratos-api/core)).

### `/api/stratos/logbook/*` returns 404 but the module shows as enabled

Same fix as Core's equivalent issue — flush the route + module caches:

```bash theme={null}
php artisan route:clear
php artisan optimize:clear
```

### A pilot says their logbook is empty but they've filed PIREPs

The most likely cause is that all their existing PIREPs are still in `IN_PROGRESS` state (e.g. flights logged via an older ACARS tracker that never marked them as filed). Check:

```sql theme={null}
SELECT state, COUNT(*) FROM pireps WHERE user_id = <pilot_id> GROUP BY state;
```

States `0` (IN\_PROGRESS), `3` (CANCELLED), `4` (DELETED), `5` (DRAFT), `7` (PAUSED) won't appear. To bring them into the logbook, an admin can manually mark them as ACCEPTED in the phpVMS admin (Pilot → PIREPs → Edit).

## Updating

Same flow as Core: download the new `module.zip` from the releases page, upload via **Admin → Modules → Add New Module**, then run `php artisan optimize:clear`.

The current release ships zero migrations.

## Contributing

PRs against [SkyvexSoftware/stratos-logbook-api](https://github.com/SkyvexSoftware/stratos-logbook-api) welcome. Bug reports in [Issues](https://github.com/SkyvexSoftware/stratos-logbook-api/issues) — please include the phpVMS version, the Stratos client version, and a relevant snippet from `storage/logs/laravel.log`.