Base URL

All API requests are served from your airline’s private deployment:

https://api.rectifai.yourdomain.com/v1

Note: Each airline operates its own fully sovereign instance. No data leaves your infrastructure.

---

Authentication

rectifAI API uses JWT Bearer tokens for authentication. Tokens are issued per user session and include role-based access control (RBAC) claims.

Token Request

POST /v1/auth/token
Content-Type: application/json

{
  "username": "mcc.controller@airline.com",
  "password": "<secure-password>",
  "grant_type": "password"
}

Response

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rt_8x9y2k...",
  "scope": "controller.read controller.write audit.read"
}

---

Common Headers

Include these headers in all authenticated requests:

Header	Value	Required
Authorization	Bearer <token>	Required
Content-Type	application/json	Required
X-Request-ID	Unique UUID for tracing	Optional
X-Idempotency-Key	UUID for idempotent writes	Optional

---

Response Envelope

All API responses follow a consistent envelope structure:

{
  "status": "success",
  "data": { ... },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2025-11-04T12:34:56Z",
    "version": "1.0"
  }
}

---

Error Codes

rectifAI uses standard HTTP status codes and structured error responses:

Code	Status	Description
200	OK	Request succeeded
201	Created	Resource created successfully
400	Bad Request	Invalid request parameters
401	Unauthorized	Missing or invalid authentication
403	Forbidden	Insufficient permissions
404	Not Found	Resource does not exist
409	Conflict	Resource state conflict
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Unexpected server error

Error Response Format

{
  "status": "error",
  "error": {
    "code": "INVALID_MEL_REFERENCE",
    "message": "MEL item 34-11-01 not found for aircraft type B737-800",
    "details": {
      "aircraft_type": "B737-800",
      "mel_reference": "34-11-01"
    }
  },
  "meta": {
    "request_id": "req_xyz789",
    "timestamp": "2025-11-04T12:34:56Z"
  }
}

---

Pagination

List endpoints support cursor-based pagination for efficient traversal of large datasets:

GET /v1/controller/events?cursor=eyJpZCI6MTIzfQ&limit=50

Pagination Response

{
  "status": "success",
  "data": [...],
  "pagination": {
    "has_more": true,
    "next_cursor": "eyJpZCI6MTczfQ",
    "count": 50
  }
}

---

AI Controller Endpoints

The AI Controller Layer provides autonomous reasoning, MEL verification, and reliability analysis.

Example Request

curl -X GET "$BASE/v1/controller/verify-mel?aircraft_reg=N12345&ata=34-11-01&flight_type=ETOPS" \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "status": "success",
  "data": {
    "mel_applicable": true,
    "mel_category": "B",
    "restrictions": [
      "Flight in icing conditions prohibited",
      "Max flight duration: 3 days"
    ],
    "expiry": "2025-11-07T12:00:00Z",
    "confidence": 0.98,
    "reasoning": "MEL 34-11-01 permits dispatch with inoperative anti-ice valve under Category B..."
  }
}

curl -X GET "$BASE/v1/controller/recurrence-check?ata=32-41&lookback_days=30" \
  -H "Authorization: Bearer $TOKEN"

curl -X POST "$BASE/v1/controller/decision" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "scenario": "aog_recovery",
    "aircraft_reg": "N67890",
    "defect_code": "79-31-00",
    "context": {
      "station": "KJFK",
      "scheduled_departure": "2025-11-04T18:00:00Z",
      "part_availability": "remote_warehouse"
    }
  }'

---

Conversational Interface

Natural language interface powered by LLM reasoning. Supports Server-Sent Events (SSE) for streaming responses.

Example Request (Streaming)

curl -X POST "$BASE/v1/chat/completions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: text/event-stream" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What is the MEL status for N12345 right now?"
      }
    ],
    "stream": true
  }'

SSE Response Stream

event: message
data: {"delta": "Aircraft N12345 currently has ", "done": false}

event: message
data: {"delta": "2 active MEL items:\n", "done": false}

event: message
data: {"delta": "1. MEL 34-11-01 (Category B) - expires 2025-11-07\n", "done": false}

event: message
data: {"delta": "2. MEL 21-31-02 (Category C) - expires 2025-11-10\n", "done": false}

event: done
data: {"usage": {"tokens": 87}, "trace_id": "trace_abc123"}

---

Knowledge Graph

Query the semantic knowledge graph for maintenance relationships, technical dependencies, and historical patterns.

curl -X GET "$BASE/v1/graph/query" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "query": "MATCH (d:Defect)-[:RELATED_TO]->(p:Part) WHERE d.ata = \"32-41\" RETURN p.part_number, COUNT(d)"
  }'

---

Data Ingestion

Real-time event ingestion endpoints for MRO, flight ops, and logistics systems.

curl -X POST "$BASE/v1/ingest/events" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "event_type": "defect",
    "aircraft_reg": "N12345",
    "ata_chapter": "34-11",
    "description": "Anti-ice valve inoperative",
    "timestamp": "2025-11-04T10:15:00Z",
    "station": "KJFK",
    "source_system": "AMOS"
  }'

---

Audit & Compliance

Full audit trail for regulatory compliance and decision traceability.

curl -X GET "$BASE/v1/audit/trace?decision_id=dec_xyz789" \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "status": "success",
  "data": {
    "decision_id": "dec_xyz789",
    "timestamp": "2025-11-04T12:30:00Z",
    "user": "mcc.controller@airline.com",
    "query": "Can N12345 dispatch with MEL 34-11-01?",
    "recommendation": "Dispatch approved with restrictions",
    "reasoning_chain": [
      {
        "step": 1,
        "rule": "MEL_CATEGORY_B_VERIFICATION",
        "outcome": "pass",
        "data_sources": ["MEL_DATABASE", "AIRCRAFT_CONFIG"]
      },
      {
        "step": 2,
        "rule": "FLIGHT_RESTRICTION_CHECK",
        "outcome": "pass",
        "restrictions_applied": ["NO_ICING_CONDITIONS"]
      }
    ],
    "confidence": 0.98,
    "model_version": "controller-v2.3.1"
  }
}

---

Webhooks

Subscribe to real-time events via secure webhook delivery with HMAC signature verification.

curl -X POST "$BASE/v1/webhooks/subscribe" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "url": "https://your-app.com/webhooks/rectifai",
    "events": ["mel.expired", "aog.declared", "reliability.alert"],
    "secret": "<webhook-secret>"
  }'

Webhook Payload Example

{
  "event_type": "reliability.alert",
  "event_id": "evt_abc123",
  "timestamp": "2025-11-04T14:00:00Z",
  "data": {
    "alert_type": "recurrence_threshold",
    "ata_chapter": "32-41",
    "affected_aircraft": ["N12345", "N67890"],
    "recurrence_count": 5,
    "severity": "high"
  },
  "signature": "sha256=abc123def456..."
}

---

Administration

System administration and monitoring endpoints.

curl -X GET "$BASE/v1/admin/health"

{
  "status": "healthy",
  "version": "1.0.2",
  "uptime": 345600,
  "services": {
    "controller": "healthy",
    "chat": "healthy",
    "ingestion": "healthy",
    "knowledge_graph": "healthy"
  }
}

---

OpenAPI Specification

Download the complete OpenAPI 3.1 specification for programmatic integration:

curl -X GET "$BASE/v1/openapi.json" -o rectifai-openapi.json

Import this specification into tools like Postman, Insomnia, or code generators like OpenAPI Generator to automatically create client libraries.