{
  "openapi": "3.1.0",
  "info": {
    "title": "YakaAI API",
    "version": "1.1.0",
    "description": "Technical Documentation, Agent Rules, Dynamic Banners, and Schema Specifications for AI Agents & Developers."
  },
  "servers": [
    {
      "url": "https://yakaai.com/api",
      "description": "Production Edge Server"
    },
    {
      "url": "https://master.universal-ai-cheatsheet-hub.pages.dev/api",
      "description": "Staging Edge Server"
    }
  ],
  "paths": {
    "/repos": {
      "get": {
        "summary": "Search repositories & technical capabilities",
        "description": "Searches active repositories by name, language, and topics with velocity and freshness ranking.",
        "parameters": [
          { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 }, "description": "Page number" },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 48 }, "description": "Items per page" },
          { "name": "sort", "in": "query", "schema": { "type": "string", "enum": ["velocity", "recent"], "default": "velocity" }, "description": "Sort order" },
          { "name": "lang", "in": "query", "schema": { "type": "string" }, "description": "Filter by language" },
          { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Search query" }
        ],
        "responses": {
          "200": {
            "description": "List of repositories",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/Repository" }
                    },
                    "total": { "type": "integer" },
                    "page": { "type": "integer" },
                    "limit": { "type": "integer" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/cheat/{owner}/{repo}": {
      "get": {
        "summary": "Get technical documentation (Dual Mode)",
        "description": "Returns documentation. Supports ?section={topic} for targeted extraction or ?section=toc for Table of Contents.",
        "parameters": [
          { "name": "owner", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "repo", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "section", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Target section topic or 'toc'" }
        ],
        "responses": {
          "200": {
            "description": "Technical documentation in Markdown format",
            "content": { "text/markdown": { "schema": { "type": "string" } } }
          }
        }
      }
    },
    "/skills/{owner}/{repo}": {
      "get": {
        "summary": "Discover AI agent skills & rules",
        "description": "Scans for .cursorrules, CLAUDE.md, AGENTS.md, and MCP configurations.",
        "parameters": [
          { "name": "owner", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "repo", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Detected skill files and MCP config",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "hasSkills": { "type": "boolean" },
                    "found": { "type": "array", "items": { "type": "string" } },
                    "files": { "type": "object", "additionalProperties": { "type": "string" } },
                    "hasMcp": { "type": "boolean" },
                    "mcpConfig": { "type": "object" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/spec/{owner}/{repo}": {
      "get": {
        "summary": "Extract official API specifications",
        "description": "Returns isolated OpenAPI, Swagger, GraphQL, or Protobuf schema for the repository.",
        "parameters": [
          { "name": "owner", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "repo", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "API specification schema",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "hasSpec": { "type": "boolean" },
                    "specFile": { "type": "string" },
                    "spec": { "type": "object" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/og": {
      "get": {
        "summary": "Generate dynamic vector OpenGraph thumbnail banner",
        "description": "Generates 1200x630 SVG thumbnail banners at Cloudflare Edge with dark neon aesthetics, dynamic titles, and categorization badges.",
        "parameters": [
          { "name": "title", "in": "query", "schema": { "type": "string" }, "description": "Title text to display" },
          { "name": "desc", "in": "query", "schema": { "type": "string" }, "description": "Subtitle or description" },
          { "name": "badge", "in": "query", "schema": { "type": "string" }, "description": "Badge text on bottom left" },
          { "name": "type", "in": "query", "schema": { "type": "string", "enum": ["doc", "skills", "mcp", "topic", "spec", "home"] }, "description": "Color theme category" }
        ],
        "responses": {
          "200": {
            "description": "Dynamic SVG Banner",
            "content": { "image/svg+xml": { "schema": { "type": "string" } } }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Repository": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "name": { "type": "string" },
          "full_name": { "type": "string" },
          "description": { "type": "string" },
          "language": { "type": "string" },
          "stars": { "type": "integer" },
          "topics": { "type": "array", "items": { "type": "string" } },
          "updated_at": { "type": "string", "format": "date-time" },
          "doc_chars": { "type": "integer" },
          "doc_files": { "type": "integer" }
        }
      }
    }
  }
}