openapi: 3.1.0
info:
  title: The IoT World Platform API
  version: 2.0.0
  description: Enterprise AI & IoT Platform APIs for 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
      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
  /api/v1/rag/query:
    post:
      summary: Query RAG document intelligence
      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
  /api/v1/inference/vllm:
    post:
      summary: Execute model inference
      operationId: executeInference
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [model, prompt]
              properties:
                model:
                  type: string
                prompt:
                  type: string
      responses:
        '200':
          description: Inference response
  /api/v1/hardware/mhs/diagnostics:
    get:
      summary: Get MHS hardware diagnostics
      operationId: getMhsDiagnostics
      responses:
        '200':
          description: Hardware diagnostic state