# Welcome to the TrueFlight External API

This portal documents TrueFlight’s machine-to-machine HTTP API for flight schools and training organizations. Use it to sync schedules, CRM data, maintenance, training (LMS), and billing-adjacent reads with your own systems, data warehouse, or partner tools.

The API reference in this site is generated from the same OpenAPI document linked below. Responses use JSON with a `data` envelope where noted; field names in payloads are snake_case, matching the live implementation.

## Who this is for

You are building a server-side integration (cron jobs, ETL, middleware, or a trusted backend), not a browser client. All routes live under `/api/external/v1` on your TrueFlight deployment host—the same hostname you use for the web application. (Default is: `https://trueflight.app`)

## Getting started

1. Create an API key in the TrueFlight web app under Settings → Developer API. Keys are shown once; store them in a secret manager.
2. Call the API with the header:
`Authorization: Bearer <your_api_key>`
Keys are prefixed (for example `tf_live_…`) so you can tell environment and type at a glance.
3. Check connectivity with `GET /health` (no auth required), then `GET /me` to confirm organization, allowed locations, and key scopes.
4. Respect scopes: read-only operations use read scope; create, update, and delete operations require write scope. The reference marks each operation accordingly.
5. Location context: many resources are scoped to an organization and optionally a location. Location-scoped keys behave predictably; org-wide keys often require a `location_id` query parameter where the resource is per-base. Details are in each operation’s description.


## What you can integrate

The current surface includes, subject to your plan and permissions:

- Identity and ops — Health and caller context (`/me`, including location list where applicable).
- Schedule — Reservations (read and limited update where documented), aircraft, simulators, reservation types, instructors.
- CRM and billing reads — Companies (customers), invoices, read-only payments for reconciliation.
- Maintenance — Squawks, maintenance reminders, and work orders.
- LMS — Courses, enrollments, exams, and exam attempts (including grading updates where documented).
- Read-only depth — Document templates and instances, store orders, contracts, discovery flight products—useful for reporting and portals without mutating regulated flows here.


For every shipped route, the [OpenAPI 3.1 description](/tf-docs) is the contract. Download it for codegen, contract tests, or importing into Postman, Insomnia, or your API gateway.

## Webhooks

TrueFlight can POST event payloads to HTTPS endpoints you configure. Each delivery includes headers such as `x-tf-signature`, `x-tf-timestamp`, and `x-tf-delivery-id`.

Verify authenticity by computing HMAC-SHA256 over the canonical string `timestamp.deliveryId.rawBody` (using your endpoint’s signing secret, as shown once when the endpoint is created) and comparing to the hex signature in `x-tf-signature`. Treat verification failures as non-retryable for that payload until you fix configuration.

Event types and payload shapes are summarized in the OpenAPI `info.description` and in the reference; user lifecycle events (invites, acceptances, archive status) are documented there with field notes.

## Errors and stability

Errors follow a consistent problem style (HTTP status plus a machine-readable `type` and human-readable `detail` where applicable). Prefer idempotent retries on `5xx` and transient network failures with backoff. Do not log full API keys or webhook signing secrets.

## OpenAPI file in this folder

The [OpenAPI description](/tf-docs) is the file this site uses to build the reference and link checker targets in this bundle. It is maintained in lockstep with the application so it is always up-to-date.