{"openapi":"3.1.0","info":{"title":"Booking API (demo)","version":"2.0.0","summary":"A 2k3software demo project, with fictitious data.","description":"A booking REST API for a fictitious studio with a single practitioner. Each key opens a private sandbox with sample services and bookings, deleted after 24 hours. Times use RFC 3339 in the Lisbon time zone. Errors use the Problem Details format (RFC 9457). Do not use real personal data.","contact":{"name":"2k3software","url":"https://2k3software.com/en/#contact"}},"servers":[{"url":"https://api-demo.2k3software.com"}],"tags":[{"name":"keys","description":"Demo keys and sandbox status."},{"name":"catalog","description":"Services and free slots."},{"name":"bookings","description":"Create, read, change and cancel bookings."}],"security":[{"bearer":[]}],"paths":{"/v1/health":{"get":{"operationId":"health","tags":["keys"],"security":[],"summary":"Service status","description":"No key needed.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"version":{"type":"string"},"time":{"type":"string","format":"date-time"}}}}}}}}},"/v1/keys":{"post":{"operationId":"createKey","tags":["keys"],"security":[],"summary":"Request a demo key","description":"Creates a sandbox with 3 services and 3 sample bookings. The key lasts 24 hours; then everything is deleted. Limit: 5 keys per minute per IP.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"locale":{"type":"string","enum":["pt","en"],"description":"Language for names and error messages."}}},"example":{"locale":"en"}}}},"responses":{"201":{"description":"Key created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Key"}}}},"422":{"$ref":"#/components/responses/Validation"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/me":{"get":{"operationId":"me","tags":["keys"],"summary":"My sandbox status","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Me"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/services":{"get":{"operationId":"listServices","tags":["catalog"],"summary":"List services","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Service"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/availability":{"get":{"operationId":"availability","tags":["catalog"],"summary":"Free slots for a service on a day","description":"Opening hours: Monday to Friday 9:00-13:00 and 14:00-18:00, Saturday 9:00-13:00 (Lisbon time), on a 30-minute grid.","parameters":[{"name":"service_id","in":"query","required":true,"schema":{"type":"string"},"example":"srv_consulta"},{"name":"date","in":"query","required":true,"description":"Local day, YYYY-MM-DD.","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Availability"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/Validation"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/bookings":{"get":{"operationId":"listBookings","tags":["bookings"],"summary":"List bookings","description":"Sorted by start time, with cursor pagination.","parameters":[{"name":"from","in":"query","description":"First day (default: today).","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","description":"Last day, inclusive (default: from + 30 days; at most 62 days).","schema":{"type":"string","format":"date"}},{"name":"status","in":"query","schema":{"type":"string","enum":["confirmed","cancelled"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"cursor","in":"query","description":"The next_cursor from the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Booking"}},"next_cursor":{"type":["string","null"]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/Validation"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"createBooking","tags":["bookings"],"summary":"Create a booking","description":"It must fit within opening hours and cannot overlap another confirmed booking. With the Idempotency-Key header, repeating the same request returns the same booking instead of creating another.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. 8 to 64 letters, digits, - or _.","example":"pedido-0001","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,64}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BookingInput"},"example":{"service_id":"srv_consulta","start":"2026-12-01T10:00:00Z","customer":{"name":"Sample Customer"},"notes":"First visit."}}}},"responses":{"201":{"description":"Booking created","headers":{"Location":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Booking"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"409":{"$ref":"#/components/responses/Conflict"},"415":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/Validation"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/bookings/{id}":{"get":{"operationId":"getBooking","tags":["bookings"],"parameters":[{"name":"id","in":"path","required":true,"description":"Booking id, e.g. bk_k7m2p9qa.","schema":{"type":"string","pattern":"^bk_[a-z0-9]+$"}}],"summary":"Get a booking","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Booking"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"patch":{"operationId":"updateBooking","tags":["bookings"],"parameters":[{"name":"id","in":"path","required":true,"description":"Booking id, e.g. bk_k7m2p9qa.","schema":{"type":"string","pattern":"^bk_[a-z0-9]+$"}}],"summary":"Update a booking","description":"Change the time (reschedule), the name or the notes. The service cannot change; cancel and create another instead.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BookingPatch"},"example":{"start":"2026-12-01T11:00:00Z"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Booking"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Validation"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/bookings/{id}/cancel":{"post":{"operationId":"cancelBooking","tags":["bookings"],"parameters":[{"name":"id","in":"path","required":true,"description":"Booking id, e.g. bk_k7m2p9qa.","schema":{"type":"string","pattern":"^bk_[a-z0-9]+$"}}],"summary":"Cancel a booking","description":"The booking gets status cancelled and the slot becomes free again.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Booking"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Key from POST /v1/keys."}},"schemas":{"Key":{"type":"object","properties":{"key":{"type":"string","example":"demo_..."},"expires_at":{"type":"string","format":"date-time"},"locale":{"type":"string"},"note":{"type":"string"}}},"Me":{"type":"object","properties":{"locale":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"},"bookings":{"type":"integer"},"limits":{"type":"object"}}},"Service":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"duration_minutes":{"type":"integer"}}},"Slot":{"type":"object","properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}}},"Availability":{"type":"object","properties":{"service_id":{"type":"string"},"date":{"type":"string","format":"date"},"timezone":{"type":"string"},"closed":{"type":"boolean"},"slots":{"type":"array","items":{"$ref":"#/components/schemas/Slot"}}}},"Booking":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["confirmed","cancelled"]},"service":{"$ref":"#/components/schemas/Service"},"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"},"customer":{"type":"object","properties":{"name":{"type":"string"}}},"notes":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"cancelled_at":{"type":["string","null"],"format":"date-time"}}},"BookingInput":{"type":"object","additionalProperties":false,"required":["service_id","start","customer"],"properties":{"service_id":{"type":"string"},"start":{"type":"string","format":"date-time","description":"RFC 3339 with offset. On the hour or half hour."},"customer":{"type":"object","additionalProperties":false,"required":["name"],"properties":{"name":{"type":"string","minLength":2,"maxLength":60,"description":"Fictitious name. Emails and phone numbers are rejected."}}},"notes":{"type":["string","null"],"maxLength":280}}},"BookingPatch":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"start":{"type":"string","format":"date-time"},"customer":{"$ref":"#/components/schemas/BookingInput/properties/customer"},"notes":{"type":["string","null"],"maxLength":280}}},"Problem":{"type":"object","description":"RFC 9457","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"code":{"type":"string"},"errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"request_id":{"type":"string"}}}},"responses":{"BadRequest":{"description":"Invalid JSON or wrong content type","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Unauthorized":{"description":"Missing, invalid or expired key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"NotFound":{"description":"Booking not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Conflict":{"description":"Slot taken, booking cancelled or sandbox full","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Validation":{"description":"Invalid fields (see errors)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"RateLimited":{"description":"Too many requests (60 per minute per key)","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}