{
  "openapi": "3.1.0",
  "info": {
    "title": "Cloud GPU Rating REST API",
    "description": "Independent, authoritative developer API providing real-time GPU cloud pricing matrices, bare-metal hardware benchmarks, and verified provider catalogs across 12+ enterprise and specialist AI clouds.",
    "version": "1.0.0",
    "contact": {
      "name": "Cloud GPU Rating Engineering",
      "url": "https://cloudgpurating.com",
      "email": "info@cloudgpurating.com"
    },
    "license": {
      "name": "Open Benchmark Dataset License",
      "url": "https://cloudgpurating.com/terms"
    }
  },
  "servers": [
    {
      "url": "https://cloudgpurating.com",
      "description": "Production Cloud GPU Rating API"
    }
  ],
  "paths": {
    "/api/v1/health": {
      "get": {
        "summary": "Health Check & System Diagnostics",
        "description": "Returns operational status, database connectivity, and timestamp.",
        "operationId": "getHealth",
        "responses": {
          "200": {
            "description": "System is healthy",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/providers": {
      "get": {
        "summary": "List Verified GPU Cloud Providers",
        "description": "Retrieve all verified providers with optional filtering by name query, category, GPU model, or maximum hourly budget.",
        "operationId": "listProviders",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": false,
            "description": "Filter by provider name or keyword (e.g., 'RunPod', 'InfiniBand')",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "Filter by provider category (e.g., 'Specialized GPU Cloud', 'Enterprise Hyperscaler')",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "gpu",
            "in": "query",
            "required": false,
            "description": "Filter by GPU accelerator model (e.g., 'H100', 'RTX 4090', 'MI300X')",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "max_price",
            "in": "query",
            "required": false,
            "description": "Maximum starting hourly price in USD",
            "schema": {
              "type": "number",
              "format": "float"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Array of verified GPU providers",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProvidersResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/providers/{slug}": {
      "get": {
        "summary": "Get Single Provider Profile & Specs",
        "description": "Retrieve comprehensive hardware, pricing, datacenter locations, egress policies, and benchmarks for a specific provider by slug.",
        "operationId": "getProviderBySlug",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "Unique provider slug identifier (e.g., 'runpod', 'lambda', 'coreweave', 'nebius', 'vast-ai', 'aws')",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Detailed provider specifications",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SingleProviderResponse"
                }
              }
            }
          },
          "404": {
            "description": "Provider not found"
          }
        }
      }
    },
    "/api/v1/pricing": {
      "get": {
        "summary": "Get Normalized GPU Hourly Pricing Matrix",
        "description": "Returns verified spot and on-demand hourly rates with calculated market statistics (min, median, max) across flagship architectures (H100 SXM5, RTX 4090, AMD MI300X, L40S, A100).",
        "operationId": "getPricingMatrix",
        "responses": {
          "200": {
            "description": "Normalized pricing dataset",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PricingMatrixResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/benchmarks": {
      "get": {
        "summary": "Get Interconnect & Inference Benchmarks",
        "description": "Access empirical bare-metal interconnect metrics (InfiniBand Quantum-2 vs RoCEv2 vs PCIe), inference token generation throughput across vLLM (tokens/sec), and FLOPS-per-dollar calculations.",
        "operationId": "getBenchmarks",
        "responses": {
          "200": {
            "description": "Hardware benchmark index",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BenchmarksResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/guides": {
      "get": {
        "summary": "List Technical Architecture Blueprints",
        "description": "Retrieve titles, slugs, and summaries of technical guides covering distributed Slurm training, vLLM serving, H100 vs H200 comparisons, and cloud TCO math.",
        "operationId": "listGuides",
        "responses": {
          "200": {
            "description": "List of architecture guides",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GuidesResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/ai-index": {
      "get": {
        "summary": "Complete AI LLM Knowledge Index",
        "description": "Unified machine-readable dataset designed specifically for AI models, LLMs, and agentic workflows to ingest the entire GPU cloud directory, pricing brackets, and recommendations in a single call.",
        "operationId": "getAiIndex",
        "responses": {
          "200": {
            "description": "Unified AI dataset",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AiIndexResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "HealthResponse": {
        "type": "object",
        "properties": {
          "status": { "type": "string", "example": "healthy" },
          "version": { "type": "string", "example": "1.0.0" },
          "database": { "type": "string", "example": "connected" },
          "timestamp": { "type": "string", "format": "date-time" }
        }
      },
      "ProviderItem": {
        "type": "object",
        "properties": {
          "name": { "type": "string", "example": "Runpod" },
          "slug": { "type": "string", "example": "runpod" },
          "website": { "type": "string", "format": "uri", "example": "https://www.runpod.io" },
          "summary": { "type": "string" },
          "category": { "type": "string", "example": "Specialized GPU Cloud" },
          "starting_price": { "type": "number", "example": 0.34 },
          "h100_price": { "type": "string", "example": "$2.69 / hr" },
          "interconnect": { "type": "string", "example": "3.2 Tbps NVIDIA Quantum-2 InfiniBand" },
          "egress_fee": { "type": "string", "example": "$0.00 / GB (Free)" },
          "regions": { "type": "string", "example": "North America, Europe, Asia" },
          "gpu_models": { "type": "string", "example": "RTX 4090, A100 80GB, H100 SXM5, L40S, MI300X" }
        }
      },
      "ProvidersResponse": {
        "type": "object",
        "properties": {
          "status": { "type": "string", "example": "success" },
          "count": { "type": "integer", "example": 12 },
          "data": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/ProviderItem" }
          }
        }
      },
      "SingleProviderResponse": {
        "type": "object",
        "properties": {
          "status": { "type": "string", "example": "success" },
          "provider": { "$ref": "#/components/schemas/ProviderItem" },
          "specs": { "type": "object" },
          "benchmarks": { "type": "object" },
          "faqs": { "type": "array", "items": { "type": "object" } }
        }
      },
      "PricingMatrixResponse": {
        "type": "object",
        "properties": {
          "status": { "type": "string", "example": "success" },
          "updated": { "type": "string", "example": "October 2026" },
          "summary": { "type": "object" },
          "matrix": { "type": "array", "items": { "type": "object" } }
        }
      },
      "BenchmarksResponse": {
        "type": "object",
        "properties": {
          "status": { "type": "string", "example": "success" },
          "benchmarks": {
            "type": "object",
            "properties": {
              "interconnect_bandwidth_gbps": { "type": "array", "items": { "type": "object" } },
              "vllm_serving_throughput": { "type": "array", "items": { "type": "object" } },
              "flops_per_dollar_index": { "type": "array", "items": { "type": "object" } }
            }
          }
        }
      },
      "GuidesResponse": {
        "type": "object",
        "properties": {
          "status": { "type": "string", "example": "success" },
          "count": { "type": "integer", "example": 10 },
          "guides": { "type": "array", "items": { "type": "object" } }
        }
      },
      "AiIndexResponse": {
        "type": "object",
        "properties": {
          "platform": { "type": "string", "example": "Cloud GPU Rating" },
          "version": { "type": "string", "example": "2026.10" },
          "providers": { "type": "array", "items": { "$ref": "#/components/schemas/ProviderItem" } },
          "gpu_architectures": { "type": "object" },
          "recommendations_for_llms": { "type": "object" }
        }
      }
    }
  }
}