# REST API documentation

Base path: `/api/v1`. All responses are JSON. The API has no live aircraft-tracking endpoints.

## Authentication and request rules

Create an API client/token in Integrations. A token is shown once and stored only as a hash. Send it as:

```http
Authorization: Bearer pams_<prefix>.<secret>
Accept: application/json
```

Tokens expire, may be revoked, inherit client IP restrictions and per-minute rate limits, and can use only granted scopes. Mutations require `Content-Type: application/json` and a unique `Idempotency-Key` of at most 160 characters. Reuse with the same method/path/body replays the prior response; reuse with different content returns 409.

Every response includes `X-Request-ID`. Errors use:

```json
{"error":{"status":422,"code":"validation_failed","message":"Validation message","request_id":"..."}}
```

Collection endpoints accept resource-supported filters plus `page` and a bounded page size. Records are always scoped to the token’s airline.

## Read endpoints

Each resource supports `GET /<resource>` and `GET /<resource>/{id}` with its `.read` scope:

| Resource | Scope |
|---|---|
| `aircraft` | `aircraft.read` |
| `aircraft-availability` | `availability.read` |
| `airports` | `airports.read` |
| `routes` | `routes.read` |
| `flight-schedules` | `schedules.read` |
| `flights`, `flight-statuses` | `flights.read` |
| `dispatch` | `dispatch.read` |
| `crew-assignments` | `crew.read` |
| `maintenance-schedules`, `maintenance-work-orders` | `maintenance.read` |
| `expenses` | `expenses.read` |
| `revenue` | `revenue.read` |
| `fuel`, `fuel-plans` | `fuel.read` |
| `alerts` | `alerts.read` |

## Mutation endpoints

| Method and path | Scope |
|---|---|
| `POST /flights`, `PUT /flights/{id}` | `flights.write` |
| `PATCH /flights/{id}/status` | `flights.status` |
| `PUT /flights/{id}/dispatch` | `dispatch.write` |
| `POST /crew-assignments` | `crew.write` |
| `POST /maintenance-schedules` | `maintenance.write` |
| `POST /maintenance-work-orders`, `PUT /maintenance-work-orders/{id}` | `maintenance.write` |
| `POST /expenses` | `expenses.write` |
| `POST /revenue`, `POST /revenue/{id}/payments` | `revenue.write` |
| `POST /fuel-plans`, `POST /fuel` | `fuel.write` |
| `PATCH /aircraft/{id}/status` | `aircraft.write` |
| `PATCH /alerts/{id}/acknowledge`, `/resolve` | `alerts.write` |

Mutation payloads use the same backend validation and permission/business services as server-rendered pages. Grounding, document expiry, schedule conflicts, approval restrictions, financial immutability, and tenant isolation therefore remain active.

## Webhooks

Outbound events include flight create/update/delay/cancel/complete, aircraft grounded, maintenance overdue, work-order complete, expense approved, and payment received. Destinations must be public HTTPS URLs without embedded credentials. Deliveries carry a signature generated with the endpoint secret; consumers must verify the raw body before parsing, deduplicate event/idempotency identifiers, return a 2xx status promptly, and process asynchronously. Failed deliveries retain attempt/failure history and support authorized replay.