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

# Safety Endpoints

> API reference for safety management endpoints: reports, investigations, CPAs, risk assessments, hazard notifications, and compliance.

The safety endpoints cover the Safety Management System (SMS) required by 14 CFR Part 5. They are split across two route groups:

* **`/api/v1/sms/*`** -- Report lifecycle, investigations, CPAs, evidence, AI triage, compliance, and metrics
* **`/api/v1/safety/*`** -- Risk assessments (SRM), risk controls, safety reports, hazard notifications, and audit log

All endpoints require authentication unless otherwise noted.

## SMS Reports

Manage safety reports (hazard, incident, near-miss, concern, observation, audit finding).

**Base path:** `/api/v1/sms/reports`

| Method  | Path           | Description              | Auth Required |
| ------- | -------------- | ------------------------ | :-----------: |
| `GET`   | `/reports`     | List reports (paginated) |      Yes      |
| `GET`   | `/reports/:id` | Get a single report      |      Yes      |
| `POST`  | `/reports`     | Create a new report      |      Yes      |
| `PATCH` | `/reports/:id` | Update a report          |      Yes      |

**Anonymous reporting** is available at `/api/v1/sms/public/anonymous-report` (no auth required, rate-limited to 10 requests per minute).

### List Reports

```bash theme={}
curl -X GET "https://api.planeconnection.com/api/v1/sms/reports?page=1&page_size=20&status=submitted" \
  -H "Authorization: Bearer $TOKEN"
```

### Update Report Status

```bash theme={}
curl -X PATCH "https://api.planeconnection.com/api/v1/sms/reports/rpt_abc123" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "under_review",
    "assignedTo": "user_xyz",
    "severity": "major"
  }'
```

Report statuses: `submitted`, `under_review`, `corrective_action`, `closed`

***

## Investigations

Manage safety investigations linked to reports.

**Base path:** `/api/v1/sms/investigations`

| Method  | Path                  | Description                     | Auth Required |
| ------- | --------------------- | ------------------------------- | :-----------: |
| `GET`   | `/investigations`     | List investigations (paginated) |      Yes      |
| `GET`   | `/investigations/:id` | Get a single investigation      |      Yes      |
| `POST`  | `/investigations`     | Create a new investigation      |      Yes      |
| `PATCH` | `/investigations/:id` | Update an investigation         |      Yes      |

### Create Investigation

```bash theme={}
curl -X POST "https://api.planeconnection.com/api/v1/sms/investigations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reportId": "rpt_abc123",
    "title": "Runway incursion investigation",
    "investigationType": "standard",
    "priority": "high",
    "leadInvestigatorId": "user_xyz"
  }'
```

**Investigation types:** `standard`, `full`, `rapid`

**Statuses:** `assigned`, `in_progress`, `pending_review`, `closed`, `cancelled`

**Update fields include:** `rootCause`, `contributingFactors`, `immediateActions`, `findings`, `recommendations`, `lessonsLearned`, `investigationMethod`, `findingSummary`

***

## Corrective and Preventive Actions (CPAs)

Manage CPAs generated from investigations or standalone.

**Base path:** `/api/v1/sms/cpas`

| Method  | Path        | Description           | Auth Required |
| ------- | ----------- | --------------------- | :-----------: |
| `GET`   | `/cpas`     | List CPAs (paginated) |      Yes      |
| `GET`   | `/cpas/:id` | Get a single CPA      |      Yes      |
| `POST`  | `/cpas`     | Create a new CPA      |      Yes      |
| `PATCH` | `/cpas/:id` | Update a CPA          |      Yes      |

### Create CPA

```bash theme={}
curl -X POST "https://api.planeconnection.com/api/v1/sms/cpas" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "investigationId": "inv_abc123",
    "cpaType": "corrective",
    "category": "Procedure",
    "title": "Update pre-flight checklist for runway inspection",
    "description": "Add mandatory runway surface condition check",
    "dueDate": "2026-04-15",
    "priority": "high"
  }'
```

**CPA types:** `corrective`, `preventive`

**Statuses:** `open`, `in_progress`, `completed`, `verified`, `cancelled`

**Verification fields:** `verifiedBy`, `verifiedAt`, `effectivenessRating`, `recurrenceCheckDate`

***

## Risk Assessments (SRM)

Manage Safety Risk Management assessments per 14 CFR 5.53.

**Base path:** `/api/v1/safety/risk-assessments`

| Method  | Path                    | Description                       | Auth Required |
| ------- | ----------------------- | --------------------------------- | :-----------: |
| `GET`   | `/risk-assessments`     | List risk assessments (paginated) |      Yes      |
| `GET`   | `/risk-assessments/:id` | Get a single risk assessment      |      Yes      |
| `POST`  | `/risk-assessments`     | Create a risk assessment          |      Yes      |
| `PATCH` | `/risk-assessments/:id` | Update a risk assessment          |      Yes      |

### Create Risk Assessment

```bash theme={}
curl -X POST "https://api.planeconnection.com/api/v1/safety/risk-assessments" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceType": "report",
    "sourceId": "rpt_abc123",
    "hazardDescription": "Deteriorating runway surface at KJFK",
    "hazardCategory": "Airfield",
    "severity": 4,
    "likelihood": "C",
    "riskLevel": "elevated",
    "riskScore": 12,
    "existingControls": "Visual inspection before each departure"
  }'
```

**Source types:** `report`, `investigation`, `audit`, `external`, `proactive`

**Severity:** `1` (negligible) to `5` (catastrophic)

**Likelihood:** `A` (frequent) through `E` (extremely improbable)

**Risk levels:** `minimal`, `low`, `moderate`, `elevated`, `high`

**Statuses:** `draft`, `active`, `mitigated`, `accepted`, `closed`

***

## Risk Controls

Manage controls linked to risk assessments per 14 CFR 5.55.

**Base path:** `/api/v1/safety/risk-controls`

| Method  | Path                 | Description                   | Auth Required |
| ------- | -------------------- | ----------------------------- | :-----------: |
| `GET`   | `/risk-controls`     | List controls for a workspace |      Yes      |
| `GET`   | `/risk-controls/:id` | Get a single control          |      Yes      |
| `POST`  | `/risk-controls`     | Create a risk control         |      Yes      |
| `PATCH` | `/risk-controls/:id` | Update a risk control         |      Yes      |

### Create Risk Control

```bash theme={}
curl -X POST "https://api.planeconnection.com/api/v1/safety/risk-controls" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "riskAssessmentId": "risk_abc123",
    "description": "Install automated surface condition monitoring system",
    "controlType": "engineering",
    "status": "proposed"
  }'
```

**Control types:** `engineering`, `administrative`, `ppe`, `training`, `procedure`

**Statuses:** `proposed`, `implementing`, `implemented`, `verified`

**Effectiveness:** `effective`, `partially_effective`, `ineffective`

***

## Hazard Notifications

Track notifications sent to external parties about identified hazards per 14 CFR 5.57.

**Base path:** `/api/v1/safety/hazard-notifications`

| Method  | Path                        | Description                    | Auth Required |
| ------- | --------------------------- | ------------------------------ | :-----------: |
| `GET`   | `/hazard-notifications`     | List notifications (paginated) |      Yes      |
| `GET`   | `/hazard-notifications/:id` | Get a single notification      |      Yes      |
| `POST`  | `/hazard-notifications`     | Create a notification          |      Yes      |
| `PATCH` | `/hazard-notifications/:id` | Update a notification          |      Yes      |

**Notified party types:** `certificate_holder`, `manufacturer`, `service_provider`, `regulator`, `other`

**Notification methods:** `email`, `letter`, `phone`, `in_person`, `electronic_system`, `other`

***

## Evidence Management

Upload and manage evidence files (photos, documents) attached to safety records.

**Base path:** `/api/v1/sms/evidence`

Evidence files are stored securely and can be attached to reports, investigations, and CPAs.

***

## SMS AI Triage

AI-powered analysis of safety data.

**Base path:** `/api/v1/sms/ai`

AI features include automated triage, trend analysis, and natural language report processing with semantic search capabilities.

***

## Compliance Tracking

Track SMS compliance items and generate Declaration of Compliance (DOC) documents.

**Base path:** `/api/v1/sms/compliance`

***

## Safety Metrics

Aggregate safety performance metrics and SPI tracking.

**Base path:** `/api/v1/sms/metrics`

***

## Safety Audit Log

An append-only audit trail of all safety record changes.

**Base path:** `/api/v1/safety/audit-log`

| Method | Path         | Description                            | Auth Required |
| ------ | ------------ | -------------------------------------- | :-----------: |
| `GET`  | `/audit-log` | List audit log entries for a workspace |      Yes      |

<Info>
  The safety audit log is append-only and cannot be modified or deleted, in compliance with 14 CFR
  5.97 (SMS records retention).
</Info>