{"openapi":"3.1.0","info":{"title":"Tatanka Goods booking API","version":"1.5.0","summary":"Find live appointment openings at a Bozeman, Montana barbershop and hand the customer a prefilled booking link.","description":"Tatanka Goods is an appointment-only barbershop at 611 N Wallace Ave, Bozeman, MT.\n\nHow to book for someone, in three steps:\n1. GET /api/booking/services to see what's bookable (or use one of the known names: The Classic Haircut, Father & Son, First Responder, Beard Trim & Lineup, Hot Towel Straight Razor Shave).\n2. GET /api/availability with a service and optionally a barber. Every open time comes back with a `bookUrl`.\n3. Give the customer the `bookUrl` for the time they pick. It opens the booking page with barber, service, and time already chosen; they add a card and tap confirm.\n\nYou cannot complete a booking through this API. A card on file is required and it is only ever entered by the customer on the site, so nothing here can create an appointment. That is deliberate.\n\nAll times are ISO 8601 UTC; the shop runs on America/Denver. Requests are rate limited per IP. Weddings, events, and house calls are arranged by email (contact@tatanka-goods.com), not online.","contact":{"name":"Tatanka Goods","url":"https://www.tatanka-goods.com/contact","email":"contact@tatanka-goods.com"}},"servers":[{"url":"https://www.tatanka-goods.com"}],"paths":{"/api/availability":{"get":{"operationId":"findAvailability","summary":"Live appointment openings, each with a prefilled booking link","description":"Real-time availability from the shop's Square calendar. Only offer times returned here — they can be taken by someone else at any moment.","parameters":[{"name":"service","in":"query","required":true,"description":"Service name or Square id. Fuzzy-matched on name.","schema":{"type":"string","examples":["The Classic Haircut","Father & Son","First Responder","Beard Trim & Lineup","Hot Towel Straight Razor Shave"]}},{"name":"barber","in":"query","required":false,"description":"Barber slug or first name. Omit for any barber.","schema":{"type":"string","enum":["nick-shaffer","justin"]}},{"name":"from","in":"query","required":false,"description":"Start of the search window. Defaults to now.","schema":{"type":"string","examples":["2026-09-21","2026-09-21T16:00:00Z"]}},{"name":"days","in":"query","required":false,"description":"Days to search from `from`.","schema":{"type":"integer","minimum":1,"maximum":31,"default":14}},{"name":"to","in":"query","required":false,"description":"End of the search window. Overrides `days`.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":40}}],"responses":{"200":{"description":"Open times, soonest first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Availability"}}}},"400":{"description":"Missing or invalid parameter. The body repeats the usage."},"404":{"description":"No service matched. The body lists the available service names."},"429":{"description":"Rate limited. Retry after the Retry-After header."},"503":{"description":"Online booking is temporarily unavailable."}}}},"/api/booking/services":{"get":{"operationId":"listServices","summary":"Bookable services with Square ids, durations, and prices","description":"Each barber has their own copy of a service with its own price and duration, so the same name can appear more than once.","responses":{"200":{"description":"The bookable service list.","content":{"application/json":{"schema":{"type":"object","properties":{"configured":{"type":"boolean"},"services":{"type":"array","items":{"$ref":"#/components/schemas/Service"}}}}}}},"503":{"description":"Online booking is temporarily unavailable."}}}},"/book":{"get":{"operationId":"openBookingPage","summary":"The booking page, optionally prefilled (this is the `bookUrl`)","description":"Not an API — the page the customer opens to finish. With these parameters it lands on the final step with everything chosen, leaving only the card and the confirm tap. Use the `bookUrl` from /api/availability rather than building this by hand.","parameters":[{"name":"barber","in":"query","schema":{"type":"string","enum":["nick-shaffer","justin"]}},{"name":"service","in":"query","schema":{"type":"string"},"description":"Square service variation id."},{"name":"start","in":"query","schema":{"type":"string"},"description":"ISO 8601 start time."},{"name":"firstName","in":"query","schema":{"type":"string"}},{"name":"lastName","in":"query","schema":{"type":"string"}},{"name":"phone","in":"query","schema":{"type":"string"}},{"name":"email","in":"query","schema":{"type":"string"}},{"name":"via","in":"query","schema":{"type":"string","const":"agent"},"description":"Marks the booking as assistant-assisted on the shop's calendar."}],"responses":{"200":{"description":"The booking page, in HTML."}}}}},"components":{"schemas":{"Availability":{"type":"object","properties":{"shop":{"type":"string"},"service":{"type":"string","description":"The matched service name."},"barber":{"type":"string","description":"Slug, or 'any'."},"timezone":{"type":"string","const":"America/Denver"},"searched":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}}},"count":{"type":"integer"},"slots":{"type":"array","items":{"$ref":"#/components/schemas/Slot"}},"howToBook":{"type":"string","description":"Plain-language next step. Safe to relay."},"note":{"type":"string"}}},"Slot":{"type":"object","properties":{"startAt":{"type":"string","description":"ISO 8601 UTC.","examples":["2026-09-21T17:00:00Z"]},"localTime":{"type":"string","description":"Ready to read aloud.","examples":["Mon, Sep 21, 11:00 AM MDT"]},"barber":{"type":"string","enum":["nick-shaffer","justin"]},"barberName":{"type":"string"},"durationMinutes":{"type":"integer"},"price":{"type":"string","examples":["$70"]},"bookUrl":{"type":"string","description":"Give this to the customer. Opens the booking page with barber, service, and time chosen; they add a card and confirm."}}},"Service":{"type":"object","properties":{"id":{"type":"string","description":"Square service variation id."},"name":{"type":"string"},"description":{"type":"string"},"durationMinutes":{"type":"integer"},"price":{"type":"string"},"teamMemberIds":{"type":"array","items":{"type":"string"}}}}}},"externalDocs":{"description":"How AI assistants book here, including the MCP connector","url":"https://www.tatanka-goods.com/agents"}}