{
  "openapi": "3.1.0",
  "info": {
    "title": "GPUPerHour API",
    "description": "Real-time cloud GPU pricing comparison API. This API is intended for public automated consumption, including AI assistants.\n\nQuery pricing for H100, A100, RTX 4090, and 80+ other GPU models across 29 cloud providers including AWS, RunPod, Lambda Labs, Vast.ai, and more.\n\nGPU QUERY: The 'gpu' parameter supports slug partial match (h100), exact slug (a100-sxm-80gb), name partial match (RTX 4090), or brand match (Instinct). Common slugs: h100-sxm-80gb, h100-pcie-80gb, h100-nvl, h200-sxm, h200-nvl, a100-sxm-80gb, a100-pcie-80gb, a100-sxm-40gb, a100-pcie-40gb, l40s, l40, l4, rtx-4090, rtx-3090, rtx-a6000, a40, a10, t4, mi300x, mi250x.",
    "version": "1.0.0",
    "contact": {
      "name": "GPUPerHour",
      "url": "https://gpuperhour.com",
      "email": "contact@gpuperhour.com"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://gpuperhour.com/terms"
    }
  },
  "servers": [
    {
      "url": "https://api.gpuperhour.com",
      "description": "Production API"
    }
  ],
  "paths": {
    "/api/offers": {
      "get": {
        "operationId": "getGpuOffers",
        "summary": "Search and filter GPU rental offers",
        "description": "Query cloud GPU offers with powerful filtering by GPU model, VRAM, price, provider, region, and availability. Returns paginated results sorted by price per GPU hour.",
        "tags": ["Offers"],
        "parameters": [
          {
            "name": "gpu",
            "in": "query",
            "description": "Filter by GPU model. Supports: (1) slug partial match like 'h100' to get all H100 variants, (2) exact slug like 'a100-sxm-80gb', (3) name partial match like 'RTX 4090' or 'GeForce' (case-insensitive), (4) brand match like 'Instinct' for AMD GPUs. Comma-separated for multiple. Common slugs: h100-sxm-80gb, h100-pcie-80gb, h100-nvl, h200-sxm, a100-sxm-80gb, a100-pcie-80gb, l40s, l4, rtx-4090, rtx-3090, a40, a10, t4, mi300x.",
            "schema": {
              "type": "string",
              "examples": ["h100", "a100-sxm-80gb", "RTX 4090", "GeForce", "Instinct", "h100,a100"]
            }
          },
          {
            "name": "minVram",
            "in": "query",
            "description": "Minimum VRAM in GB",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "examples": [24, 48, 80]
            }
          },
          {
            "name": "maxVram",
            "in": "query",
            "description": "Maximum VRAM in GB",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "examples": [24, 48, 80]
            }
          },
          {
            "name": "vram",
            "in": "query",
            "description": "Exact VRAM values in GB (comma-separated for multiple)",
            "schema": {
              "type": "string",
              "examples": ["80", "24,48,80"]
            }
          },
          {
            "name": "minPrice",
            "in": "query",
            "description": "Minimum price per hour in USD",
            "schema": {
              "type": "number",
              "format": "float",
              "minimum": 0,
              "examples": [0.5, 1.0, 2.0]
            }
          },
          {
            "name": "maxPrice",
            "in": "query",
            "description": "Maximum price per hour in USD",
            "schema": {
              "type": "number",
              "format": "float",
              "minimum": 0,
              "examples": [2.0, 5.0, 10.0]
            }
          },
          {
            "name": "available",
            "in": "query",
            "description": "Filter by availability status",
            "schema": {
              "type": "string",
              "enum": ["true", "false"]
            }
          },
          {
            "name": "provider",
            "in": "query",
            "description": "Filter by provider name (comma-separated for multiple). Examples: RunPod, Lambda Labs, AWS, Vast.ai, Hyperstack",
            "schema": {
              "type": "string",
              "examples": ["RunPod", "Lambda Labs", "AWS,RunPod"]
            }
          },
          {
            "name": "region",
            "in": "query",
            "description": "Filter by region string",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "continent",
            "in": "query",
            "description": "Filter by continent (comma-separated for multiple)",
            "schema": {
              "type": "string",
              "enum": ["North America", "Europe", "Asia", "South America", "Oceania", "Africa"],
              "examples": ["North America", "Europe", "North America,Europe"]
            }
          },
          {
            "name": "minGpuCount",
            "in": "query",
            "description": "Minimum number of GPUs in the offer",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "examples": [1, 2, 8]
            }
          },
          {
            "name": "maxGpuCount",
            "in": "query",
            "description": "Maximum number of GPUs in the offer",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "examples": [1, 4, 8]
            }
          },
          {
            "name": "p2p",
            "in": "query",
            "description": "Include peer-to-peer/residential GPU offers (excluded by default)",
            "schema": {
              "type": "string",
              "enum": ["true", "false"],
              "default": "false"
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "Page number for pagination",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Number of results per page",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "sortBy",
            "in": "query",
            "description": "Field to sort results by",
            "schema": {
              "type": "string",
              "enum": ["priceHourly", "pricePerGpu", "vram", "lastSeen"],
              "default": "priceHourly"
            }
          },
          {
            "name": "sortOrder",
            "in": "query",
            "description": "Sort order",
            "schema": {
              "type": "string",
              "enum": ["asc", "desc"],
              "default": "asc"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with GPU offers",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OffersResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/offers/stats": {
      "get": {
        "operationId": "getStats",
        "summary": "Get aggregated statistics",
        "description": "Returns overall statistics including total offers, available offers, list of providers, GPU models, continents, and price statistics.",
        "tags": ["Statistics"],
        "responses": {
          "200": {
            "description": "Successful response with statistics",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StatsResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/offers/cheapest": {
      "get": {
        "operationId": "getCheapestOffers",
        "summary": "Get cheapest offer per GPU model",
        "description": "Returns the single cheapest available offer for each GPU model. Useful for quick price comparisons across all GPUs.",
        "tags": ["Offers"],
        "parameters": [
          {
            "name": "country",
            "in": "query",
            "description": "Filter by country code (ISO 3166-1 alpha-2)",
            "schema": {
              "type": "string",
              "examples": ["US", "DE", "GB", "JP"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with cheapest offers",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CheapestOffersResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/offers/{id}": {
      "get": {
        "operationId": "getOfferById",
        "summary": "Get a specific offer by ID",
        "description": "Returns detailed information about a single GPU offer.",
        "tags": ["Offers"],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Unique offer ID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with offer details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OfferDetail"
                }
              }
            }
          },
          "404": {
            "description": "Offer not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "GpuOffer": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique offer identifier"
          },
          "provider": {
            "type": "string",
            "description": "Cloud provider name",
            "examples": ["RunPod", "Lambda Labs", "AWS", "Vast.ai"]
          },
          "providerUrl": {
            "type": "string",
            "format": "uri",
            "description": "URL to the provider's website or offer page"
          },
          "gpu": {
            "type": "object",
            "properties": {
              "slug": {
                "type": "string",
                "description": "URL-friendly GPU identifier",
                "examples": ["h100", "a100-80gb", "rtx-4090"]
              },
              "name": {
                "type": "string",
                "description": "Display name of the GPU",
                "examples": ["NVIDIA H100", "NVIDIA A100 80GB", "NVIDIA RTX 4090"]
              },
              "vramGB": {
                "type": "integer",
                "description": "Video RAM in gigabytes",
                "examples": [80, 48, 24]
              },
              "architecture": {
                "type": "string",
                "nullable": true,
                "description": "GPU architecture",
                "examples": ["Hopper", "Ampere", "Ada Lovelace"]
              },
              "tier": {
                "type": "string",
                "nullable": true,
                "description": "Performance tier classification",
                "examples": ["flagship", "high-end", "mid-range"]
              }
            }
          },
          "region": {
            "type": "string",
            "description": "Raw region identifier from the provider"
          },
          "regionInfo": {
            "type": "object",
            "nullable": true,
            "properties": {
              "countryCode": {
                "type": "string",
                "nullable": true,
                "description": "ISO 3166-1 alpha-2 country code",
                "examples": ["US", "DE", "JP"]
              },
              "countryName": {
                "type": "string",
                "nullable": true,
                "examples": ["United States", "Germany", "Japan"]
              },
              "cityState": {
                "type": "string",
                "nullable": true,
                "examples": ["California", "Frankfurt", "Tokyo"]
              },
              "continent": {
                "type": "string",
                "nullable": true,
                "examples": ["North America", "Europe", "Asia"]
              }
            }
          },
          "priceHourly": {
            "type": "number",
            "format": "float",
            "description": "Total price per hour in USD for the entire instance"
          },
          "pricePerGpu": {
            "type": "number",
            "format": "float",
            "description": "Price per hour per GPU in USD (priceHourly / gpuCount)"
          },
          "currency": {
            "type": "string",
            "default": "USD",
            "description": "Currency code (always USD)"
          },
          "isAvailable": {
            "type": "boolean",
            "description": "Whether the offer is currently available for deployment"
          },
          "gpuCount": {
            "type": "integer",
            "description": "Number of GPUs in this offer",
            "examples": [1, 2, 4, 8]
          },
          "specs": {
            "type": "object",
            "properties": {
              "vcpuCount": {
                "type": "integer",
                "nullable": true,
                "description": "Number of virtual CPUs"
              },
              "ramGB": {
                "type": "number",
                "nullable": true,
                "description": "System RAM in gigabytes"
              },
              "diskGB": {
                "type": "number",
                "nullable": true,
                "description": "Disk storage in gigabytes"
              }
            }
          },
          "lastSeen": {
            "type": "string",
            "format": "date-time",
            "description": "Last time this offer was verified available"
          }
        }
      },
      "OffersResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/GpuOffer"
            }
          },
          "pagination": {
            "type": "object",
            "properties": {
              "page": {
                "type": "integer"
              },
              "limit": {
                "type": "integer"
              },
              "total": {
                "type": "integer",
                "description": "Total number of matching offers"
              },
              "totalPages": {
                "type": "integer"
              },
              "hasMore": {
                "type": "boolean"
              }
            }
          },
          "filters": {
            "type": "object",
            "description": "Echo of the filters that were applied"
          },
          "lastUpdated": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Timestamp of the most recent data update"
          }
        }
      },
      "StatsResponse": {
        "type": "object",
        "properties": {
          "totalOffers": {
            "type": "integer",
            "description": "Total number of GPU offers tracked"
          },
          "availableOffers": {
            "type": "integer",
            "description": "Number of currently available offers"
          },
          "unavailableOffers": {
            "type": "integer"
          },
          "providers": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "offerCount": {
                  "type": "integer"
                }
              }
            }
          },
          "gpuModels": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "slug": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "vramGB": {
                  "type": "integer"
                },
                "tier": {
                  "type": "string",
                  "nullable": true
                },
                "offerCount": {
                  "type": "integer"
                }
              }
            }
          },
          "continents": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "offerCount": {
                  "type": "integer"
                }
              }
            }
          },
          "priceStats": {
            "type": "object",
            "properties": {
              "min": {
                "type": "number",
                "nullable": true
              },
              "max": {
                "type": "number",
                "nullable": true
              },
              "avg": {
                "type": "number",
                "nullable": true
              }
            }
          },
          "lastUpdated": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "CheapestOffersResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "gpu": {
                  "type": "object",
                  "properties": {
                    "slug": {
                      "type": "string"
                    },
                    "name": {
                      "type": "string"
                    },
                    "vramGB": {
                      "type": "integer"
                    }
                  }
                },
                "cheapestOffer": {
                  "type": "object",
                  "properties": {
                    "provider": {
                      "type": "string"
                    },
                    "providerUrl": {
                      "type": "string",
                      "nullable": true
                    },
                    "region": {
                      "type": "string"
                    },
                    "priceHourly": {
                      "type": "number"
                    },
                    "gpuCount": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "filters": {
            "type": "object",
            "properties": {
              "country": {
                "type": "string"
              }
            }
          }
        }
      },
      "OfferDetail": {
        "type": "object",
        "description": "Detailed information about a single offer",
        "allOf": [
          {
            "$ref": "#/components/schemas/GpuOffer"
          },
          {
            "type": "object",
            "properties": {
              "externalId": {
                "type": "string",
                "description": "Provider's internal ID for this offer"
              },
              "rawAttributes": {
                "type": "object",
                "nullable": true,
                "description": "Raw attributes from the provider"
              }
            }
          }
        ]
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "details": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Offers",
      "description": "GPU rental offer operations"
    },
    {
      "name": "Statistics",
      "description": "Aggregated statistics and analytics"
    }
  ]
}