{
  "openapi": "3.1.0",
  "info": {
    "title": "SuperhotGeo API",
    "version": "1.0.0",
    "description": "Curated, public data on superhot rock geothermal energy, plus a grounded assistant. Free to read (rate-limited); pass an API key for higher quotas and access to /ask. Please attribute to \"SuperhotGeo (superhotgeo.com)\".",
    "contact": { "name": "SuperhotGeo", "email": "info@superhotgeo.com", "url": "https://superhotgeo.com" },
    "license": { "name": "Attribution required", "url": "https://superhotgeo.com/llms.txt" }
  },
  "servers": [
    { "url": "https://superhotgeo.com/api/v1", "description": "Production" }
  ],
  "security": [{ "ApiKeyHeader": [] }, { "BearerAuth": [] }, {}],
  "paths": {
    "/{resource}": {
      "get": {
        "operationId": "listResource",
        "summary": "List records from a public collection",
        "description": "Returns a page of records. Use q for a keyword filter, limit/offset to page.",
        "parameters": [
          { "$ref": "#/components/parameters/Resource" },
          { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Keyword filter over the resource's text fields." },
          { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } },
          { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } },
          { "name": "order", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Field to order by." },
          { "name": "dir", "in": "query", "required": false, "schema": { "type": "string", "enum": ["asc", "desc"] } }
        ],
        "responses": {
          "200": {
            "description": "A page of records.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse" } } }
          },
          "404": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/{resource}/{id}": {
      "get": {
        "operationId": "getResource",
        "summary": "Fetch one record by id",
        "parameters": [
          { "$ref": "#/components/parameters/Resource" },
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "The record.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordResponse" } } }
          },
          "404": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/ask": {
      "post": {
        "operationId": "askSuperhot",
        "summary": "Ask the grounded SuperhotGeo Assistant",
        "description": "Returns a grounded answer with cited web sources. Requires an API key.",
        "security": [{ "ApiKeyHeader": [] }, { "BearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["question"],
                "properties": {
                  "question": { "type": "string", "maxLength": 1000, "description": "The question about superhot geothermal." },
                  "history": {
                    "type": "array",
                    "description": "Optional prior turns for context.",
                    "items": {
                      "type": "object",
                      "properties": { "role": { "type": "string", "enum": ["user", "assistant"] }, "text": { "type": "string" } }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Grounded answer.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "answer": { "type": "string" },
                    "question": { "type": "string" },
                    "sources": {
                      "type": "array",
                      "items": { "type": "object", "properties": { "title": { "type": "string" }, "url": { "type": "string", "format": "uri" } } }
                    }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyHeader": { "type": "apiKey", "in": "header", "name": "x-api-key" },
      "BearerAuth": { "type": "http", "scheme": "bearer" }
    },
    "parameters": {
      "Resource": {
        "name": "resource",
        "in": "path",
        "required": true,
        "description": "Which public collection.",
        "schema": {
          "type": "string",
          "enum": ["library", "projects", "pioneers", "vendors", "testbeds", "lessons", "exchange", "offtake", "datasets", "insights"]
        }
      }
    },
    "responses": {
      "Error": {
        "description": "Error.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "limit": { "type": "integer" } }
            }
          }
        }
      }
    },
    "schemas": {
      "Record": {
        "type": "object",
        "description": "A record; fields vary by resource. Always includes an id.",
        "properties": { "id": { "type": "string" } },
        "additionalProperties": true
      },
      "ListResponse": {
        "type": "object",
        "properties": {
          "resource": { "type": "string" },
          "count": { "type": "integer" },
          "limit": { "type": "integer" },
          "offset": { "type": "integer" },
          "query": { "type": "string" },
          "data": { "type": "array", "items": { "$ref": "#/components/schemas/Record" } }
        }
      },
      "RecordResponse": {
        "type": "object",
        "properties": {
          "resource": { "type": "string" },
          "data": { "$ref": "#/components/schemas/Record" }
        }
      }
    }
  }
}