# Developer Resources & API Documentation — The IoT World

> Complete developer reference, OpenAPI specifications, Model Context Protocol (MCP) server endpoints, and API authentication patterns for The IoT World.

## Machine-Readable Specifications
- **OpenAPI 3.1 Specification (JSON)**: [https://www.theiotworld.io/openapi.json](https://www.theiotworld.io/openapi.json)
- **OpenAPI 3.1 Specification (YAML)**: [https://www.theiotworld.io/openapi.yaml](https://www.theiotworld.io/openapi.yaml)
- **MCP Server Manifest**: [https://www.theiotworld.io/mcp.json](https://www.theiotworld.io/mcp.json)
- **Agent Instructions Guide**: [https://www.theiotworld.io/agent-instructions.md](https://www.theiotworld.io/agent-instructions.md)

## Core API Endpoints

### 1. Ingest Telemetry (`POST /api/v1/telemetry/ingest`)
- **Description**: Ingests high-throughput encrypted device logs from laboratory and IoT hardware.
- **Headers**: `Authorization: Bearer <TOKEN>`, `Content-Type: application/json`
- **Request Body**:
```json
{
  "tenant_id": "tenant-001",
  "device_id": "baha-5000-01",
  "timestamp": "2026-08-28T08:00:00Z",
  "metrics": {
    "optical_density": 0.452,
    "reagent_level_pct": 87.5,
    "chamber_pressure_kpa": 101.3
  }
}
```

### 2. RAG Knowledge Query (`POST /api/v1/rag/query`)
- **Description**: Performs hybrid vector + lexical search across calibration and clinical documents with automatic PHI scrubbing.
- **Request Body**:
```json
{
  "tenant_id": "tenant-001",
  "query": "Calibration tolerances for BA-HA 5000 photometer lamp",
  "top_k": 5
}
```

### 3. Model Inference (`POST /api/v1/inference/vllm`)
- **Description**: OpenAI-compatible model completion endpoint hosted on Ray Serve & vLLM with tenant isolation.
- **Request Body**:
```json
{
  "model": "theiotworld-lora-clinical-v2",
  "prompt": "Analyze assay drift for sample batch #4092",
  "temperature": 0.2
}
```

### 4. Hardware Diagnostics (`GET /api/v1/hardware/mhs/diagnostics`)
- **Description**: Returns real-time Model Hardware Standard (MHS) diagnostics, QC flags, and sensor levels.