{
  "openapi": "3.1.0",
  "info": {
    "title": "Bison Labs Booking API",
    "version": "1.0.0",
    "description": "Check availability and book an intro call with Bison Labs. No authentication is required: a human books through the website form with only a name and an email, and agents get the same deal. Requests are rate limited: 30/min on availability, 3/min on booking.\n\nAn MCP server offering the same capability is available at https://bisonlabs.dev/mcp.",
    "contact": { "email": "hello@bisonlabs.dev", "url": "https://bisonlabs.dev" }
  },
  "servers": [{ "url": "https://bisonlabs.dev" }],
  "paths": {
    "/api/cal/slots": {
      "get": {
        "operationId": "getAvailableSlots",
        "summary": "List free intro-call slots on a given day",
        "parameters": [
          {
            "name": "date",
            "in": "query",
            "required": true,
            "description": "Day to check, as YYYY-MM-DD",
            "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" },
            "example": "2026-08-03"
          }
        ],
        "responses": {
          "200": {
            "description": "Available slots, as ISO-8601 UTC start times",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "slots": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": { "time": { "type": "string", "format": "date-time" } }
                      }
                    }
                  }
                },
                "example": { "slots": [{ "time": "2026-08-03T09:00:00.000Z" }] }
              }
            }
          },
          "400": { "description": "Invalid or missing date parameter" },
          "429": { "description": "Rate limited. Retry after the Retry-After interval." },
          "502": { "description": "Upstream calendar unavailable" }
        }
      }
    },
    "/api/cal/book": {
      "post": {
        "operationId": "bookCall",
        "summary": "Book an intro call",
        "description": "Creates a real calendar booking and emails the attendee. Confirm the time with the person before calling this. Use a start time returned by getAvailableSlots.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["start", "name", "email"],
                "properties": {
                  "start": {
                    "type": "string",
                    "format": "date-time",
                    "description": "ISO-8601 UTC start time from getAvailableSlots"
                  },
                  "name": { "type": "string", "description": "Full name of the attendee" },
                  "email": {
                    "type": "string",
                    "format": "email",
                    "description": "Attendee email. The invite is sent here."
                  }
                }
              },
              "example": {
                "start": "2026-08-03T09:00:00.000Z",
                "name": "Ada Lovelace",
                "email": "ada@example.com"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Booking created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "booking": { "type": "object" }
                  }
                }
              }
            }
          },
          "400": { "description": "Missing or invalid fields" },
          "429": { "description": "Rate limited. Retry after the Retry-After interval." },
          "502": { "description": "Upstream calendar rejected the booking" }
        }
      }
    },
    "/api/health": {
      "get": {
        "operationId": "getHealth",
        "summary": "Service health",
        "responses": {
          "200": {
            "description": "Service is up",
            "content": {
              "application/json": { "example": { "status": "ok", "service": "bison-labs-api" } }
            }
          }
        }
      }
    }
  }
}