{
  "openapi": "3.1.1",
  "info": {
    "title": "BoardShuffle Games and Setup Guides API",
    "version": "1.2.0",
    "description": "Public, read-only board game metadata, setup instructions and generation settings. Generate setups using the separate MCP endpoint; saved setups remain on the device."
  },
  "servers": [
    {
      "url": "https://boardshuffle.com"
    }
  ],
  "externalDocs": {
    "url": "https://boardshuffle.com/api/docs.md"
  },
  "security": [],
  "paths": {
    "/api/generation/{gameId}.json": {
      "get": {
        "operationId": "getGenerationOptions",
        "summary": "Read per-game MCP generation settings and defaults",
        "parameters": [
          {
            "name": "gameId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "description": "Game route identifier.",
              "enum": [
                "a-handful-of-stars",
                "azul",
                "barony",
                "bloc-by-bloc",
                "burgle-bros",
                "carcassonne",
                "catan",
                "chronicles-of-avel",
                "civilization-new-dawn",
                "clans-of-caledonia",
                "clockwork-wars",
                "codenames",
                "cyclades",
                "eight-minute-legends",
                "el-dorado",
                "empires-of-the-void-2",
                "escape-from-atlantis",
                "five-tribes",
                "forbidden-desert",
                "forbidden-island",
                "forbidden-stars",
                "gaia-project",
                "ghost-stories",
                "heroscape",
                "kingdom-builder",
                "labyrinth",
                "rise-and-fall",
                "scythe",
                "small-world-realms",
                "spirit-island",
                "splendor",
                "ticket-to-ride",
                "tiny-epic-pirates",
                "tiny-epic-zombies",
                "twilight-imperium"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Defaults and JSON input schema for boardshuffle_generate_setup.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "gameId",
                    "defaults",
                    "inputSchema",
                    "limitation"
                  ],
                  "properties": {
                    "gameId": {
                      "type": "string",
                      "description": "Game route identifier.",
                      "enum": [
                        "a-handful-of-stars",
                        "azul",
                        "barony",
                        "bloc-by-bloc",
                        "burgle-bros",
                        "carcassonne",
                        "catan",
                        "chronicles-of-avel",
                        "civilization-new-dawn",
                        "clans-of-caledonia",
                        "clockwork-wars",
                        "codenames",
                        "cyclades",
                        "eight-minute-legends",
                        "el-dorado",
                        "empires-of-the-void-2",
                        "escape-from-atlantis",
                        "five-tribes",
                        "forbidden-desert",
                        "forbidden-island",
                        "forbidden-stars",
                        "gaia-project",
                        "ghost-stories",
                        "heroscape",
                        "kingdom-builder",
                        "labyrinth",
                        "rise-and-fall",
                        "scythe",
                        "small-world-realms",
                        "spirit-island",
                        "splendor",
                        "ticket-to-ride",
                        "tiny-epic-pirates",
                        "tiny-epic-zombies",
                        "twilight-imperium"
                      ]
                    },
                    "defaults": {
                      "type": "object"
                    },
                    "inputSchema": {
                      "type": "object"
                    },
                    "limitation": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Unknown game identifier.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/games.json": {
      "get": {
        "operationId": "listGames",
        "summary": "List playable games, documentation URLs and sharing support",
        "responses": {
          "200": {
            "description": "Games available in this build.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "games"
                  ],
                  "properties": {
                    "games": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Game"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/games/{gameId}.json": {
      "get": {
        "operationId": "getSetupGuide",
        "summary": "Read setup steps, limitations, related games and sharing instructions",
        "parameters": [
          {
            "name": "gameId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "description": "Game route identifier.",
              "enum": [
                "a-handful-of-stars",
                "azul",
                "barony",
                "bloc-by-bloc",
                "burgle-bros",
                "carcassonne",
                "catan",
                "chronicles-of-avel",
                "civilization-new-dawn",
                "clans-of-caledonia",
                "clockwork-wars",
                "codenames",
                "cyclades",
                "eight-minute-legends",
                "el-dorado",
                "empires-of-the-void-2",
                "escape-from-atlantis",
                "five-tribes",
                "forbidden-desert",
                "forbidden-island",
                "forbidden-stars",
                "gaia-project",
                "ghost-stories",
                "heroscape",
                "kingdom-builder",
                "labyrinth",
                "rise-and-fall",
                "scythe",
                "small-world-realms",
                "spirit-island",
                "splendor",
                "ticket-to-ride",
                "tiny-epic-pirates",
                "tiny-epic-zombies",
                "twilight-imperium"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Setup guide for one playable game.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SetupGuide"
                }
              }
            }
          },
          "404": {
            "description": "Unknown game.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Game": {
        "type": "object",
        "required": [
          "id",
          "name",
          "title",
          "description",
          "url",
          "markdownUrl",
          "guideUrl",
          "generationOptionsUrl",
          "supportsShareCode"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Game route identifier.",
            "enum": [
              "a-handful-of-stars",
              "azul",
              "barony",
              "bloc-by-bloc",
              "burgle-bros",
              "carcassonne",
              "catan",
              "chronicles-of-avel",
              "civilization-new-dawn",
              "clans-of-caledonia",
              "clockwork-wars",
              "codenames",
              "cyclades",
              "eight-minute-legends",
              "el-dorado",
              "empires-of-the-void-2",
              "escape-from-atlantis",
              "five-tribes",
              "forbidden-desert",
              "forbidden-island",
              "forbidden-stars",
              "gaia-project",
              "ghost-stories",
              "heroscape",
              "kingdom-builder",
              "labyrinth",
              "rise-and-fall",
              "scythe",
              "small-world-realms",
              "spirit-island",
              "splendor",
              "ticket-to-ride",
              "tiny-epic-pirates",
              "tiny-epic-zombies",
              "twilight-imperium"
            ]
          },
          "name": {
            "type": "string",
            "description": "Name of the board game."
          },
          "title": {
            "type": "string",
            "description": "Title of the setup tool."
          },
          "description": {
            "type": "string",
            "description": "Summary of the tool."
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Interactive browser tool."
          },
          "markdownUrl": {
            "type": "string",
            "format": "uri",
            "description": "Plain Markdown setup guide."
          },
          "guideUrl": {
            "type": "string",
            "format": "uri",
            "description": "Structured JSON setup guide."
          },
          "generationOptionsUrl": {
            "type": "string",
            "format": "uri",
            "description": "Per-game generation settings schema and defaults for MCP calls."
          },
          "supportsShareCode": {
            "type": "boolean",
            "description": "Whether the browser tool exposes a Share panel with a reusable setup code."
          }
        }
      },
      "SetupGuide": {
        "type": "object",
        "required": [
          "id",
          "name",
          "title",
          "description",
          "url",
          "markdownUrl",
          "guideUrl",
          "generationOptionsUrl",
          "supportsShareCode",
          "setupSteps",
          "setupNote",
          "relatedGameIds",
          "access",
          "sharing"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Game route identifier.",
            "enum": [
              "a-handful-of-stars",
              "azul",
              "barony",
              "bloc-by-bloc",
              "burgle-bros",
              "carcassonne",
              "catan",
              "chronicles-of-avel",
              "civilization-new-dawn",
              "clans-of-caledonia",
              "clockwork-wars",
              "codenames",
              "cyclades",
              "eight-minute-legends",
              "el-dorado",
              "empires-of-the-void-2",
              "escape-from-atlantis",
              "five-tribes",
              "forbidden-desert",
              "forbidden-island",
              "forbidden-stars",
              "gaia-project",
              "ghost-stories",
              "heroscape",
              "kingdom-builder",
              "labyrinth",
              "rise-and-fall",
              "scythe",
              "small-world-realms",
              "spirit-island",
              "splendor",
              "ticket-to-ride",
              "tiny-epic-pirates",
              "tiny-epic-zombies",
              "twilight-imperium"
            ]
          },
          "name": {
            "type": "string",
            "description": "Name of the board game."
          },
          "title": {
            "type": "string",
            "description": "Title of the setup tool."
          },
          "description": {
            "type": "string",
            "description": "Summary of the tool."
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Interactive browser tool."
          },
          "markdownUrl": {
            "type": "string",
            "format": "uri",
            "description": "Plain Markdown setup guide."
          },
          "guideUrl": {
            "type": "string",
            "format": "uri",
            "description": "Structured JSON setup guide."
          },
          "generationOptionsUrl": {
            "type": "string",
            "format": "uri",
            "description": "Per-game generation settings schema and defaults for MCP calls."
          },
          "supportsShareCode": {
            "type": "boolean",
            "description": "Whether the browser tool exposes a Share panel with a reusable setup code."
          },
          "setupSteps": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "string"
            }
          },
          "setupNote": {
            "type": "string",
            "description": "Tool-specific scope or setup considerations."
          },
          "relatedGameIds": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "Game route identifier.",
              "enum": [
                "a-handful-of-stars",
                "azul",
                "barony",
                "bloc-by-bloc",
                "burgle-bros",
                "carcassonne",
                "catan",
                "chronicles-of-avel",
                "civilization-new-dawn",
                "clans-of-caledonia",
                "clockwork-wars",
                "codenames",
                "cyclades",
                "eight-minute-legends",
                "el-dorado",
                "empires-of-the-void-2",
                "escape-from-atlantis",
                "five-tribes",
                "forbidden-desert",
                "forbidden-island",
                "forbidden-stars",
                "gaia-project",
                "ghost-stories",
                "heroscape",
                "kingdom-builder",
                "labyrinth",
                "rise-and-fall",
                "scythe",
                "small-world-realms",
                "spirit-island",
                "splendor",
                "ticket-to-ride",
                "tiny-epic-pirates",
                "tiny-epic-zombies",
                "twilight-imperium"
              ]
            }
          },
          "access": {
            "type": "object",
            "required": [
              "authentication",
              "cost",
              "browserRequiredForGeneration"
            ],
            "properties": {
              "authentication": {
                "const": "none"
              },
              "cost": {
                "const": "free"
              },
              "browserRequiredForGeneration": {
                "const": false
              }
            }
          },
          "generation": {
            "type": "object",
            "required": [
              "mcpUrl",
              "tool",
              "optionsUrl"
            ],
            "properties": {
              "mcpUrl": {
                "type": "string",
                "format": "uri"
              },
              "tool": {
                "const": "boardshuffle_generate_setup"
              },
              "optionsUrl": {
                "type": "string",
                "format": "uri"
              }
            }
          },
          "sharing": {
            "type": "object",
            "required": [
              "supported",
              "instructions"
            ],
            "properties": {
              "supported": {
                "type": "boolean"
              },
              "queryParameter": {
                "const": "b"
              },
              "instructions": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  }
}