{
    "openapi": "3.1.0",
    "info": {
        "title": "Talent Studio | Online Venue Booking & Event Reservations - Agentic Booking API",
        "description": "Official AI Agent API for Talent Studio | Online Venue Booking & Event Reservations at Talent Studio. Supports live catalog discovery (including private add-on sections/specialists), real-time slot and add-on availability checks, atomic multi-slot booking creation with optional child add-on sections, and 12-digit UPI UTR verification.",
        "version": "1.2.0"
    },
    "servers": [
        {
            "url": "https://talentstudio.vps14.indiax.com",
            "description": "Talent Studio | Online Venue Booking & Event Reservations Production Server (Vadodara)"
        }
    ],
    "paths": {
        "/api/agent.php": {
            "get": {
                "operationId": "queryBookKaroAgentApi",
                "summary": "Fetch live catalog (including private add-ons), check date/section/add-on availability, or look up booking status",
                "description": "Execute read-only queries against BookKaro. Use action='catalog' to discover active events, rental options, public sections, and private_addon_sections; action='check_availability' to verify busy slot blocks and discover available_private_addons for a specific date and time window; or action='booking_status' to query an existing reservation and its attached add-ons.",
                "parameters": [
                    {
                        "name": "action",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "catalog",
                                "check_availability",
                                "booking_status"
                            ],
                            "default": "catalog"
                        },
                        "description": "The specific query action to perform."
                    },
                    {
                        "name": "category",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "all",
                                "events",
                                "karaoke",
                                "hourly",
                                "sections",
                                "addons",
                                "expos"
                            ],
                            "default": "all"
                        },
                        "description": "Used when action='catalog' to filter catalog items (use 'addons' or 'all' to view private_addon_sections)."
                    },
                    {
                        "name": "date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "format": "date"
                        },
                        "description": "Required when action='check_availability'. Target date in YYYY-MM-DD format."
                    },
                    {
                        "name": "start_time",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$"
                        },
                        "description": "Optional when action='check_availability' (HH:MM in 24-hour IST). When provided with slots_or_hours, returns available_private_addons scoped to that exact booking window."
                    },
                    {
                        "name": "slots_or_hours",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "default": 1
                        },
                        "description": "Optional duration in hours or section slots when action='check_availability'."
                    },
                    {
                        "name": "section_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Optional section ID for filtering catalog items or checking specific studio section availability."
                    },
                    {
                        "name": "booking_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Required when action='booking_status'."
                    },
                    {
                        "name": "email",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "format": "email"
                        },
                        "description": "Required when action='booking_status'. Email used during booking."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful retrieval of catalog, slot/add-on availability, or booking record."
                    }
                }
            }
        },
        "/api/agent.php?action=create_booking": {
            "post": {
                "operationId": "createBookKaroBooking",
                "summary": "Create a new booking for an event, studio section, hourly venue block, or expo booth (with optional private add-on sections)",
                "description": "Executes an atomic reservation and returns payment checkout links or instant free ticket confirmation. Always call queryBookKaroAgentApi(action='check_availability') before booking hourly or section slots. For 'hourly' and 'section' bookings, you can optionally attach one or more private add-on sections via the `addons` array.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "booking_category",
                                    "user_name",
                                    "user_email",
                                    "user_phone"
                                ],
                                "properties": {
                                    "action": {
                                        "type": "string",
                                        "enum": [
                                            "create_booking"
                                        ],
                                        "default": "create_booking",
                                        "description": "Action identifier (defaults to create_booking)."
                                    },
                                    "booking_category": {
                                        "type": "string",
                                        "enum": [
                                            "event",
                                            "section",
                                            "hourly",
                                            "expo"
                                        ],
                                        "description": "Category of primary reservation."
                                    },
                                    "user_name": {
                                        "type": "string",
                                        "description": "Full legal or contact name of the customer."
                                    },
                                    "user_email": {
                                        "type": "string",
                                        "format": "email",
                                        "description": "Contact email address for receipt and ticket delivery."
                                    },
                                    "user_phone": {
                                        "type": "string",
                                        "pattern": "^[0-9]{10}$",
                                        "description": "10-digit mobile contact number."
                                    },
                                    "event_id": {
                                        "type": "integer",
                                        "description": "ID of the target event from the catalog (required when booking_category='event')."
                                    },
                                    "section_id": {
                                        "type": "integer",
                                        "description": "ID of the studio section from the catalog (required when booking_category='section')."
                                    },
                                    "booth_type_id": {
                                        "type": "integer",
                                        "description": "ID of the expo booth from the catalog (required when booking_category='expo')."
                                    },
                                    "booking_date": {
                                        "type": "string",
                                        "format": "date",
                                        "description": "Date of reservation in YYYY-MM-DD format (required for 'hourly' and 'section')."
                                    },
                                    "booking_time": {
                                        "type": "string",
                                        "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$",
                                        "description": "Starting time in 24-hour IST (HH:MM format). Must be at least 60 mins in the future."
                                    },
                                    "slots_or_hours": {
                                        "type": "integer",
                                        "minimum": 1,
                                        "default": 1,
                                        "description": "Number of seats/tickets (for 'event'), duration slots (for 'section'), or hours (for 'hourly')."
                                    },
                                    "addons": {
                                        "type": "array",
                                        "description": "Optional list of private add-on sections (is_active=0) to attach as child items inside the main booking's time window (supported for 'hourly' and 'section' bookings).",
                                        "items": {
                                            "type": "object",
                                            "required": [
                                                "section_id"
                                            ],
                                            "properties": {
                                                "section_id": {
                                                    "type": "integer",
                                                    "description": "ID of the private add-on section from `private_addon_sections` / `available_private_addons`."
                                                },
                                                "start_time": {
                                                    "type": "string",
                                                    "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$",
                                                    "description": "Start time for this add-on in 24-hour IST (HH:MM). Defaults to the main booking_time if omitted. Must fall within the main booking window."
                                                },
                                                "slots": {
                                                    "type": "integer",
                                                    "minimum": 1,
                                                    "default": 1,
                                                    "description": "Number of slots to book for this add-on. End time must not exceed the main booking's end time."
                                                }
                                            }
                                        }
                                    },
                                    "space_format": {
                                        "type": "string",
                                        "enum": [
                                            "bare",
                                            "shell"
                                        ],
                                        "default": "bare",
                                        "description": "Booth furnishing choice for expo bookings."
                                    },
                                    "custom_area_booked": {
                                        "type": "number",
                                        "description": "Area in square units if booking a custom-sized booth stall."
                                    },
                                    "company_name": {
                                        "type": "string",
                                        "description": "Optional organization or corporate entity name for tax invoices."
                                    },
                                    "customer_gstin": {
                                        "type": "string",
                                        "pattern": "^[0-9]{2}[A-Z]{5}[0-9]{4}[A-Z]{1}[1-9A-Z]{1}Z[0-9A-Z]{1}$",
                                        "description": "Optional 15-character Indian GSTIN for tax invoice generation."
                                    },
                                    "attendees": {
                                        "type": "array",
                                        "description": "Optional list of attendee details when an event requires individual attendee info.",
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "name": {
                                                    "type": "string"
                                                },
                                                "email": {
                                                    "type": "string",
                                                    "format": "email"
                                                },
                                                "phone": {
                                                    "type": "string"
                                                },
                                                "info_1": {
                                                    "type": "string"
                                                },
                                                "info_2": {
                                                    "type": "string"
                                                },
                                                "info_3": {
                                                    "type": "string"
                                                },
                                                "info_4": {
                                                    "type": "string"
                                                },
                                                "info_5": {
                                                    "type": "string"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Booking (and any attached child add-on sections) created atomically and awaiting payment (or confirmed if free)."
                    },
                    "400": {
                        "description": "Validation failure, parameter mismatch, or double-booking slot collision."
                    }
                }
            }
        },
        "/api/agent.php?action=submit_utr": {
            "post": {
                "operationId": "submitBookKaroUtr",
                "summary": "Submit a 12-digit UPI UTR to lock a pending booking for admin verification",
                "description": "Verifies the booking_id and user_email against the pending reservation, records the 12-digit numeric UPI UTR transaction reference, emails the provisional receipt, and returns the formatted receipt markdown and URL.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "booking_id",
                                    "user_email",
                                    "utr"
                                ],
                                "properties": {
                                    "action": {
                                        "type": "string",
                                        "enum": [
                                            "submit_utr"
                                        ],
                                        "default": "submit_utr",
                                        "description": "Action identifier (defaults to submit_utr)."
                                    },
                                    "booking_id": {
                                        "type": "integer",
                                        "description": "The numeric booking ID returned when the reservation was created."
                                    },
                                    "user_email": {
                                        "type": "string",
                                        "format": "email",
                                        "description": "The exact customer email address used when creating the booking."
                                    },
                                    "utr": {
                                        "type": "string",
                                        "pattern": "^[0-9]{12}$",
                                        "description": "Exact 12-digit numeric UPI Unique Transaction Reference number."
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Payment UTR recorded and provisional receipt returned."
                    },
                    "400": {
                        "description": "Missing or invalid booking_id, user_email, or 12-digit UTR."
                    },
                    "404": {
                        "description": "No matching booking found for the provided booking_id and user_email."
                    }
                }
            }
        }
    }
}