{
  "openapi": "3.1.0",
  "info": {
    "title": "Pickleball Rules Machine API",
    "version": "1.0.0",
    "description": "Machine-readable endpoints, search index, clean markdown views, and full LLM knowledge base files for Pickleball Rules.",
    "contact": {
      "name": "Pickleball Rules",
      "url": "https://www.pickleballrules.fyi/about/"
    },
    "license": {
      "name": "Pickleball Rules Content License",
      "url": "https://www.pickleballrules.fyi/ai.txt"
    }
  },
  "servers": [
    {
      "url": "https://www.pickleballrules.fyi",
      "description": "Production server"
    }
  ],
  "paths": {
    "/llms.txt": {
      "get": {
        "summary": "LLM Context Index",
        "description": "Machine-readable index of all website guides following the llms.txt standard.",
        "operationId": "getLlmsTxt",
        "responses": {
          "200": {
            "description": "Plain text index of guides with URLs and descriptions.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/.well-known/llms.txt": {
      "get": {
        "summary": "LLM Context Index (Well-Known)",
        "description": "Alias endpoint for /llms.txt at the standard .well-known location.",
        "operationId": "getWellKnownLlmsTxt",
        "responses": {
          "200": {
            "description": "Plain text index of guides with URLs and descriptions.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/llms-full.txt": {
      "get": {
        "summary": "Consolidated Full-Text Knowledge Base",
        "description": "Complete consolidated reference guide combining official rules, stroke mechanics, and strategy in plain text.",
        "operationId": "getLlmsFullTxt",
        "responses": {
          "200": {
            "description": "Full text knowledge base formatted in Markdown.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/search-index.json": {
      "get": {
        "summary": "Site Search Index",
        "description": "Complete searchable JSON index containing page titles, slugs, categories, descriptions, excerpts, headings, and timestamps.",
        "operationId": "getSearchIndex",
        "responses": {
          "200": {
            "description": "List of indexed pages.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/SearchIndexEntry"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/index.md": {
      "get": {
        "summary": "Homepage Plain-Text Markdown",
        "description": "Plain text Markdown version of the homepage and master directory.",
        "operationId": "getHomepageMarkdown",
        "responses": {
          "200": {
            "description": "Homepage in Markdown with YAML frontmatter.",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/{slug}.md": {
      "get": {
        "summary": "Page Plain-Text Markdown",
        "description": "Clean markdown version of any content page (e.g. /rules/kitchen.md) with YAML frontmatter.",
        "operationId": "getPageMarkdown",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "Path slug of the page (e.g. \"rules/kitchen\").",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Clean markdown document with metadata frontmatter.",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "Page not found."
          }
        }
      }
    },
    "/ai.txt": {
      "get": {
        "summary": "AI Agent Guidelines",
        "description": "Agent instructions, site authority, scope, citation standards, and permissions.",
        "operationId": "getAiTxt",
        "responses": {
          "200": {
            "description": "AI crawler and agent instruction text.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/.well-known/agent.json": {
      "get": {
        "summary": "Agent Capabilities Manifest",
        "description": "Machine manifest declaring agent capabilities, OpenAPI endpoints, and search index.",
        "operationId": "getAgentManifest",
        "responses": {
          "200": {
            "description": "Agent manifest JSON.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/.well-known/ai-plugin.json": {
      "get": {
        "summary": "Plugin Manifest",
        "description": "Plugin manifest for AI chat and agent integrations.",
        "operationId": "getPluginManifest",
        "responses": {
          "200": {
            "description": "Plugin manifest JSON.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/sitemap-index.xml": {
      "get": {
        "summary": "XML Sitemap Index",
        "description": "XML sitemap index for search crawlers and agents.",
        "operationId": "getSitemapIndex",
        "responses": {
          "200": {
            "description": "XML sitemap index.",
            "content": {
              "application/xml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/rss.xml": {
      "get": {
        "summary": "RSS Feed",
        "description": "RSS feed with recent guide releases and updates.",
        "operationId": "getRssFeed",
        "responses": {
          "200": {
            "description": "XML RSS feed.",
            "content": {
              "application/rss+xml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SearchIndexEntry": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "markdownUrl": {
            "type": "string",
            "format": "uri"
          },
          "category": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "excerpt": {
            "type": "string"
          },
          "headings": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "updatedAt": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "title",
          "slug",
          "url",
          "markdownUrl",
          "category",
          "description",
          "excerpt",
          "headings"
        ]
      }
    }
  }
}
