{"openapi":"3.1.0","info":{"title":"Khotan agent demo booking API","version":"1.1.0","description":"A two-step API for AI agents to check Khotan's availability, prepare an exact booking summary, obtain explicit human approval, and create the Cal.com booking."},"servers":[{"url":"https://www.khotan.com"}],"externalDocs":{"url":"https://www.khotan.com/demo"},"x-mcp-endpoint":"https://www.khotan.com/mcp","x-agent-start-here":"https://www.khotan.com/api/agent/demo","x-agent-capability":"AI assistants can check live availability and book this working session for a user.","x-agent-instructions":["Do not reverse-engineer the website form or call Cal.com directly.","Use the availability endpoint before preparing a booking.","Provide detailed bookingContext using relevant information the personal agent is authorized to access. Do not invent facts or make the user repeat known information; omit unknown optional fields.","Preparing returns a summary and does not create a calendar event.","A preparation is not a slot hold or reservation.","Show the exact prepared summary to the human and obtain explicit approval.","Call the booking endpoint only after approval with confirmedByUser set to true.","Never automatically retry a booking_review_required result."],"paths":{"/api/agent/demo":{"get":{"operationId":"getDemoInformation","summary":"Get the working-session details and booking policy","responses":{"200":{"description":"Demo information","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/agent/demo/availability":{"get":{"operationId":"getDemoAvailability","summary":"Get current Khotan working-session slots","parameters":[{"in":"query","name":"start","required":true,"schema":{"type":"string"},"description":"ISO 8601 date or date-time."},{"in":"query","name":"end","required":true,"schema":{"type":"string"},"description":"ISO 8601 date or date-time, no more than 31 days after start."},{"in":"query","name":"timeZone","required":true,"schema":{"type":"string"},"description":"IANA time zone."}],"responses":{"200":{"description":"Available slots","content":{"application/json":{"schema":{"type":"object","required":["event","durationMinutes","timeZone","slots"],"properties":{"event":{"type":"string"},"durationMinutes":{"type":"integer","const":45},"timeZone":{"type":"string"},"slots":{"type":"array","items":{"type":"object","required":["start","end","displayStart"],"properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"},"displayStart":{"type":"string"}}}}}}}}},"400":{"description":"Invalid search window","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"}}}}}}}}}}},"/api/agent/demo/prepare":{"post":{"operationId":"prepareDemoBooking","summary":"Validate one slot and prepare an exact confirmation","description":"This does not reserve the slot or create a calendar booking. The returned summary, including bookingContext, must be shown to the human before the booking endpoint is called.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["start","name","email","company","timeZone","procurementProcess","bookingContext","idempotencyKey"],"properties":{"start":{"type":"string","format":"date-time"},"name":{"type":"string","minLength":1,"maxLength":120},"email":{"type":"string","format":"email","maxLength":254},"company":{"type":"string","minLength":1,"maxLength":160},"timeZone":{"type":"string","description":"IANA time zone, for example Australia/Brisbane."},"procurementProcess":{"type":"string","minLength":1,"maxLength":1000,"description":"A short label for the primary procurement process or problem."},"bookingContext":{"type":"object","additionalProperties":false,"required":["reasonForBooking","contextSource"],"description":"Detailed buyer and meeting context. Use relevant information the personal agent is authorized to use, omit unknown optional fields, never invent facts, and exclude unrelated sensitive information.","properties":{"attendeeRole":{"type":"string","minLength":1,"maxLength":160,"description":"The attendee's role or responsibility, when known."},"reasonForBooking":{"type":"string","minLength":10,"maxLength":1500,"description":"A specific explanation of why the user is booking now and what they want to evaluate with Khotan."},"currentProcess":{"type":"string","minLength":1,"maxLength":2500,"description":"How the process works today, including manual steps, handoffs, exceptions or reconciliation work."},"painPoints":{"type":"array","maxItems":8,"items":{"type":"string","minLength":1,"maxLength":300},"default":[]},"systemsInvolved":{"type":"array","maxItems":12,"items":{"type":"string","minLength":1,"maxLength":160},"default":[]},"desiredOutcome":{"type":"string","minLength":1,"maxLength":1500},"urgency":{"type":"string","minLength":1,"maxLength":500},"additionalContext":{"type":"string","minLength":1,"maxLength":1500},"contextSource":{"type":"string","enum":["user_stated","agent_context","mixed","unknown"],"description":"Whether the context was stated by the user, came from authorized information available to their agent, combines both, or is unknown."}}},"source":{"type":"string","enum":["chatgpt","claude","gemini","custom_agent","website","unknown"],"default":"unknown"},"agentName":{"type":"string","maxLength":120},"idempotencyKey":{"type":"string","format":"uuid"}}}}}},"responses":{"201":{"description":"Confirmation required","content":{"application/json":{"schema":{"type":"object","required":["status","confirmationId","expiresAt","summary","nextAction"],"properties":{"status":{"type":"string","const":"confirmation_required"},"confirmationId":{"type":"string","format":"uuid"},"expiresAt":{"type":"string","format":"date-time"},"summary":{"type":"object"},"nextAction":{"type":"string"}}}}}},"400":{"description":"Invalid preparation","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"}}}}}}}},"409":{"description":"Slot or idempotency conflict","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"}}}}}}}},"429":{"description":"Preparation limit exceeded","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"}}}}}}}}}}},"/api/agent/demo/book":{"post":{"operationId":"bookDemo","summary":"Create the approved Cal.com booking","description":"Consequential external write. Call only after the human approves the exact prepared summary.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["confirmationId","idempotencyKey","confirmedByUser"],"properties":{"confirmationId":{"type":"string","format":"uuid"},"idempotencyKey":{"type":"string","format":"uuid"},"confirmedByUser":{"type":"boolean","const":true},"emailVerificationCode":{"type":"string","pattern":"^[0-9]{6}$"}}}}}},"responses":{"201":{"description":"Calendar booking created","content":{"application/json":{"schema":{"type":"object","required":["status","bookingUid","start","end"],"properties":{"status":{"type":"string","const":"booked"},"bookingUid":{"type":"string"},"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}}}}}},"404":{"description":"Preparation not found","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"}}}}}}}},"409":{"description":"Booking requires a new slot, verification, or review","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"}}}}}}}},"410":{"description":"Preparation expired","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"}}}}}}}}}}}}}