{
  "openapi": "3.1.0",
  "info": {
    "title": "Fuse room data",
    "version": "2.0.0",
    "summary": "Fuse's rooms, prices and availability in Budapest and Riga, read only and public, with no key.",
    "description": "Every Fuse room in Budapest and Riga, its monthly price for each contract length, when it is free, its address and its page, as the live listing on fusestays.com shows it.\n\nNo key and no sign in: every operation is public and read only; the JSON ones (rooms.json, rooms.jsonl, /ask) are open to any origin, the text ones (llms.txt, the markdown twins) are for servers and crawlers and send no CORS header. Nothing here books, holds, pays, uploads or signs. Only the student books, on the room's own page.\n\nRate limits: /ask allows 30 requests a minute per client and says so in its RateLimit headers; past that it answers 429 with Retry-After. The files have no rate limit; read them fresh rather than often.\n\nMCP servers (Model Context Protocol, JSON-RPC over Streamable HTTP POST, no key, read only, 60 requests a minute per client): rooms at https://fusestays.com/mcp, docs at https://fusestays.com/mcp/docs. Each has a server card at its address plus /server-card.\n\nEvery public reading page also has a markdown twin at its address plus .md (the home page at /index.md); pages such as the checkout, the portal and the listing search do not. Fields, freshness and terms in full: https://fusestays.com/rooms-data.",
    "contact": {
      "name": "Fuse",
      "email": "support@fusestays.com",
      "url": "https://fusestays.com/developers"
    }
  },
  "externalDocs": {
    "description": "Room data for apps and AI assistants",
    "url": "https://fusestays.com/rooms-data"
  },
  "servers": [
    {
      "url": "https://fusestays.com",
      "description": "fusestays.com"
    }
  ],
  "security": [],
  "tags": [
    {
      "name": "rooms",
      "description": "Every room, its prices and when it is free."
    },
    {
      "name": "search",
      "description": "Questions in plain words."
    },
    {
      "name": "pages",
      "description": "The site's pages and index as text for language models."
    }
  ],
  "paths": {
    "/rooms.json": {
      "get": {
        "operationId": "listRooms",
        "tags": [
          "rooms"
        ],
        "summary": "Every room with its price per contract length",
        "description": "Every Fuse room in Budapest and Riga, grouped by city, with its monthly price for each contract length, deposit, when it is free, address and page. Built from the live listing. The site reads the listing at most every 5 minutes, so a copy is usually up to 10 minutes old. generatedAt says when the file was built. A city whose list could not be read is marked failed, never left out.",
        "responses": {
          "200": {
            "description": "The rooms feed.",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "Age": {
                "$ref": "#/components/headers/Age"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RoomsFeed"
                }
              }
            }
          }
        }
      }
    },
    "/rooms.jsonl": {
      "get": {
        "operationId": "listRoomsAsSchemaOrg",
        "tags": [
          "rooms"
        ],
        "summary": "Every room as schema.org data, one per line",
        "description": "The same rooms as schema.org data, one JSON object per line: a Room, or an Apartment for a studio, with an Offer for each contract length and its availability (InStock when free now, PreOrder with availabilityStarts when it frees up later).",
        "responses": {
          "200": {
            "description": "One schema.org Accommodation per line.",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              }
            },
            "content": {
              "application/jsonl": {
                "schema": {
                  "type": "string",
                  "description": "JSON Lines: one schema.org Accommodation object per line."
                }
              }
            }
          },
          "503": {
            "description": "A city's rooms could not be read and no saved list is left: try again later, never an empty or partial feed.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              }
            },
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string",
                  "description": "A one line message."
                }
              }
            }
          }
        }
      }
    },
    "/ask": {
      "get": {
        "operationId": "askFuse",
        "tags": [
          "search"
        ],
        "summary": "Ask in plain words: matching rooms, buildings and FAQ answers",
        "description": "A question or a search in plain words, answered as NLWeb 0.55 defines it: matching rooms, buildings and FAQ answers, each with its page and its schema.org object. Never cached.",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": true,
            "description": "The question, for example: private room in Riga under 600 euros from February.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 300
            }
          },
          {
            "name": "prev",
            "in": "query",
            "required": false,
            "description": "Earlier questions of the same conversation, so a follow up keeps their filters: a JSON array of strings, or the questions separated by commas. The last five count.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "mode",
            "in": "query",
            "required": false,
            "description": "list returns the matches; summarize and generate add a short summary of the best match first.",
            "schema": {
              "type": "string",
              "enum": [
                "list",
                "summarize",
                "generate"
              ],
              "default": "list"
            }
          },
          {
            "name": "num",
            "in": "query",
            "required": false,
            "description": "How many results.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 25,
              "default": 10
            }
          },
          {
            "name": "streaming",
            "in": "query",
            "required": false,
            "description": "true for a text/event-stream instead of one JSON document.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The answer, as one JSON document, or as server sent events when streaming is asked for.",
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AskAnswer"
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string",
                  "description": "NLWeb events: start, one result per item, then complete."
                }
              }
            }
          },
          "400": {
            "description": "No query, or a query over the length limit.",
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Over 30 requests a minute from this client.",
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "The answer could not be built. Try again in a few minutes.",
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/llms.txt": {
      "get": {
        "operationId": "getLlmsTxt",
        "tags": [
          "pages"
        ],
        "summary": "The site index for language models",
        "description": "Who Fuse is, when to use it, prices by city and room type, every building and university page, how to book and where everything is (llmstxt.org). Built from the live listing. The site reads the listing at most every 5 minutes, so a copy is usually up to 10 minutes old.",
        "responses": {
          "200": {
            "description": "llms.txt.",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "Age": {
                "$ref": "#/components/headers/Age"
              }
            },
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string",
                  "description": "Markdown, as llmstxt.org defines it."
                }
              }
            }
          }
        }
      }
    },
    "/index.md": {
      "get": {
        "operationId": "getHomeMarkdown",
        "tags": [
          "pages"
        ],
        "summary": "The home page as markdown",
        "description": "The home page's words as markdown.",
        "responses": {
          "200": {
            "description": "The home page as markdown.",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              }
            },
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string",
                  "description": "The page as markdown, starting with its title as a heading."
                }
              }
            }
          }
        }
      }
    },
    "/pricing.md": {
      "get": {
        "operationId": "getPricesMarkdown",
        "tags": [
          "pages",
          "rooms"
        ],
        "summary": "Prices per city and room type as markdown",
        "description": "Rent from and to per city and room type, what the rent includes, the membership fee and the deposit, from the live listing.",
        "responses": {
          "200": {
            "description": "The prices page as markdown.",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              }
            },
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string",
                  "description": "The page as markdown, starting with its title as a heading."
                }
              }
            }
          }
        }
      }
    },
    "/faqs.md": {
      "get": {
        "operationId": "getFaqMarkdown",
        "tags": [
          "pages"
        ],
        "summary": "Every FAQ answer as markdown",
        "description": "Every question on the FAQ page with its answer.",
        "responses": {
          "200": {
            "description": "The FAQ page as markdown.",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              }
            },
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string",
                  "description": "The page as markdown, starting with its title as a heading."
                }
              }
            }
          }
        }
      }
    },
    "/cities/{city}.md": {
      "get": {
        "operationId": "getCityMarkdown",
        "tags": [
          "pages",
          "rooms"
        ],
        "summary": "A city page as markdown",
        "description": "A city's page as markdown: its rooms and prices for Budapest and Riga, the waitlist for the cities Fuse is not open in yet.",
        "parameters": [
          {
            "name": "city",
            "in": "path",
            "required": true,
            "description": "The city.",
            "schema": {
              "type": "string",
              "enum": [
                "budapest",
                "riga",
                "vienna",
                "prague",
                "krakow",
                "warsaw"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The city page as markdown.",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              }
            },
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string",
                  "description": "The page as markdown, starting with its title as a heading."
                }
              }
            }
          },
          "404": {
            "description": "No such page: a short markdown page that says where to go instead.",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string",
                  "description": "A markdown 404 page."
                }
              }
            }
          }
        }
      }
    },
    "/cities/{city}/properties/{room}.md": {
      "get": {
        "operationId": "getRoomMarkdown",
        "tags": [
          "pages",
          "rooms"
        ],
        "summary": "One room's page as markdown",
        "description": "One room's page as markdown: its price for each contract length, deposit, fees, dates, address and nearby universities.",
        "parameters": [
          {
            "name": "city",
            "in": "path",
            "required": true,
            "description": "The room's city.",
            "schema": {
              "type": "string",
              "enum": [
                "budapest",
                "riga"
              ]
            }
          },
          {
            "name": "room",
            "in": "path",
            "required": true,
            "description": "The room's id, as listRooms gives it.",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9-]+$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The room page as markdown.",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              }
            },
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string",
                  "description": "The page as markdown, starting with its title as a heading."
                }
              }
            }
          },
          "404": {
            "description": "No such page: a short markdown page that says where to go instead.",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string",
                  "description": "A markdown 404 page."
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "RoomsFeed": {
        "type": "object",
        "description": "Every room in Budapest and Riga, grouped by city, with the terms that apply to every room.",
        "required": [
          "version",
          "generatedAt",
          "provider",
          "currency",
          "terms",
          "cities"
        ],
        "properties": {
          "version": {
            "type": "integer",
            "const": 3,
            "description": "The feed's format version."
          },
          "generatedAt": {
            "type": "string",
            "description": "When this file was built, not when the listing was read.",
            "format": "date-time"
          },
          "provider": {
            "type": "object",
            "required": [
              "name",
              "website",
              "legalName",
              "country",
              "email",
              "rating",
              "ratingUrl"
            ],
            "properties": {
              "name": {
                "type": "string",
                "description": "Fuse."
              },
              "website": {
                "type": "string",
                "description": "The site.",
                "format": "uri"
              },
              "legalName": {
                "type": "string",
                "description": "The operating company."
              },
              "country": {
                "type": "string",
                "description": "Where it is registered."
              },
              "email": {
                "type": "string",
                "description": "Contact.",
                "format": "email"
              },
              "rating": {
                "type": "string",
                "description": "The public rating line."
              },
              "ratingUrl": {
                "type": "string",
                "description": "Where the rating comes from.",
                "format": "uri"
              }
            }
          },
          "currency": {
            "type": "string",
            "const": "EUR"
          },
          "terms": {
            "type": "object",
            "required": [
              "included",
              "fairUse",
              "contractMonths",
              "contractStartDays",
              "membershipFeeEur",
              "membershipFeeNote",
              "deposit",
              "howToBook",
              "pricesNote"
            ],
            "properties": {
              "included": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "What the monthly price includes."
              },
              "fairUse": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                },
                "description": "The fair use rule per city."
              },
              "contractMonths": {
                "type": "array",
                "items": {
                  "type": "integer"
                },
                "description": "The contract lengths in months."
              },
              "contractStartDays": {
                "type": "array",
                "items": {
                  "type": "integer"
                },
                "description": "The days of the month a contract can start."
              },
              "membershipFeeEur": {
                "type": "integer",
                "description": "The one time membership fee in EUR."
              },
              "membershipFeeNote": {
                "type": "string",
                "description": "When the fee is paid and when it is refunded."
              },
              "deposit": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                },
                "description": "The deposit rule per city."
              },
              "howToBook": {
                "type": "string",
                "description": "The booking steps; only the student books, on the room's page."
              },
              "pricesNote": {
                "type": "string",
                "description": "How to read the prices."
              }
            }
          },
          "cities": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FeedCity"
            }
          }
        }
      },
      "FeedCity": {
        "type": "object",
        "required": [
          "slug",
          "name",
          "country",
          "url",
          "fromMonthly",
          "failed",
          "saved",
          "rooms"
        ],
        "properties": {
          "slug": {
            "type": "string",
            "description": "budapest or riga."
          },
          "name": {
            "type": "string",
            "description": "The city's name."
          },
          "country": {
            "type": "string",
            "description": "The country's name (each room's address.country is its ISO 3166 code)."
          },
          "url": {
            "type": "string",
            "description": "The city's page.",
            "format": "uri"
          },
          "fromMonthly": {
            "type": [
              "integer",
              "null"
            ],
            "description": "The lowest monthly price the city page shows, in EUR."
          },
          "failed": {
            "type": "boolean",
            "description": "True when this city's list could not be read just now: its rooms are then empty because they are unknown, not because there are none."
          },
          "saved": {
            "type": "boolean",
            "description": "True when its rooms or their details come from the last good read, up to a day old."
          },
          "rooms": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FeedRoom"
            }
          }
        }
      },
      "FeedRoom": {
        "type": "object",
        "description": "One room.",
        "required": [
          "id",
          "url",
          "bookUrlTemplate",
          "city",
          "building",
          "address",
          "coordinates",
          "district",
          "homeType",
          "roomType",
          "sizeSqm",
          "bed",
          "floor",
          "sharedWith",
          "priceDependsOnStart",
          "monthlyPriceByContractMonths",
          "anyLengthOfferMonthly",
          "firstStartPrices",
          "monthlyPriceByStartDate",
          "monthlyPriceOnOtherStartDates",
          "anyLengthOfferOnOtherStartDates",
          "anyLengthOfferLastStart",
          "depositOn12Months",
          "availableNow",
          "availableFrom",
          "nearbyUniversities",
          "photo"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "The room's id, as in its page address.",
            "examples": [
              "hu-bu-05-01-04"
            ]
          },
          "url": {
            "type": "string",
            "description": "The room's page on fusestays.com, where the student books it.",
            "format": "uri"
          },
          "bookUrlTemplate": {
            "type": "string",
            "description": "The same page with a start date and contract length chosen: replace {yyyy-mm-dd} and {months}."
          },
          "city": {
            "type": "string",
            "description": "Budapest or Riga."
          },
          "building": {
            "type": "string",
            "description": "The street address of the building."
          },
          "address": {
            "type": "object",
            "required": [
              "street",
              "postalCode",
              "locality",
              "country"
            ],
            "properties": {
              "street": {
                "type": "string",
                "description": "Street and number."
              },
              "postalCode": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Postal code, when known."
              },
              "locality": {
                "type": "string",
                "description": "City."
              },
              "country": {
                "type": "string",
                "description": "ISO 3166 country code.",
                "examples": [
                  "HU",
                  "LV"
                ]
              }
            }
          },
          "coordinates": {
            "type": [
              "object",
              "null"
            ],
            "description": "The building's position, when known.",
            "required": [
              "lat",
              "lng"
            ],
            "properties": {
              "lat": {
                "type": "number"
              },
              "lng": {
                "type": "number"
              }
            }
          },
          "district": {
            "type": [
              "string",
              "null"
            ],
            "description": "The district, when known."
          },
          "homeType": {
            "type": [
              "string",
              "null"
            ],
            "description": "Flatshare, Coliving or Private apartment."
          },
          "roomType": {
            "type": [
              "string",
              "null"
            ],
            "description": "The room type as the site names it."
          },
          "sizeSqm": {
            "type": [
              "number",
              "null"
            ],
            "description": "Room size in square metres, when known."
          },
          "bed": {
            "type": [
              "string",
              "null"
            ],
            "description": "Bed size, when known."
          },
          "floor": {
            "type": [
              "string",
              "null"
            ],
            "description": "Floor, when known."
          },
          "sharedWith": {
            "type": [
              "integer",
              "null"
            ],
            "description": "For a shared room: how many people share it besides the student."
          },
          "priceDependsOnStart": {
            "type": "boolean",
            "description": "The price depends on the start date (monthlyPriceByStartDate or monthlyPriceOnOtherStartDates is set). Then monthlyPriceByContractMonths is empty and anyLengthOfferMonthly and depositOn12Months are null (version 3), and firstStartPrices holds the first start's."
          },
          "monthlyPriceByContractMonths": {
            "type": "object",
            "description": "Monthly price in EUR, all inclusive, on every start date, keyed by contract length in months (5, 6, 12). Shorter contracts cost more a month. Empty when priceDependsOnStart.",
            "propertyNames": {
              "pattern": "^[0-9]+$"
            },
            "additionalProperties": {
              "type": "integer",
              "minimum": 0
            }
          },
          "anyLengthOfferMonthly": {
            "type": [
              "integer",
              "null"
            ],
            "description": "The Riga offer: one monthly rate in EUR for any contract length, on every start date, when the room has it. Null when priceDependsOnStart."
          },
          "firstStartPrices": {
            "type": "object",
            "description": "The room's first start's prices (the start availableNow and availableFrom describe), for every room: a start date not in monthlyPriceByStartDate takes these, unless monthlyPriceOnOtherStartDates is set.",
            "required": [
              "monthlyPriceByContractMonths",
              "anyLengthOfferMonthly",
              "depositOn12Months"
            ],
            "properties": {
              "monthlyPriceByContractMonths": {
                "type": "object",
                "description": "Monthly price in EUR per contract length in months.",
                "propertyNames": {
                  "pattern": "^[0-9]+$"
                },
                "additionalProperties": {
                  "type": "integer",
                  "minimum": 0
                }
              },
              "anyLengthOfferMonthly": {
                "type": [
                  "integer",
                  "null"
                ],
                "description": "The Riga offer's monthly rate on the first start, when the room has it."
              },
              "depositOn12Months": {
                "type": [
                  "integer",
                  "null"
                ],
                "description": "The deposit in EUR on the first start's 12 month price."
              }
            }
          },
          "monthlyPriceByStartDate": {
            "type": "object",
            "description": "A start date (yyyy-mm-dd) priced otherwise than firstStartPrices: its monthly price in EUR per contract length, with no any length offer on it. Empty for nearly every room.",
            "propertyNames": {
              "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"
            },
            "additionalProperties": {
              "type": "object",
              "propertyNames": {
                "pattern": "^[0-9]+$"
              },
              "additionalProperties": {
                "type": "integer",
                "minimum": 0
              }
            }
          },
          "monthlyPriceOnOtherStartDates": {
            "type": [
              "object",
              "null"
            ],
            "description": "Only for a room whose first start is at Gera's Riga spring 2027 set price (every set price start is then in monthlyPriceByStartDate): any other start date, one after the spring window, is priced at this, its monthly price in EUR per contract length, never firstStartPrices. Null for nearly every room.",
            "propertyNames": {
              "pattern": "^[0-9]+$"
            },
            "additionalProperties": {
              "type": "integer",
              "minimum": 0
            }
          },
          "anyLengthOfferOnOtherStartDates": {
            "type": [
              "integer",
              "null"
            ],
            "description": "The Riga offer's monthly rate in EUR on those other start dates, when the room has it there."
          },
          "anyLengthOfferLastStart": {
            "type": [
              "string",
              "null"
            ],
            "description": "The last start date (yyyy-mm-dd) firstStartPrices' anyLengthOfferMonthly goes on: a later start date that takes firstStartPrices takes its monthly prices with no any length offer. Null when the offer has no end.",
            "format": "date"
          },
          "depositOn12Months": {
            "type": [
              "integer",
              "null"
            ],
            "description": "The deposit in EUR on the 12 month price, on every start date. Null when priceDependsOnStart."
          },
          "availableNow": {
            "type": "boolean",
            "description": "Free to move in now."
          },
          "availableFrom": {
            "type": [
              "string",
              "null"
            ],
            "description": "The first free day, when not free now.",
            "format": "date"
          },
          "nearbyUniversities": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "name",
                "distance",
                "time"
              ],
              "properties": {
                "name": {
                  "type": "string",
                  "description": "University."
                },
                "distance": {
                  "type": "string",
                  "description": "Distance, as the listing gives it."
                },
                "time": {
                  "type": "string",
                  "description": "Travel time, as the listing gives it."
                }
              }
            }
          },
          "photo": {
            "type": [
              "string",
              "null"
            ],
            "description": "One photo of the room, when it has one.",
            "format": "uri"
          }
        }
      },
      "AskAnswer": {
        "type": "object",
        "description": "An NLWeb answer (version 0.55).",
        "required": [
          "_meta",
          "query_id",
          "results"
        ],
        "properties": {
          "_meta": {
            "$ref": "#/components/schemas/AskMeta"
          },
          "query_id": {
            "type": "string",
            "description": "The caller's query_id when it was an id, else a new one."
          },
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AskResult"
            }
          }
        }
      },
      "AskMeta": {
        "type": "object",
        "required": [
          "response_type",
          "response_format",
          "version"
        ],
        "properties": {
          "response_type": {
            "type": "string",
            "enum": [
              "answer",
              "failure"
            ]
          },
          "response_format": {
            "type": "string",
            "const": "conversational_search"
          },
          "version": {
            "type": "string",
            "const": "0.55"
          },
          "mode": {
            "type": "string",
            "enum": [
              "list",
              "summarize",
              "generate"
            ]
          },
          "site": {
            "type": "string",
            "description": "fusestays.com."
          },
          "filters": {
            "type": "object",
            "description": "What the question was understood as: city, room types, budget, contract length, move in date."
          },
          "data_read_at": {
            "type": "string",
            "description": "When the answer was built, not when the listing was read.",
            "format": "date-time"
          },
          "message": {
            "type": "string",
            "description": "Said when nothing fits."
          }
        }
      },
      "AskResult": {
        "type": "object",
        "description": "A room, a building or an FAQ answer, with its schema.org object. A summary result (@type SearchSummary, with text) comes first when mode is summarize or generate.",
        "required": [
          "@type"
        ],
        "properties": {
          "@type": {
            "type": "string",
            "enum": [
              "Item",
              "SearchSummary"
            ]
          },
          "url": {
            "type": "string",
            "description": "The page that shows it.",
            "format": "uri"
          },
          "name": {
            "type": "string",
            "description": "Its name."
          },
          "site": {
            "type": "string",
            "description": "fusestays.com."
          },
          "siteUrl": {
            "type": "string",
            "description": "The site's domain (fusestays.com), not a full address."
          },
          "score": {
            "type": "number",
            "description": "How well it fits the question."
          },
          "description": {
            "type": "string",
            "description": "A short description."
          },
          "schema_object": {
            "type": "object",
            "description": "Its schema.org object (JSON-LD)."
          },
          "text": {
            "type": "string",
            "description": "The summary, on a SearchSummary result."
          }
        }
      },
      "Error": {
        "type": "object",
        "description": "Every error /ask answers: a code, a message and, where it helps, a hint.",
        "required": [
          "_meta",
          "error"
        ],
        "properties": {
          "_meta": {
            "$ref": "#/components/schemas/AskMeta"
          },
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "INVALID_QUERY",
                  "QUERY_TOO_LONG",
                  "RATE_LIMITED",
                  "INTERNAL_ERROR"
                ],
                "description": "INVALID_QUERY and QUERY_TOO_LONG with 400, RATE_LIMITED with 429, INTERNAL_ERROR with 500."
              },
              "message": {
                "type": "string",
                "description": "What went wrong."
              },
              "hint": {
                "type": "string",
                "description": "How to fix it."
              }
            }
          }
        }
      }
    },
    "headers": {
      "Cache-Control": {
        "description": "How long a shared cache may keep the answer: up to 5 minutes, and 5 more while a new one is built. Never kept when a city's list was missing or came from the last good read (no-store).",
        "schema": {
          "type": "string"
        }
      },
      "Age": {
        "description": "How many seconds ago the site built the copy it answers with.",
        "schema": {
          "type": "integer",
          "minimum": 0
        }
      },
      "RateLimit-Limit": {
        "description": "Requests allowed in the window.",
        "schema": {
          "type": "integer"
        }
      },
      "RateLimit-Remaining": {
        "description": "Requests left in the window.",
        "schema": {
          "type": "integer"
        }
      },
      "RateLimit-Reset": {
        "description": "Seconds until the window resets.",
        "schema": {
          "type": "integer"
        }
      },
      "Retry-After": {
        "description": "Seconds to wait before trying again.",
        "schema": {
          "type": "integer"
        }
      }
    }
  }
}