{
  "openapi": "3.1.0",
  "info": {
    "title": "Bookii API",
    "version": "0.1.0-prototype",
    "description": "Agent-native booking API. In this prototype, GET /api/slots is live (Netlify Function over the shared availability engine); holds and bookings are demonstrated client-side and specified here for the full build."
  },
  "servers": [{ "url": "https://bookii.to" }],
  "paths": {
    "/api/slots": {
      "get": {
        "summary": "Policy-applied bookable slots (live)",
        "parameters": [
          { "name": "date", "in": "query", "schema": { "type": "string", "format": "date" } },
          { "name": "tz", "in": "query", "schema": { "type": "string", "example": "America/Chicago" } }
        ],
        "responses": { "200": { "description": "Slots with preferred flags and next-step affordances" } }
      }
    },
    "/v1/holds": {
      "post": {
        "summary": "Two-phase booking, phase 1: TTL slot reservation (spec)",
        "parameters": [{ "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" } }],
        "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "eventType": { "type": "string" }, "start": { "type": "string", "format": "date-time" }, "ttlSeconds": { "type": "integer", "maximum": 300 } }, "required": ["eventType", "start"] } } } },
        "responses": { "201": { "description": "{holdId, expiresAt}" }, "409": { "description": "Slot already held or booked" } }
      }
    },
    "/v1/bookings": {
      "post": {
        "summary": "Phase 2: confirm a held slot (spec)",
        "parameters": [{ "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" } }],
        "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "holdId": { "type": "string" }, "attendee": { "type": "object" }, "principal": { "type": "object", "description": "Booking stays pending until principal email-confirms" }, "agent": { "type": "object" } }, "required": ["holdId", "attendee"] } } } },
        "responses": { "201": { "description": "Booking created (pending until principal confirmed for agent bookings)" } }
      }
    }
  }
}