> ## Documentation Index
> Fetch the complete documentation index at: https://docs.planeconnection.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> Base URLs, authentication, versioning, rate limits, and response format for the PlaneConnection REST API.

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:

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

See [Authentication](/en/reference/api/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:

<Tabs>
  <Tab title="Success">
    ```json theme={}
    {
      "success": true,
      "data": {
        "items": [...],
        "total": 42,
        "page": 1,
        "per_page": 20,
        "total_pages": 3
      }
    }
    ```
  </Tab>

  <Tab title="Single Resource">
    ```json theme={}
    {
      "success": true,
      "data": {
        "id": "risk_abc123",
        "hazardDescription": "Deteriorating runway surface",
        "severity": 4,
        "createdAt": "2026-03-15T10:30:00Z"
      }
    }
    ```
  </Tab>

  <Tab title="Error">
    ```json theme={}
    {
      "error": "Not found",
      "code": "NOT_FOUND",
      "requestId": "req_a1b2c3d4"
    }
    ```
  </Tab>
</Tabs>

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

<Warning>
  These are application-layer limits. Additional distributed rate limiting provides protection in
  production.
</Warning>

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

```bash theme={}
curl https://api.planeconnection.com/health
```

```json theme={}
{ "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.

<CardGroup cols={2}>
  <Card title="Authentication" icon="lock" href="/en/reference/api/authentication">
    JWT tokens, API keys, and service auth
  </Card>

  <Card title="Error Codes" icon="circle-exclamation" href="/en/reference/api/errors">
    Error response format and troubleshooting
  </Card>

  <Card title="Safety Endpoints" icon="shield" href="/en/reference/api/safety-endpoints">
    Reports, investigations, CPAs, risk assessments
  </Card>

  <Card title="Ops Endpoints" icon="plane" href="/en/reference/api/ops-endpoints">
    Trips, fleet, crew, dispatch
  </Card>
</CardGroup>