{
 "openapi": "3.1.0",
 "info": {
  "title": "pickyourmatch — ask for accommodation in plain words",
  "version": "1.0.0",
  "summary": "Exact, directly bookable accommodation units: public, read-only, no key.",
  "description": "pickyourmatch answers an accommodation request with individually described units — floor, view, beds, per-unit dog and child allowances — from each participating property’s own system, with live availability and the property’s own price for exact dates. Booking happens on the property’s own booking page; everything a listing states is what the guest is assigned — guaranteed.\n\nNo key, no account, no sign-in: every operation is a public GET and nothing can be written. Send the header `x-pym-test: 1` on test calls so they are not counted as real requests. No quota is published; dated requests ask each property’s booking system live, so keep an answer for a few minutes instead of repeating the request. Guide: https://pickyourmatch.com/developers/",
  "contact": {
   "name": "pickyourmatch (GauVendi GmbH)",
   "url": "https://pickyourmatch.com/support/",
   "email": "info@gauvendi.com"
  },
  "termsOfService": "https://pickyourmatch.com/terms/"
 },
 "servers": [
  {
   "url": "https://pickyourmatch.com"
  }
 ],
 "externalDocs": {
  "description": "Guide for developers and AI agents",
  "url": "https://pickyourmatch.com/developers/"
 },
 "paths": {
  "/ask": {
   "get": {
    "operationId": "askStays",
    "summary": "Find accommodation that fits a request",
    "tags": [
     "ask"
    ],
    "description": "Give the guest’s request in plain words (`q`) and everything known about the traveller (`context`); add dates and the party as fields when they are known. Without dates the answer shows bookable units with from-prices. Without any parameter the answer explains how to ask. The answer is Markdown for an agent, JSON with `format=json`, and a page for a browser.",
    "parameters": [
     {
      "name": "q",
      "in": "query",
      "required": false,
      "description": "The request in the guest’s own words, in any language.",
      "schema": {
       "type": "string",
       "maxLength": 400
      },
      "example": "apartment with a sauna for 2 adults and a dog"
     },
     {
      "name": "context",
      "in": "query",
      "required": false,
      "description": "What is known about the traveller: who travels, children’s ages, a dog, an electric car, a wheelchair, what the trip is for.",
      "schema": {
       "type": "string",
       "maxLength": 600
      },
      "example": "a couple, anniversary weekend, arriving by train"
     },
     {
      "name": "check_in",
      "in": "query",
      "required": false,
      "description": "Arrival, YYYY-MM-DD. Give it together with check_out.",
      "schema": {
       "type": "string",
       "format": "date"
      },
      "example": "2027-01-22"
     },
     {
      "name": "check_out",
      "in": "query",
      "required": false,
      "description": "Departure, YYYY-MM-DD: after check_in, at most 30 nights.",
      "schema": {
       "type": "string",
       "format": "date"
      },
      "example": "2027-01-24"
     },
     {
      "name": "adults",
      "in": "query",
      "required": false,
      "description": "Number of adults. Two when not given.",
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 30
      },
      "example": 2
     },
     {
      "name": "children_ages",
      "in": "query",
      "required": false,
      "description": "Ages of the children, 0 to 17, separated by commas.",
      "schema": {
       "type": "string",
       "pattern": "^\\d{1,2}(,\\d{1,2})*$"
      },
      "example": "6,9"
     },
     {
      "name": "pets",
      "in": "query",
      "required": false,
      "description": "Number of dogs or other pets. Only units that allow this many are returned.",
      "schema": {
       "type": "integer",
       "minimum": 0,
       "maximum": 10
      }
     },
     {
      "name": "max_price",
      "in": "query",
      "required": false,
      "description": "Highest price per night, in the property’s own currency.",
      "schema": {
       "type": "number",
       "minimum": 1
      }
     },
     {
      "name": "city",
      "in": "query",
      "required": false,
      "description": "Town or destination.",
      "schema": {
       "type": "string",
       "maxLength": 80
      },
      "example": "Schladming"
     },
     {
      "name": "near",
      "in": "query",
      "required": false,
      "description": "A place, venue or address to stay near.",
      "schema": {
       "type": "string",
       "maxLength": 120
      }
     },
     {
      "name": "radius_km",
      "in": "query",
      "required": false,
      "description": "Distance to `near` in kilometres.",
      "schema": {
       "type": "number",
       "minimum": 0.1,
       "maximum": 500
      }
     },
     {
      "name": "features",
      "in": "query",
      "required": false,
      "description": "Features the unit must have, separated by commas — the names in /ai-inventory.json or of the feature hubs in /llms.txt.",
      "schema": {
       "type": "string"
      },
      "example": "Sauna,Balcony"
     },
     {
      "name": "free_cancellation",
      "in": "query",
      "required": false,
      "description": "Only offers that can be cancelled free of charge.",
      "schema": {
       "type": "boolean"
      }
     },
     {
      "name": "unit",
      "in": "query",
      "required": false,
      "description": "One unit, as `<property>:<code>` from a page address or an earlier answer: its live state plus alternatives.",
      "schema": {
       "type": "string",
       "pattern": "^[a-z0-9-]+:[A-Za-z0-9_-]+$"
      }
     },
     {
      "name": "property",
      "in": "query",
      "required": false,
      "description": "One property, by the first part of its page address.",
      "schema": {
       "type": "string",
       "pattern": "^[a-z0-9-]+$"
      }
     },
     {
      "name": "lang",
      "in": "query",
      "required": false,
      "description": "Language of the answer.",
      "schema": {
       "type": "string",
       "enum": [
        "en",
        "de",
        "fr",
        "es",
        "it",
        "nl",
        "ar"
       ],
       "default": "en"
      }
     },
     {
      "name": "format",
      "in": "query",
      "required": false,
      "description": "md (Markdown), json or html. When not given, the Accept header decides.",
      "schema": {
       "type": "string",
       "enum": [
        "md",
        "json",
        "html"
       ]
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "description": "How many candidates are read before the best are chosen.",
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 50,
       "default": 24
      }
     },
     {
      "name": "x-pym-test",
      "in": "header",
      "required": false,
      "description": "Send 1 on test calls: they are answered like any other and are not counted.",
      "schema": {
       "type": "string",
       "enum": [
        "1"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "The answer: what was understood, the best matches and why each fits, alternatives and what differs, the same units on other dates, and a booking link per unit.",
      "content": {
       "text/markdown": {
        "schema": {
         "type": "string"
        }
       },
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Answer"
        }
       },
       "text/html": {
        "schema": {
         "type": "string"
        }
       }
      }
     },
     "400": {
      "description": "The request could not be read. `problems` names every parameter that cannot be used and how it should look.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        },
        "example": {
         "error": {
          "code": "invalid_request",
          "message": "The request could not be read",
          "problems": [
           {
            "parameter": "check_in",
            "message": "check_in must be a date written YYYY-MM-DD, for example 2027-01-22"
           }
          ],
          "docs": "https://pickyourmatch.com/developers/"
         }
        }
       }
      }
     },
     "503": {
      "description": "The search failed just now. Come back after the seconds in `Retry-After`.",
      "headers": {
       "Retry-After": {
        "schema": {
         "type": "integer"
        },
        "description": "Seconds to wait"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   },
   "post": {
    "operationId": "askNlweb",
    "summary": "The same question in the NLWeb shape",
    "tags": [
     "ask"
    ],
    "description": "For a caller that speaks NLWeb (v0.55): the request in `query.text`, filters beside it, what is known about the traveller in `context`. Answers typed items (schema.org Accommodation) with price, source and a booking action. A stream of events (start, result, complete) when `prefer.streaming` is true or the Accept header asks for text/event-stream.",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/NlwebRequest"
       },
       "example": {
        "query": {
         "text": "apartment with a sauna for 2 adults and a dog",
         "check_in": "2027-01-22",
         "check_out": "2027-01-24"
        },
        "context": {
         "text": "anniversary weekend, arriving by train"
        },
        "prefer": {
         "mode": "list, summarize"
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "An answer — or a failure of the question, named in `error.code` (see `_meta.response_type`).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/NlwebResponse"
        }
       },
       "text/event-stream": {
        "schema": {
         "type": "string"
        }
       }
      }
     },
     "400": {
      "description": "The body is not JSON, or has no query.text.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/NlwebResponse"
        }
       }
      }
     },
     "503": {
      "description": "The search failed just now. Come back after the seconds in `Retry-After`.",
      "headers": {
       "Retry-After": {
        "schema": {
         "type": "integer"
        },
        "description": "Seconds to wait"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/NlwebResponse"
        }
       }
      }
     }
    }
   }
  },
  "/ask/feedback": {
   "get": {
    "operationId": "sendFeedback",
    "summary": "Tell how an answer went",
    "tags": [
     "ask"
    ],
    "description": "No personal data. Each report is read and used to improve the answers.",
    "parameters": [
     {
      "name": "outcome",
      "in": "query",
      "required": false,
      "description": "What happened with the answer.",
      "schema": {
       "type": "string",
       "enum": [
        "booked",
        "shortlisted",
        "not_suitable",
        "no_match"
       ]
      },
      "example": "shortlisted"
     },
     {
      "name": "missing",
      "in": "query",
      "required": false,
      "description": "What the guest wanted and did not find.",
      "schema": {
       "type": "string",
       "maxLength": 200
      }
     },
     {
      "name": "product",
      "in": "query",
      "required": false,
      "description": "The unit concerned, as `<property>:<code>`.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "format",
      "in": "query",
      "required": false,
      "description": "md or json.",
      "schema": {
       "type": "string",
       "enum": [
        "md",
        "json"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Received.",
      "content": {
       "text/markdown": {
        "schema": {
         "type": "string"
        }
       },
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          },
          "received": {
           "type": "object"
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/ai-inventory.json": {
   "get": {
    "operationId": "getInventory",
    "summary": "Every participating property and its bookable units",
    "tags": [
     "data"
    ],
    "description": "Facts per property and per unit — address, check-in and check-out, features, bookable extras and the page of each unit. Rebuilt every night from each property’s own system.",
    "responses": {
     "200": {
      "description": "The inventory.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "additionalProperties": true
        }
       }
      }
     }
    }
   }
  }
 },
 "components": {
  "schemas": {
   "Error": {
    "type": "object",
    "required": [
     "error"
    ],
    "properties": {
     "error": {
      "type": "object",
      "required": [
       "code",
       "message"
      ],
      "properties": {
       "code": {
        "type": "string",
        "enum": [
         "invalid_request",
         "not_found",
         "temporarily_unavailable"
        ]
       },
       "message": {
        "type": "string"
       },
       "problems": {
        "type": "array",
        "items": {
         "type": "object",
         "required": [
          "parameter",
          "message"
         ],
         "properties": {
          "parameter": {
           "type": "string"
          },
          "message": {
           "type": "string"
          }
         }
        }
       },
       "retry_after_seconds": {
        "type": "integer"
       },
       "docs": {
        "type": "string",
        "format": "uri"
       }
      }
     }
    }
   },
   "NlwebRequest": {
    "type": "object",
    "required": [
     "query"
    ],
    "properties": {
     "query": {
      "type": "object",
      "required": [
       "text"
      ],
      "additionalProperties": true,
      "properties": {
       "text": {
        "type": "string",
        "description": "The request in the guest’s own words."
       },
       "location": {
        "type": "string",
        "description": "Town or destination."
       },
       "check_in": {
        "type": "string",
        "format": "date"
       },
       "check_out": {
        "type": "string",
        "format": "date"
       },
       "adults": {
        "type": "integer"
       },
       "children_ages": {
        "type": "array",
        "items": {
         "type": "integer",
         "minimum": 0,
         "maximum": 17
        }
       },
       "pets": {
        "type": "integer"
       },
       "max_price": {
        "type": "number"
       },
       "features": {
        "type": "array",
        "items": {
         "type": "string"
        }
       }
      }
     },
     "context": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
       "text": {
        "type": "string"
       },
       "memory": {
        "type": "string"
       },
       "prev": {
        "type": "array",
        "items": {
         "type": "string"
        }
       }
      }
     },
     "prefer": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
       "streaming": {
        "type": "boolean"
       },
       "mode": {
        "type": "string",
        "description": "list, summarize, or both separated by a comma"
       },
       "accept-language": {
        "type": "string"
       },
       "response_format": {
        "type": "string",
        "enum": [
         "conversational_search"
        ]
       }
      }
     },
     "meta": {
      "type": "object",
      "additionalProperties": true
     }
    }
   },
   "NlwebResponse": {
    "type": "object",
    "required": [
     "_meta"
    ],
    "properties": {
     "_meta": {
      "type": "object",
      "required": [
       "response_type",
       "version"
      ],
      "properties": {
       "response_type": {
        "type": "string",
        "enum": [
         "answer",
         "failure"
        ]
       },
       "response_format": {
        "type": "string"
       },
       "version": {
        "type": "string"
       }
      }
     },
     "results": {
      "type": "array",
      "description": "Typed items: schema.org Accommodation per stay, and a SearchSummary first when a summary was asked for.",
      "items": {
       "type": "object",
       "additionalProperties": true
      }
     },
     "error": {
      "type": "object",
      "properties": {
       "code": {
        "type": "string",
        "enum": [
         "NO_RESULTS",
         "INVALID_QUERY",
         "UNSUPPORTED_FORMAT",
         "UNSUPPORTED_MODE",
         "INTERNAL_ERROR"
        ]
       },
       "message": {
        "type": "string"
       }
      }
     }
    }
   },
   "Requirement": {
    "type": "object",
    "description": "One requirement of the request, checked against the unit’s own data.",
    "properties": {
     "requirement": {
      "type": "string"
     },
     "status": {
      "type": "string",
      "enum": [
       "confirmed",
       "not_met",
       "unknown",
       "conflicting"
      ]
     },
     "evidence": {
      "type": "string"
     }
    }
   },
   "Stay": {
    "type": "object",
    "additionalProperties": true,
    "description": "One bookable unit. Prices are the property’s own; with dates they are live for exactly those dates.",
    "properties": {
     "id": {
      "type": "string",
      "description": "<property>:<code> — stable, usable as the `unit` parameter"
     },
     "name": {
      "type": "string"
     },
     "property": {
      "type": "string"
     },
     "city": {
      "type": "string"
     },
     "country": {
      "type": "string"
     },
     "sleeps": {
      "type": "integer"
     },
     "bedrooms": {
      "type": "integer"
     },
     "max_children": {
      "type": "integer"
     },
     "max_dogs": {
      "type": "integer"
     },
     "features": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "price_from_per_night": {
      "type": "string"
     },
     "price_per_night": {
      "type": "string"
     },
     "price_total_for_stay": {
      "type": "string"
     },
     "available": {
      "type": "boolean"
     },
     "match_score": {
      "type": "integer",
      "minimum": 0,
      "maximum": 100,
      "description": "Share of ALL requirements that are confirmed"
     },
     "requirements": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Requirement"
      }
     },
     "benefits_for_this_trip": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "lat": {
      "type": "number"
     },
     "lng": {
      "type": "number"
     },
     "approx_km": {
      "type": "number"
     },
     "book_url": {
      "type": "string",
      "format": "uri",
      "description": "Opens exactly this unit on the property’s own booking page. Give it to the guest as written."
     },
     "details_and_booking_url": {
      "type": "string",
      "format": "uri"
     }
    }
   },
   "Answer": {
    "type": "object",
    "additionalProperties": true,
    "properties": {
     "interpreted": {
      "type": "object",
      "additionalProperties": true,
      "description": "What was understood: place, dates, party, requirements, budget."
     },
     "check_in": {
      "type": "string",
      "format": "date"
     },
     "check_out": {
      "type": "string",
      "format": "date"
     },
     "nights": {
      "type": "integer"
     },
     "confirmed_matches": {
      "type": "integer"
     },
     "results": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Stay"
      }
     },
     "same_units_other_dates": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Stay"
      }
     },
     "alternative_dates": {
      "type": "array",
      "items": {
       "type": "object",
       "additionalProperties": true
      }
     },
     "dates_note": {
      "type": "string"
     },
     "guidance": {
      "type": "string"
     },
     "brief_markdown": {
      "type": "string",
      "description": "The same answer as Markdown, ready to present."
     }
    }
   }
  }
 }
}
