{
  "openapi": "3.0.3",
  "info": {
    "title": "Clear Stride public API",
    "version": "1.1.0",
    "description": "Clear Stride is the marketing site for an equestrian expense-tracking product (web + iOS). It exposes read-only discovery endpoints plus one public write endpoint, POST /api/demo-requests, that books a product demo (the same action as the /request-demo form). The product's own data (expenses, health records) is private and requires a user account; there is no public data API. The demo endpoint needs no authentication. An optional API key (X-API-Key) is accepted for trusted integrations.",
    "contact": {
      "name": "Clear Stride",
      "email": "hello@clearstride.app",
      "url": "https://clearstride.app"
    }
  },
  "servers": [
    { "url": "https://clearstride.app", "description": "Production site" }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Optional API key for trusted integrations. Not required to call any endpoint; when supplied on POST /api/demo-requests the request is flagged as trusted in the response. Request a key at hello@clearstride.app."
      }
    },
    "schemas": {
      "DemoRequest": {
        "type": "object",
        "required": ["name", "email"],
        "additionalProperties": false,
        "properties": {
          "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Contact name." },
          "email": { "type": "string", "format": "email", "minLength": 5, "maxLength": 254, "description": "Contact email." },
          "barn_name": { "type": "string", "maxLength": 160, "description": "Barn or farm name." },
          "phone": { "type": "string", "maxLength": 30, "description": "Phone number." },
          "horses": { "type": "string", "maxLength": 10, "description": "Approximate herd size.", "enum": ["1-2", "3-6", "7-15", "16+"] },
          "message": { "type": "string", "maxLength": 2000, "description": "Anything you want the team to know." }
        }
      },
      "DemoRequestResult": {
        "type": "object",
        "properties": {
          "ok": { "type": "boolean" },
          "id": { "type": "string", "description": "Identifier of the created demo request." },
          "trusted": { "type": "boolean", "description": "True if a recognized X-API-Key was supplied." },
          "message": { "type": "string" }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": { "type": "string" },
          "message": { "type": "string" },
          "errors": { "type": "array", "items": { "type": "string" } }
        }
      }
    }
  },
  "security": [],
  "paths": {
    "/api/demo-requests": {
      "post": {
        "summary": "Book a product demo",
        "description": "Create a Clear Stride demo request on a user's behalf. Public; no authentication required. An optional X-API-Key header is accepted for trusted integrations.",
        "operationId": "createDemoRequest",
        "security": [{}, { "ApiKeyAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/DemoRequest" },
              "example": { "name": "Jane Rider", "email": "jane@example.com", "barn_name": "Willow Creek", "horses": "3-6", "message": "Two hunters and a pony; would love a walkthrough." }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Demo request created",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DemoRequestResult" } } }
          },
          "400": {
            "description": "Validation failed",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          },
          "405": {
            "description": "Method not allowed",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          },
          "502": {
            "description": "Intake service unavailable",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          }
        }
      }
    },
    "/llms.txt": {
      "get": {
        "summary": "Machine-readable site overview (llms.txt)",
        "operationId": "getLlmsTxt",
        "responses": {
          "200": { "description": "Plain-text overview of the product and pages", "content": { "text/plain": {} } }
        }
      }
    },
    "/index.md": {
      "get": {
        "summary": "Homepage rendered as Markdown for agents",
        "operationId": "getHomepageMarkdown",
        "responses": {
          "200": { "description": "Markdown rendering of the homepage", "content": { "text/markdown": {} } }
        }
      }
    },
    "/skill.md": {
      "get": {
        "summary": "Agent instructions for using this site",
        "operationId": "getSkill",
        "responses": {
          "200": { "description": "Markdown agent instructions", "content": { "text/markdown": {} } }
        }
      }
    },
    "/.well-known/agent-card.json": {
      "get": {
        "summary": "A2A agent card",
        "operationId": "getAgentCard",
        "responses": {
          "200": { "description": "Agent card JSON", "content": { "application/json": {} } }
        }
      }
    },
    "/.well-known/ai.json": {
      "get": {
        "summary": "Site profile for AI agents",
        "operationId": "getAiProfile",
        "responses": {
          "200": { "description": "AI profile JSON", "content": { "application/json": {} } }
        }
      }
    },
    "/.well-known/mcp.json": {
      "get": {
        "summary": "WebMCP tool descriptor",
        "operationId": "getMcpDescriptor",
        "responses": {
          "200": { "description": "WebMCP descriptor JSON", "content": { "application/json": {} } }
        }
      }
    },
    "/sitemap.xml": {
      "get": {
        "summary": "XML sitemap",
        "operationId": "getSitemap",
        "responses": {
          "200": { "description": "Sitemap XML", "content": { "application/xml": {} } }
        }
      }
    },
    "/feed.xml": {
      "get": {
        "summary": "Atom feed of product updates",
        "operationId": "getFeed",
        "responses": {
          "200": { "description": "Atom feed of product updates", "content": { "application/atom+xml": {} } }
        }
      }
    }
  }
}