{
  "openapi": "3.1.0",
  "info": {
    "title": "Japan Trip Brain",
    "version": "1.0.0",
    "description": "Where to stay, what's on, and what to do in Japan for any city, month, and type of traveler. Built for AI agents and humans.\n\nFree, no API key, CORS open. Fair use: about 120 requests per minute per IP. Also available as MCP tools at https://free-agent-tools.vercel.app/mcp"
  },
  "servers": [
    {
      "url": "https://japan-trip-brain.vercel.app"
    }
  ],
  "paths": {
    "/api/plan": {
      "get": {
        "operationId": "planJapanTrip",
        "summary": "Where to stay, events, and what to do for a Japanese city in a given month",
        "description": "Returns season, weather, crowd level, the month's seasonal highlight, festivals that month (with typical dates), stay areas ranked for the traveler with a booking search URL each, things to do, warnings (New Year closures, Golden Week, Obon, rainy season, typhoons, heat), and an activities search URL. Typical seasonal patterns, not live data.\n\nExample: https://japan-trip-brain.vercel.app/api/plan?city=kyoto&month=11&traveler=couple",
        "parameters": [
          {
            "name": "city",
            "in": "query",
            "required": true,
            "description": "City id (a city name prefix also works).",
            "schema": {
              "type": "string",
              "description": "City id (a city name prefix also works).",
              "enum": [
                "tokyo",
                "kyoto",
                "osaka",
                "sapporo",
                "hiroshima",
                "naha"
              ]
            }
          },
          {
            "name": "month",
            "in": "query",
            "required": true,
            "description": "1-12 or English month name.",
            "schema": {
              "type": "string",
              "description": "1-12 or English month name."
            }
          },
          {
            "name": "traveler",
            "in": "query",
            "required": false,
            "description": "Optional traveler type; ranks stay areas for them.",
            "schema": {
              "type": "string",
              "description": "Optional traveler type; ranks stay areas for them.",
              "enum": [
                "solo",
                "couple",
                "family",
                "budget",
                "luxury",
                "nightlife"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Result as JSON. Always includes a `disclaimer` field.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid input. The body explains what to send and gives an example."
          },
          "429": {
            "description": "Too many requests from one IP. Retry after the Retry-After seconds."
          }
        }
      },
      "post": {
        "operationId": "planJapanTripPost",
        "summary": "Where to stay, events, and what to do for a Japanese city in a given month (JSON body)",
        "description": "Returns season, weather, crowd level, the month's seasonal highlight, festivals that month (with typical dates), stay areas ranked for the traveler with a booking search URL each, things to do, warnings (New Year closures, Golden Week, Obon, rainy season, typhoons, heat), and an activities search URL. Typical seasonal patterns, not live data.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "city",
                  "month"
                ],
                "properties": {
                  "city": {
                    "type": "string",
                    "description": "City id (a city name prefix also works).",
                    "enum": [
                      "tokyo",
                      "kyoto",
                      "osaka",
                      "sapporo",
                      "hiroshima",
                      "naha"
                    ]
                  },
                  "month": {
                    "type": "string",
                    "description": "1-12 or English month name."
                  },
                  "traveler": {
                    "type": "string",
                    "description": "Optional traveler type; ranks stay areas for them.",
                    "enum": [
                      "solo",
                      "couple",
                      "family",
                      "budget",
                      "luxury",
                      "nightlife"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result as JSON. Always includes a `disclaimer` field.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid input. The body explains what to send and gives an example."
          },
          "429": {
            "description": "Too many requests from one IP. Retry after the Retry-After seconds."
          }
        }
      }
    },
    "/api/cities": {
      "get": {
        "operationId": "listJapanCities",
        "summary": "Supported cities, months, and traveler types",
        "description": "Lists every supported city with region, summary, peak months, and stay areas; the 12 months with season and crowd level; and traveler types.\n\nExample: https://japan-trip-brain.vercel.app/api/cities",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Result as JSON. Always includes a `disclaimer` field.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid input. The body explains what to send and gives an example."
          },
          "429": {
            "description": "Too many requests from one IP. Retry after the Retry-After seconds."
          }
        }
      },
      "post": {
        "operationId": "listJapanCitiesPost",
        "summary": "Supported cities, months, and traveler types (JSON body)",
        "description": "Lists every supported city with region, summary, peak months, and stay areas; the 12 months with season and crowd level; and traveler types.",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [],
                "properties": {}
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result as JSON. Always includes a `disclaimer` field.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid input. The body explains what to send and gives an example."
          },
          "429": {
            "description": "Too many requests from one IP. Retry after the Retry-After seconds."
          }
        }
      }
    }
  }
}