API Overview

The PlaneConnection API is a RESTful JSON API that provides programmatic access to safety management, flight operations, FBO management, and platform administration features.

Base URLs

All API requests use the base URL for your environment:

Environment	Base URL
Production	`https://api.planeconnection.com`

All versioned endpoints are mounted under /api/v1. For example, the full URL for listing safety reports in production is:

https://api.planeconnection.com/api/v1/sms/reports

Versioning

The API uses URL-based versioning. The current and only version is v1. All endpoints are prefixed with /api/v1/.

Authentication

Most endpoints require authentication. The API supports two authentication methods:

JWT tokens — passed as a Bearer token in the Authorization header or via the session cookie.
API keys — passed in the X-API-Key header for service-to-service calls.

See Authentication for full details.

Tenant Context

PlaneConnection is a multi-tenant platform. Tenant context is provided via headers set by the application router:

Header	Description
`X-Tenant-Id`	Workspace UUID
`X-Tenant-Slug`	URL-safe workspace identifier
`X-Tenant-Name`	Human-readable workspace name
`X-Tenant-Timezone`	IANA timezone (e.g., `America/New_York`)
`X-Tenant-Modules`	Comma-separated list of enabled modules

All data operations are scoped to the authenticated user’s workspace. You cannot access data belonging to another workspace.

Request Format

Content-Type: application/json for all request bodies
HTTP Methods: GET, POST, PUT, PATCH, DELETE
Query parameters: Use snake_case (e.g., page_size, date_from)
Request bodies: Use camelCase (e.g., tailNumber, riskScore)

Response Format

All responses follow a consistent JSON envelope:

Success
Single Resource
Error

{
  "success": true,
  "data": {
    "items": [...],
    "total": 42,
    "page": 1,
    "per_page": 20,
    "total_pages": 3
  }
}

{
  "success": true,
  "data": {
    "id": "risk_abc123",
    "hazardDescription": "Deteriorating runway surface",
    "severity": 4,
    "createdAt": "2026-03-15T10:30:00Z"
  }
}

{
  "error": "Not found",
  "code": "NOT_FOUND",
  "requestId": "req_a1b2c3d4"
}

Pagination

List endpoints support cursor-based pagination with these query parameters:

Parameter	Type	Default	Description
`page`	integer	`1`	Page number (1-indexed)
`page_size`	integer	`20`	Items per page (max 100)

Paginated responses include total, page, per_page, and total_pages fields in the data envelope.

Rate Limits

Rate limits are enforced per client IP address using a sliding window algorithm:

Scope	Window	Max Requests
Auth endpoints (`/auth/*`)	1 minute	20
Anonymous report	1 minute	10
Signup session	1 hour	10
All other endpoints	1 minute	300

When rate-limited, the API returns a 429 Too Many Requests response.

These are application-layer limits. Additional distributed rate limiting provides protection in production.

Health Checks

Two health endpoints are available without authentication:

Endpoint	Description
`GET /health`	Shallow liveness probe — returns `{"status": "ok"}`
`GET /readiness`	Deep readiness probe — checks database and storage connectivity

curl https://api.planeconnection.com/health

{ "status": "ok" }

API Documentation

The API also serves interactive documentation:

URL	Format
`/`	Scalar interactive API explorer
`/docs`	Scalar (alias)
`/llms.txt`	LLM-optimized plain-text documentation
`/api/openapi.json`	OpenAPI 3.x specification

CORS

The API supports Cross-Origin Resource Sharing (CORS) for browser-based clients. Allowed methods are GET, POST, PUT, PATCH, DELETE, and OPTIONS. CORS preflight responses are cached for 24 hours. Allowed origins include:

Configured allowed origins for your deployment
PlaneConnection domain patterns (*.planeconnection.com)

Security Headers

All responses include these security headers:

Header	Value
`Strict-Transport-Security`	`max-age=31536000; includeSubDomains`
`X-Content-Type-Options`	`nosniff`
`X-Frame-Options`	`DENY`
`X-XSS-Protection`	`1; mode=block`

Request Tracing

Every response includes an x-request-id header for tracing. If you include an X-Request-Id header in your request, the API will echo it back. Otherwise, a UUID is generated automatically.

Authentication

JWT tokens, API keys, and service auth

Error Codes

Error response format and troubleshooting

Safety Endpoints

Reports, investigations, CPAs, risk assessments

Ops Endpoints

Trips, fleet, crew, dispatch

SMS Reference

SmartScore

Operations Reference

FBO Reference

Maintenance Reference

Operational Reports

Portal Reference

Platform Reference

API Reference

Base URLs

Versioning

Authentication

Tenant Context

Request Format

Response Format

Rate Limits

Health Checks

API Documentation

CORS

Security Headers

Request Tracing

Authentication

Error Codes

Safety Endpoints

Ops Endpoints

​Base URLs

​Versioning

​Authentication

​Tenant Context

​Request Format

​Response Format

​Pagination

​Rate Limits

​Health Checks

​API Documentation

​CORS

​Security Headers

​Request Tracing

Authentication

Error Codes

Safety Endpoints

Ops Endpoints

Base URLs

Versioning

Authentication

Tenant Context

Request Format

Response Format

Pagination

Rate Limits

Health Checks

API Documentation

CORS

Security Headers

Request Tracing