{
  "openapi": "3.1.0",
  "info": {
    "title": "The IoT World Platform API",
    "version": "2.0.0",
    "description": "Enterprise AI & IoT Platform APIs for high-throughput telemetry ingestion, RAG document intelligence, vLLM model inference, and Model Hardware Standard (MHS) diagnostics.",
    "contact": {
      "name": "Dr. Amit Puri",
      "email": "amit.puri@amitpuri.com",
      "url": "https://www.theiotworld.io"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://www.theiotworld.io/privacy"
    }
  },
  "servers": [
    {
      "url": "https://api.theiotworld.io",
      "description": "Production Multi-Tenant API Gateway"
    }
  ],
  "paths": {
    "/api/v1/telemetry/ingest": {
      "post": {
        "summary": "Ingest device telemetry",
        "description": "Ingest mTLS-encrypted high-velocity IoT and laboratory device logs into Kafka tenant partitions.",
        "operationId": "ingestTelemetry",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["tenant_id", "device_id", "timestamp", "metrics"],
                "properties": {
                  "tenant_id": { "type": "string" },
                  "device_id": { "type": "string" },
                  "timestamp": { "type": "string", "format": "date-time" },
                  "metrics": { "type": "object" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Telemetry ingested successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string", "example": "queued" },
                    "message_id": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/rag/query": {
      "post": {
        "summary": "Query RAG document intelligence",
        "description": "Execute hybrid dense (pgvector) and sparse (BM25) search with cross-encoder reranking and automated PHI redaction.",
        "operationId": "queryRag",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["tenant_id", "query"],
                "properties": {
                  "tenant_id": { "type": "string" },
                  "query": { "type": "string" },
                  "top_k": { "type": "integer", "default": 5 }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "RAG query results",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "answer": { "type": "string" },
                    "citations": { "type": "array", "items": { "type": "object" } }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/inference/vllm": {
      "post": {
        "summary": "Execute model inference",
        "description": "Serve multi-tenant LLM completions via vLLM with PagedAttention and continuous dynamic batching.",
        "operationId": "executeInference",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["model", "prompt"],
                "properties": {
                  "model": { "type": "string" },
                  "prompt": { "type": "string" },
                  "temperature": { "type": "number", "default": 0.2 }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Inference completion response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": { "type": "string" },
                    "text": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/hardware/mhs/diagnostics": {
      "get": {
        "summary": "Get MHS hardware diagnostics",
        "description": "Retrieve live Model Hardware Standard diagnostic states, optical levels, and QC flags.",
        "operationId": "getMhsDiagnostics",
        "responses": {
          "200": {
            "description": "Hardware diagnostic state",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string", "example": "healthy" },
                    "instruments": { "type": "array", "items": { "type": "object" } }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}