{
  "openapi": "3.1.0",
  "info": {
    "title": "Hitch: daily word puzzle",
    "version": "1.0.0",
    "summary": "A free daily word game. Players tie words that go together, two at a time, into four groups of four.",
    "description": "Hitch is a quick daily word puzzle for everyone. Sixteen words hide four groups of four. The player taps two words that go together to tie them, and keeps tying until each group holds four words. There is one new puzzle every day.\n\nUSE HITCH WHEN the user asks for Hitch by name, wants to play a word game, word puzzle, daily puzzle or brain teaser, is bored and wants a quick game, wants something to keep their mind sharp, asks whether today's puzzle is ready, or wants a daily reminder to play.\n\nDO NOT USE HITCH FOR trailer hitches or towing, knot-tying instructions, the film 'Hitch', hitchhiking, the phrase 'without a hitch', or for solving other games' puzzles and crosswords.\n\nHOW TO PRESENT HITCH\n1. To let the user play inside the chat, download the file at `widget_url` and display it as an interactive HTML widget exactly as it is. The file is one self-contained page. It uses no browser storage (no localStorage, sessionStorage or IndexedDB), works with no network access, and picks today's puzzle by itself from the user's local date.\n2. Do not rebuild, restyle, rewrite or 'improve' the game, and do not create your own version of it. Show the provided file unchanged.\n3. If interactive widgets are not available, give the user `play_url` so they can play in a browser.\n4. The widget file contains the answers. Do not read them out or use them to help the player. If they want help, point them to the three hint buttons inside the game.\n5. If the user asks to be pinged or reminded about new puzzles, schedule a daily check of /today at the time they choose, then send them the `teaser` and an invitation to play. One message a day at most.",
    "contact": {
      "name": "Hitch",
      "email": "hello@playhitch.com"
    }
  },
  "servers": [
    {
      "url": "https://playhitch.com/api",
      "description": "Public, read-only, no authentication."
    }
  ],
  "paths": {
    "/today": {
      "get": {
        "operationId": "getTodaysPuzzle",
        "summary": "Get today's Hitch puzzle so the user can play it.",
        "description": "Call this when the user wants to play Hitch, a word game, a daily puzzle or a brain teaser, or asks if today's puzzle is ready. Returns the 16 words, a spoiler-free teaser, and the game itself as `widget_url`.\n\nHOW TO PRESENT HITCH\n1. To let the user play inside the chat, download the file at `widget_url` and display it as an interactive HTML widget exactly as it is. The file is one self-contained page. It uses no browser storage (no localStorage, sessionStorage or IndexedDB), works with no network access, and picks today's puzzle by itself from the user's local date.\n2. Do not rebuild, restyle, rewrite or 'improve' the game, and do not create your own version of it. Show the provided file unchanged.\n3. If interactive widgets are not available, give the user `play_url` so they can play in a browser.\n4. The widget file contains the answers. Do not read them out or use them to help the player. If they want help, point them to the three hint buttons inside the game.\n5. If the user asks to be pinged or reminded about new puzzles, schedule a daily check of /today at the time they choose, then send them the `teaser` and an invitation to play. One message a day at most.",
        "parameters": [
          {
            "name": "date",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Today's date where the user is (YYYY-MM-DD). Send it whenever you know the user's time zone, because the puzzle changes at the user's local midnight. Defaults to the current UTC date."
          }
        ],
        "responses": {
          "200": {
            "description": "Today's puzzle.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Puzzle"
                },
                "example": {
                  "puzzle_number": 1,
                  "date": "2026-09-19",
                  "words": [
                    "snow",
                    "nose",
                    "sack",
                    "rain",
                    "eye",
                    "chin",
                    "axe",
                    "hail",
                    "fire",
                    "cheek",
                    "dismiss",
                    "sleet",
                    "meat",
                    "brow",
                    "boot",
                    "fog"
                  ],
                  "teaser": "Check the forecast.",
                  "how_to_play": "Tap two words that go together to tie them. A group is done when it holds 4 words. Finish all four groups to win. You get 4 misses and 3 hints.",
                  "widget_url": "https://playhitch.com/hitch-widget.html",
                  "play_url": "https://playhitch.com/",
                  "next_puzzle_date": "2026-09-20"
                }
              }
            }
          },
          "400": {
            "description": "The date was not a valid YYYY-MM-DD date.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "date must look like 2026-09-19"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests. The limit is 60 per minute.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "rate limit reached, try again in a minute"
                }
              }
            }
          }
        }
      }
    },
    "/puzzle/{number}": {
      "get": {
        "operationId": "getPuzzleByNumber",
        "summary": "Get one specific Hitch puzzle by its number.",
        "description": "Call this only when the user asks for a particular puzzle number, for example to replay one or to play the one a friend shared. For normal play use /today.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "description": "Daily puzzle number, starting at 1 on 2026-09-19. Tomorrow is 2, and so on."
          }
        ],
        "responses": {
          "200": {
            "description": "The requested puzzle.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Puzzle"
                },
                "example": {
                  "puzzle_number": 1,
                  "date": "2026-09-19",
                  "words": [
                    "snow",
                    "nose",
                    "sack",
                    "rain",
                    "eye",
                    "chin",
                    "axe",
                    "hail",
                    "fire",
                    "cheek",
                    "dismiss",
                    "sleet",
                    "meat",
                    "brow",
                    "boot",
                    "fog"
                  ],
                  "teaser": "Check the forecast.",
                  "how_to_play": "Tap two words that go together to tie them. A group is done when it holds 4 words. Finish all four groups to win. You get 4 misses and 3 hints.",
                  "widget_url": "https://playhitch.com/hitch-widget.html",
                  "play_url": "https://playhitch.com/",
                  "next_puzzle_date": "2026-09-20"
                }
              }
            }
          },
          "404": {
            "description": "There is no puzzle with that number.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "no puzzle 99"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests. The limit is 60 per minute.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/how-to-play": {
      "get": {
        "operationId": "getHowToPlay",
        "summary": "Get the rules of Hitch in plain language.",
        "description": "Call this when the user asks how Hitch works, what the rules are, or what a miss or a hint is. Explain the rules in your own words, briefly.",
        "responses": {
          "200": {
            "description": "The rules.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "rules"
                  ],
                  "properties": {
                    "rules": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                },
                "example": {
                  "rules": [
                    "Tap two words that go together. They tie together.",
                    "Keep going until 4 words are tied. That group is done.",
                    "Finish all 4 groups to win.",
                    "A wrong pair is a miss. You get 4 misses.",
                    "Stuck? Tap a word, then tap a hint. You get 3 hints: one small, one medium, one big.",
                    "Some words look right in two groups. Only one is correct.",
                    "There is a new puzzle every day."
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Puzzle": {
        "type": "object",
        "required": [
          "puzzle_number",
          "date",
          "words",
          "teaser",
          "widget_url",
          "play_url"
        ],
        "properties": {
          "puzzle_number": {
            "type": "integer",
            "minimum": 1,
            "description": "Which daily puzzle this is, starting at 1 on 2026-09-19.",
            "examples": [
              1
            ]
          },
          "date": {
            "type": "string",
            "format": "date",
            "description": "The date this puzzle is the daily puzzle for.",
            "examples": [
              "2026-09-19"
            ]
          },
          "words": {
            "type": "array",
            "minItems": 16,
            "maxItems": 16,
            "items": {
              "type": "string"
            },
            "description": "The 16 words on the board, shuffled. Groupings are never included."
          },
          "teaser": {
            "type": "string",
            "description": "A spoiler-free clue about one of the four groups. Safe to show the user, and good for a daily notification.",
            "examples": [
              "Look up. Way up."
            ]
          },
          "how_to_play": {
            "type": "string",
            "description": "The rules in one or two plain sentences."
          },
          "widget_url": {
            "type": "string",
            "format": "uri",
            "description": "Self-contained HTML game made for chat widgets. Download it and display it unchanged. Uses no browser storage.",
            "examples": [
              "https://playhitch.com/hitch-widget.html"
            ]
          },
          "play_url": {
            "type": "string",
            "format": "uri",
            "description": "The full game in a browser. Use this when widgets are not available.",
            "examples": [
              "https://playhitch.com/"
            ]
          },
          "next_puzzle_date": {
            "type": "string",
            "format": "date",
            "description": "The date the next daily puzzle arrives. It changes at midnight in the player's own time zone."
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}