{
  "openapi": "3.1.0",
  "info": {
    "title": "joschi Pizza Bistro Reservations API",
    "version": "1.0.0",
    "description": "Create table reservation requests for joschi Pizza Bistro in Hamburg. Always call the capabilities endpoint first to discover valid areas, party size limits, and date-specific available times before creating a reservation."
  },
  "servers": [
    {
      "url": "https://klapp.pizza"
    }
  ],
  "paths": {
    "/api/reservations/capabilities": {
      "get": {
        "operationId": "getReservationCapabilities",
        "summary": "Get reservation booking rules and available times",
        "description": "Returns required fields, party size limits, opening rules, and optionally the available reservation times for a specific date in Europe/Berlin timezone.",
        "parameters": [
          {
            "name": "date",
            "in": "query",
            "required": false,
            "description": "Optional reservation date in YYYY-MM-DD format. When provided, the response includes available_times for that date.",
            "schema": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
              "examples": [
                "2026-04-17"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Reservation capabilities returned successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReservationCapabilities"
                }
              }
            }
          },
          "400": {
            "description": "Invalid date format.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/reservations": {
      "post": {
        "operationId": "createReservation",
        "summary": "Create a reservation request",
        "description": "Creates a pending reservation request. Before calling this action, confirm the reservation details with the customer and fetch valid times via getReservationCapabilities.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateReservationRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Reservation request created successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateReservationResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation error or invalid reservation input.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ReservationArea": {
        "type": "string",
        "enum": [
          "innen",
          "aussen"
        ],
        "description": "Reservation area. Use 'aussen' for outdoor seating."
      },
      "AgentMetadata": {
        "type": "object",
        "description": "Optional metadata describing the AI or automation that is submitting the reservation on behalf of the customer.",
        "additionalProperties": false,
        "properties": {
          "name": {
            "type": "string",
            "description": "Name of the agent or automation submitting the reservation."
          },
          "type": {
            "type": "string",
            "description": "Agent type, for example 'ai-agent'."
          },
          "customer_confirmed": {
            "type": "boolean",
            "description": "Whether the customer explicitly confirmed the reservation details."
          },
          "customer_reference": {
            "type": "string",
            "description": "Optional reference to the chat, booking session, or confirmation record."
          },
          "notes": {
            "type": "string",
            "description": "Optional internal note from the submitting agent."
          }
        },
        "required": [
          "name"
        ]
      },
      "CreateReservationRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "guest_name",
          "guest_phone",
          "guest_email",
          "party_size",
          "area",
          "reservation_date",
          "reservation_time"
        ],
        "properties": {
          "guest_name": {
            "type": "string",
            "description": "Customer full name."
          },
          "guest_phone": {
            "type": "string",
            "description": "Customer phone number."
          },
          "guest_email": {
            "type": "string",
            "format": "email",
            "description": "Customer email address."
          },
          "party_size": {
            "type": "integer",
            "minimum": 1,
            "description": "Number of guests. The exact maximum depends on the selected area."
          },
          "area": {
            "$ref": "#/components/schemas/ReservationArea"
          },
          "reservation_date": {
            "type": "string",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
            "description": "Reservation date in YYYY-MM-DD format."
          },
          "reservation_time": {
            "type": "string",
            "pattern": "^\\d{2}:\\d{2}(:\\d{2})?$",
            "description": "Reservation time in 24-hour format. Use a time returned by getReservationCapabilities, for example '18:30' or '18:30:00'."
          },
          "notes": {
            "type": "string",
            "description": "Optional customer message, allergies, or seating request."
          },
          "agent": {
            "$ref": "#/components/schemas/AgentMetadata"
          }
        },
        "examples": [
          {
            "guest_name": "Max Mustermann",
            "guest_phone": "+49 151 12345678",
            "guest_email": "max@example.com",
            "party_size": 2,
            "area": "innen",
            "reservation_date": "2026-04-17",
            "reservation_time": "18:30:00",
            "notes": "Fensterplatz wenn moeglich",
            "agent": {
              "name": "joschi booking assistant",
              "type": "ai-agent",
              "customer_confirmed": true,
              "customer_reference": "chat-123",
              "notes": "Submitted after customer confirmation."
            }
          }
        ]
      },
      "ReservationRecord": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "status": {
            "type": "string"
          },
          "source": {
            "type": "string"
          },
          "guest_name": {
            "type": "string"
          },
          "guest_phone": {
            "type": "string"
          },
          "guest_email": {
            "type": "string",
            "format": "email"
          },
          "party_size": {
            "type": "integer"
          },
          "area": {
            "$ref": "#/components/schemas/ReservationArea"
          },
          "reservation_date": {
            "type": "string",
            "format": "date"
          },
          "reservation_time": {
            "type": "string"
          },
          "notes": {
            "type": "string"
          },
          "metadata": {
            "type": "object",
            "additionalProperties": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "CreateReservationResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "reservation": {
            "$ref": "#/components/schemas/ReservationRecord"
          },
          "mailWarning": {
            "type": [
              "string",
              "null"
            ],
            "description": "Optional warning when the reservation was saved but email notifications were not sent."
          }
        },
        "required": [
          "reservation",
          "mailWarning"
        ]
      },
      "AreaOption": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "value": {
            "$ref": "#/components/schemas/ReservationArea"
          },
          "label": {
            "type": "string"
          },
          "max_party_size": {
            "type": "integer"
          }
        },
        "required": [
          "value",
          "label",
          "max_party_size"
        ]
      },
      "OpeningRule": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "days": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "start": {
            "type": "string"
          },
          "end": {
            "type": "string"
          },
          "interval_minutes": {
            "type": "integer"
          }
        },
        "required": [
          "days",
          "start",
          "end",
          "interval_minutes"
        ]
      },
      "ReservationCapabilities": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "timezone": {
            "type": "string"
          },
          "booking_url": {
            "type": "string",
            "format": "uri"
          },
          "create_endpoint": {
            "type": "string"
          },
          "lookup_endpoint": {
            "type": "string"
          },
          "party_size_limits": {
            "type": "object",
            "additionalProperties": {
              "type": "integer"
            }
          },
          "area_options": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AreaOption"
            }
          },
          "opening_rules": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OpeningRule"
            }
          },
          "required_fields": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "optional_fields": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "agent_fields": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "requested_date": {
            "type": "string",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
          },
          "available_times": {
            "type": "array",
            "items": {
              "type": "string",
              "pattern": "^\\d{2}:\\d{2}$"
            }
          }
        },
        "required": [
          "timezone",
          "booking_url",
          "create_endpoint",
          "lookup_endpoint",
          "party_size_limits",
          "area_options",
          "opening_rules",
          "required_fields",
          "optional_fields",
          "agent_fields"
        ]
      },
      "ErrorResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "error": {
            "type": "string"
          }
        },
        "required": [
          "error"
        ]
      }
    }
  }
}