{
  "openapi": "3.1.0",
  "info": {
    "title": "StackRates Ask API",
    "version": "1.7.0",
    "summary": "VPS and cloud server prices, read daily from providers' own pages and dated, answered in plain words.",
    "description": "Ask a hosting price question in plain words and get the plans that fit, cheapest first within each group (see Answer.rows), each with its monthly price, the day it was read and the provider page it was read from. Every number comes from the StackRates dataset (https://stackrates.ai/data/); nothing is estimated. Free, no key, no sign-up; a web page on any site may call it (CORS: any origin; GET, POST and OPTIONS). The same answers are served over MCP at https://stackrates.ai/mcp.",
    "license": { "name": "CC BY 4.0", "url": "https://creativecommons.org/licenses/by/4.0/" },
    "contact": { "name": "StackRates", "url": "https://stackrates.ai/ask/" }
  },
  "servers": [{ "url": "https://stackrates.ai" }],
  "paths": {
    "/api/ask": {
      "get": {
        "operationId": "askGet",
        "summary": "Answer a price question",
        "parameters": [
          { "name": "q", "in": "query", "required": true, "description": "The question in plain words, up to 1500 characters, e.g. \"cheapest 4gb vps in germany under $10\".", "schema": { "type": "string", "maxLength": 1500 } },
          { "name": "format", "in": "query", "required": false, "description": "json (the default) or text (the same answer as plain text).", "schema": { "type": "string", "enum": ["json", "text"], "default": "json" } },
          { "name": "mode", "in": "query", "required": false, "description": "advise: the adviser's answer, which can carry a reading from one turn to the next (POST a filter). Leave out for the plain answer.", "schema": { "type": "string", "enum": ["advise"] } },
          { "name": "limit", "in": "query", "required": false, "description": "How many rows, 1 to 20 (default 8).", "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 8 } }
        ],
        "responses": {
          "200": {
            "description": "The answer (JSON), or plain text with format=text.",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/Answer" } },
              "text/plain": { "schema": { "type": "string" } }
            }
          },
          "400": { "description": "No question and no filter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      },
      "post": {
        "operationId": "askPost",
        "summary": "Answer a price question, or carry a reading into the next turn",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "question": { "type": "string", "maxLength": 1500, "description": "The question in plain words." },
                  "filter": { "type": "object", "description": "The reading of the last turn (the answer's filter), carried into the next one; or a structured question on its own, e.g. {\"min_ram_gb\": 4, \"location\": \"germany\", \"max_usd_month\": 10}." },
                  "mode": { "type": "string", "enum": ["advise", "read"], "description": "advise: the adviser's answer. read: the reading of the text only, no prices (used by StackRates' own tools)." },
                  "term_months": { "type": "integer", "enum": [12, 36], "description": "The term the totals are counted over (advise)." },
                  "country": { "type": "string", "description": "The buyer's country as ISO 3166-1 alpha-2, for VAT (advise)." }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "The answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Answer" } } } },
          "400": { "description": "A body that is not JSON, or no question and no filter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "413": { "description": "A body over 8 KB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Answer": {
        "type": "object",
        "properties": {
          "headline": { "type": "string", "description": "The answer in one sentence, with the day the lead price was read." },
          "datasetDate": { "type": "string", "format": "date", "description": "The day the dataset was built." },
          "readAs": { "type": "string", "description": "How the question was read: every need used, and the needs not used (\"Not used: ...\")." },
          "reading": { "type": "string", "description": "The reading the answer answers, as a short line (absent when nothing was found)." },
          "rows": { "type": "array", "items": { "$ref": "#/components/schemas/Row" }, "description": "The plans that fit, in groups, each cheapest first: plans whose price is confirmed for the place asked; then plans whose price is not confirmed for that place; then plans whose price includes a Windows license, unless the question asks for Windows (then only those). A question about a place or a VPS lists no dedicated server unless it asks for one. A row after the first group is marked and is never the headline. When nothing fits, the nearest plans, each saying what it misses." },
          "notes": { "type": "array", "items": { "type": "string" }, "description": "Notes on the prices (IPv4 included, prepaid terms, older readings)." },
          "cannotAnswer": { "type": "array", "items": { "type": "string" }, "description": "What our data cannot tell (\"We cannot check: ...\", places we list no servers in, VAT not stated)." },
          "links": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "path": { "type": "string" } } }, "description": "StackRates pages that show the same prices." },
          "text": { "type": "string", "description": "The whole answer as plain text." },
          "license": { "type": "string", "description": "CC BY 4.0." },
          "attribution": { "type": "string", "description": "StackRates (https://stackrates.ai/)." }
        },
        "required": ["headline", "datasetDate", "readAs", "rows", "links"]
      },
      "Row": {
        "type": "object",
        "properties": {
          "providerName": { "type": "string" },
          "plan": { "type": "string", "description": "The plan's name; a nearest plan adds what it misses." },
          "vcpu": { "type": "number" },
          "ramGb": { "type": "number" },
          "usd": { "type": "number", "description": "The monthly price in US dollars, including a separately billed IPv4 address." },
          "commitmentMonths": { "type": ["integer", "null"], "description": "A prepaid term in months, or null for month to month." },
          "exVat": { "type": "boolean", "description": "True when the provider's page prices before VAT." },
          "checkedAt": { "type": "string", "format": "date", "description": "The day the price was read." },
          "sourceUrl": { "type": "string", "format": "uri", "description": "The provider page the price was read from." },
          "stackratesUrl": { "type": "string", "format": "uri", "description": "The StackRates page that lists the plan." },
          "kind": { "type": "string", "enum": ["dedicated", "windows"], "description": "Absent for a plain VPS; \"dedicated\" for a dedicated server, \"windows\" for a plan whose price includes a Windows license." },
          "marked": { "type": "boolean", "description": "True when the row is listed after the others and is never the answer: its price is not confirmed for the place asked, or it includes a Windows license the question did not ask for." },
          "marks": { "type": "array", "items": { "type": "string" }, "description": "The row's own labels, as the place pages print them: \"dedicated server\", \"Windows license included\", \"price from its price page; not confirmed for Singapore\", \"price of the OVHcloud US site\"." },
          "unconfirmedFor": { "type": "string", "description": "Present when the row's price is not confirmed for the place asked: that place's name." }
        },
        "required": ["providerName", "plan", "usd", "checkedAt", "sourceUrl"]
      },
      "Error": { "type": "object", "properties": { "error": { "type": "string" } } }
    }
  }
}
