{
  "openapi": "3.1.0",
  "info": {
    "title": "Teos Retreats Public API",
    "description": "Public API for Harmony Retreats Ecuador (teosretreats.com). Surfaces retreat schedule, inquiry submission, Stripe deposit checkout, and markdown twins of public pages. Includes MPP (Machine Payment Protocol) x-payment-info extensions on payable operations so AI agents can programmatically pay for retreat deposits via Stripe.",
    "version": "1.0.0",
    "contact": {
      "name": "Harmony Retreats Ecuador",
      "email": "harmonyinthejungle@gmail.com",
      "url": "https://www.teosretreats.com/contact"
    },
    "license": {
      "name": "Public API — no key required for read endpoints"
    },
    "x-mpp-version": "0.1"
  },
  "servers": [
    {
      "url": "https://www.teosretreats.com",
      "description": "Production"
    }
  ],
  "paths": {
    "/api/": {
      "get": {
        "summary": "API health + welcome",
        "operationId": "getApiRoot",
        "responses": {
          "200": {
            "description": "API welcome payload",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ApiRoot" }
              },
              "text/markdown": {
                "schema": { "type": "string" }
              }
            }
          }
        }
      }
    },
    "/api/schedule": {
      "get": {
        "summary": "Upcoming retreat schedule",
        "description": "Returns all upcoming Teos Retreats with dates, prices, healers, and ceremonies.",
        "operationId": "listSchedule",
        "responses": {
          "200": {
            "description": "Array of retreat schedule items",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/ScheduleItem" }
                }
              },
              "text/markdown": {
                "schema": { "type": "string" }
              }
            }
          }
        }
      }
    },
    "/api/inquiries": {
      "post": {
        "summary": "Submit participant inquiry",
        "description": "Submits a new inquiry. A human team member replies within 48 hours.",
        "operationId": "createInquiry",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/InquiryInput" }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Inquiry accepted",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Inquiry" }
              }
            }
          }
        }
      }
    },
    "/api/checkout/session": {
      "post": {
        "summary": "Create checkout session (DISABLED)",
        "description": "DISABLED as of 2026-05-07: the upstream Stripe account was shut down. Endpoint still exists for backward compatibility but no longer creates billable sessions. Reservations are now handled manually via /api/inquiries followed by an email reply with payment options (bank transfer, Wise, or cryptocurrency).",
        "operationId": "createCheckoutSession",
        "deprecated": true,
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CreateCheckoutRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Stripe Checkout session created",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CreateCheckoutResponse" }
              }
            }
          },
          "400": {
            "description": "Invalid package_id or request body"
          },
          "502": {
            "description": "Payment gateway unavailable"
          }
        }
      }
    },
    "/api/checkout/status/{session_id}": {
      "get": {
        "summary": "Poll Stripe checkout session status",
        "operationId": "getCheckoutStatus",
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Checkout status",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CheckoutStatus" }
              }
            }
          },
          "404": {
            "description": "Session not found"
          }
        }
      }
    },
    "/api/md/{slug}": {
      "get": {
        "summary": "Markdown twin of an HTML page",
        "description": "Returns a pre-rendered markdown version of a public HTML route. Useful for AI agents ingesting site content.",
        "operationId": "getMarkdownTwin",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": ["index", "about", "about-facts", "facts", "schedule"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Markdown body",
            "content": {
              "text/markdown": {
                "schema": { "type": "string" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Admin-only bearer token issued by POST /api/auth/login. Public endpoints documented here require no token."
      }
    },
    "schemas": {
      "ApiRoot": {
        "type": "object",
        "properties": {
          "message": { "type": "string" },
          "status": { "type": "string" }
        }
      },
      "ScheduleItem": {
        "type": "object",
        "required": ["id", "month", "year", "dates", "retreat", "shaman", "duration", "price"],
        "properties": {
          "id": { "type": "string" },
          "month": { "type": "string" },
          "year": { "type": "integer" },
          "dates": { "type": "string" },
          "endsOn": { "type": "string", "format": "date" },
          "retreat": { "type": "string" },
          "shaman": { "type": "string" },
          "duration": { "type": "string" },
          "ceremonies": { "type": "array", "items": { "type": "string" } },
          "price": { "type": "string" },
          "pdf": { "type": "string", "nullable": true }
        }
      },
      "InquiryInput": {
        "type": "object",
        "required": ["name", "email", "message"],
        "properties": {
          "name": { "type": "string", "minLength": 1, "maxLength": 120 },
          "email": { "type": "string", "format": "email" },
          "phone": { "type": "string", "maxLength": 40 },
          "retreat_interest": { "type": "string", "maxLength": 120 },
          "dates": { "type": "string", "maxLength": 120 },
          "message": { "type": "string", "minLength": 1, "maxLength": 4000 },
          "lang": { "type": "string", "enum": ["en", "es", "ru"] }
        }
      },
      "Inquiry": {
        "allOf": [
          { "$ref": "#/components/schemas/InquiryInput" },
          {
            "type": "object",
            "properties": {
              "id": { "type": "string", "format": "uuid" },
              "created_at": { "type": "string", "format": "date-time" }
            }
          }
        ]
      },
      "CreateCheckoutRequest": {
        "type": "object",
        "required": ["package_id", "origin_url", "name", "email"],
        "properties": {
          "package_id": {
            "type": "string",
            "enum": ["retreat-deposit"],
            "description": "Fixed server-side package. DISABLED 2026-05-07: this endpoint no longer issues billable checkout sessions."
          },
          "origin_url": { "type": "string", "format": "uri" },
          "name": { "type": "string", "minLength": 1, "maxLength": 200 },
          "email": { "type": "string", "format": "email" },
          "retreat_id": { "type": "string", "maxLength": 80 },
          "retreat_label": { "type": "string", "maxLength": 200 },
          "lang": { "type": "string", "enum": ["en", "es", "ru"] }
        }
      },
      "CreateCheckoutResponse": {
        "type": "object",
        "properties": {
          "url": { "type": "string", "format": "uri", "description": "Hosted Stripe Checkout URL" },
          "session_id": { "type": "string" }
        }
      },
      "CheckoutStatus": {
        "type": "object",
        "properties": {
          "session_id": { "type": "string" },
          "status": { "type": "string" },
          "payment_status": { "type": "string" },
          "amount_total": { "type": "number" },
          "currency": { "type": "string" },
          "retreat_label": { "type": "string", "nullable": true },
          "customer_name": { "type": "string", "nullable": true },
          "customer_email": { "type": "string", "format": "email", "nullable": true }
        }
      }
    }
  }
}