{
  "openapi": "3.1.0",
  "info": {
    "title": "Ducky Finance Content API",
    "version": "1.0.0",
    "summary": "Read-only access to the free Ducky Finance stock market lessons and blog posts.",
    "description": "Every lesson and post on https://www.ducky.finance can be fetched as Markdown by sending `Accept: text/markdown`. `/content.json` lists everything with titles, descriptions, and URLs. The same content is available over MCP at `/mcp`. No authentication, no API key. Nothing here is personalized financial advice.",
    "contact": { "name": "Ducky Finance", "email": "hello@ducky.finance", "url": "https://www.ducky.finance/agents/" },
    "termsOfService": "https://www.ducky.finance/terms/"
  },
  "servers": [{ "url": "https://www.ducky.finance" }],
  "externalDocs": { "description": "Guide for AI agents", "url": "https://www.ducky.finance/agents/" },
  "paths": {
    "/content.json": {
      "get": {
        "operationId": "listContent",
        "summary": "List every course unit, lesson, and blog post",
        "responses": {
          "200": {
            "description": "The content index.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentIndex" } } }
          }
        }
      }
    },
    "/lessons/{lesson}/": {
      "get": {
        "operationId": "getLesson",
        "summary": "Get one lesson, as Markdown or HTML",
        "description": "Send `Accept: text/markdown` for Markdown. Lesson slugs look like `unit-1-lesson-1`; take them from `/content.json`.",
        "parameters": [
          { "name": "lesson", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^unit-[1-5]-lesson-[0-9]+$" }, "example": "unit-1-lesson-1" },
          { "$ref": "#/components/parameters/Accept" }
        ],
        "responses": { "200": { "$ref": "#/components/responses/Page" }, "404": { "description": "No such lesson." } }
      }
    },
    "/blog/{post}/": {
      "get": {
        "operationId": "getPost",
        "summary": "Get one blog post, as Markdown or HTML",
        "description": "Send `Accept: text/markdown` for Markdown. Take post URLs from `/content.json`.",
        "parameters": [
          { "name": "post", "in": "path", "required": true, "schema": { "type": "string" } },
          { "$ref": "#/components/parameters/Accept" }
        ],
        "responses": { "200": { "$ref": "#/components/responses/Page" }, "404": { "description": "No such post." } }
      }
    },
    "/llms.txt": {
      "get": {
        "operationId": "getLlmsTxt",
        "summary": "Site summary for AI assistants (llms.txt)",
        "responses": { "200": { "description": "Markdown summary of the site with links to every lesson and post.", "content": { "text/plain": { "schema": { "type": "string" } } } } }
      }
    },
    "/mcp": {
      "post": {
        "operationId": "mcp",
        "summary": "MCP server (Streamable HTTP, stateless)",
        "description": "JSON-RPC 2.0 messages per the Model Context Protocol. Tools: `list_content`, `search_content`, `get_page`. See /.well-known/mcp/server-card.json.",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } },
        "responses": {
          "200": { "description": "JSON-RPC response.", "content": { "application/json": { "schema": { "type": "object" } } } },
          "202": { "description": "Notification accepted." }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "Accept": {
        "name": "Accept",
        "in": "header",
        "required": false,
        "description": "Use `text/markdown` to get Markdown instead of HTML.",
        "schema": { "type": "string", "enum": ["text/markdown", "text/html"], "default": "text/html" }
      }
    },
    "responses": {
      "Page": {
        "description": "The page. Markdown responses carry `x-markdown-tokens` with an approximate token count.",
        "content": { "text/markdown": { "schema": { "type": "string" } }, "text/html": { "schema": { "type": "string" } } }
      }
    },
    "schemas": {
      "ContentIndex": {
        "type": "object",
        "required": ["site", "units", "lessons", "posts"],
        "properties": {
          "site": {
            "type": "object",
            "properties": {
              "name": { "type": "string" },
              "url": { "type": "string", "format": "uri" },
              "description": { "type": "string" },
              "contact": { "type": "string", "format": "email" },
              "updated": { "type": "string", "format": "date-time" }
            }
          },
          "units": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": { "name": { "type": "string" }, "level": { "type": "string" }, "url": { "type": "string", "format": "uri" } }
            }
          },
          "lessons": { "type": "array", "items": { "$ref": "#/components/schemas/Lesson" } },
          "posts": { "type": "array", "items": { "$ref": "#/components/schemas/Post" } }
        }
      },
      "Lesson": {
        "type": "object",
        "properties": {
          "type": { "const": "lesson" },
          "unit": { "type": "string", "examples": ["Unit 1"] },
          "lesson": { "type": "integer" },
          "title": { "type": "string" },
          "subtitle": { "type": "string" },
          "description": { "type": "string" },
          "url": { "type": "string", "format": "uri" }
        }
      },
      "Post": {
        "type": "object",
        "properties": {
          "type": { "const": "post" },
          "title": { "type": "string" },
          "description": { "type": "string" },
          "date": { "type": "string", "format": "date" },
          "url": { "type": "string", "format": "uri" }
        }
      }
    }
  }
}