{
  "openapi": "3.0.3",
  "info": {
    "title": "RepsFinder Public API",
    "version": "1.0.0",
    "description": "Read-only public endpoints of RepsFinder (www.qualityrepsfinder.com), an independent affiliate catalog of China shopping agents with curated replica products and real QC photos. All endpoints below are public: no authentication is required. An optional bearer token is available via the client_credentials grant (see /auth.md and /.well-known/oauth-protected-resource).",
    "contact": {
      "name": "RepsFinder",
      "email": "legal@qualityrepsfinder.com",
      "url": "https://www.qualityrepsfinder.com/auth.md"
    }
  },
  "servers": [
    {"url": "https://www.qualityrepsfinder.com"}
  ],
  "paths": {
    "/": {
      "get": {
        "summary": "Homepage",
        "description": "HTML homepage with featured products, verified agents and FAQ. Supports Accept: text/markdown content negotiation (returns index.md).",
        "responses": {"200": {"description": "HTML homepage", "content": {"text/html": {}, "text/markdown": {}}}}
      }
    },
    "/catalog": {
      "get": {
        "summary": "Full product catalog",
        "description": "HTML catalog of 17,917 curated replica products across 14 categories. Also available at /catalog.html.",
        "parameters": [
          {"name": "q", "in": "query", "required": false, "description": "Free-text search (e.g. Jordan, Yeezy, Essentials)", "schema": {"type": "string"}}
        ],
        "responses": {"200": {"description": "HTML catalog", "content": {"text/html": {}, "text/markdown": {}}}}
      }
    },
    "/category/{category}": {
      "get": {
        "summary": "Catalog category page",
        "parameters": [
          {"name": "category", "in": "path", "required": true, "schema": {"type": "string", "enum": ["accessories", "bags", "caps", "electronics", "hoodies", "jackets", "kids", "pants", "perfumes", "sets", "sneakers", "t-shirts", "underwear", "women"]}}
        ],
        "responses": {"200": {"description": "HTML category page", "content": {"text/html": {}}}}
      }
    },
    "/producto/{slug}": {
      "get": {
        "summary": "Product detail page",
        "description": "Product page with original Weidian/1688 listing link, price and real QC photos. Served at /producto/{slug}.html.",
        "parameters": [
          {"name": "slug", "in": "path", "required": true, "description": "Product slug, e.g. air-jordan-12-8-colorways-7817089978 (get slugs from the catalog or the MCP server)", "schema": {"type": "string"}}
        ],
        "responses": {"200": {"description": "HTML product page", "content": {"text/html": {}}}}
      }
    },
    "/spreadsheet/{agent}": {
      "get": {
        "summary": "Spreadsheet view per agent",
        "description": "Machine-scrapable HTML table of the catalog for one China shopping agent (Kakobuy, USFans or Litbuy).",
        "parameters": [
          {"name": "agent", "in": "path", "required": true, "schema": {"type": "string", "enum": ["kakobuy", "usfans", "litbuy"]}}
        ],
        "responses": {"200": {"description": "HTML table", "content": {"text/html": {}}}}
      }
    },
    "/health.json": {
      "get": {
        "summary": "Health endpoint",
        "responses": {"200": {"description": "Service status", "content": {"application/json": {}}}}
      }
    },
    "/mcp": {
      "post": {
        "summary": "MCP Streamable HTTP endpoint",
        "description": "Stateless JSON-RPC 2.0 MCP server (tools: search_products, list_categories, get_agent_offers, estimate_shipping). Public, no authentication.",
        "requestBody": {"required": true, "content": {"application/json": {}}},
        "responses": {"200": {"description": "JSON-RPC response", "content": {"application/json": {}}}, "202": {"description": "Accepted (notifications)"}, "405": {"description": "Method not allowed (GET not supported; use POST)"}}
      }
    },
    "/oauth/token": {
      "post": {
        "summary": "OAuth 2.0 token endpoint (client_credentials)",
        "description": "Issues an optional public-scope bearer token. The API is public, so this token is not required to call any endpoint.",
        "requestBody": {"required": true, "content": {"application/x-www-form-urlencoded": {"schema": {"type": "object", "properties": {"grant_type": {"type": "string", "enum": ["client_credentials"]}, "client_id": {"type": "string"}, "scope": {"type": "string"}}}}}},
        "responses": {"200": {"description": "Access token", "content": {"application/json": {}}}, "400": {"description": "Invalid request"}, "405": {"description": "POST only"}}
      }
    },
    "/.well-known/api-catalog": {
      "get": {
        "summary": "API catalog (RFC 9727)",
        "responses": {"200": {"description": "Linkset", "content": {"application/linkset+json": {}}}}
      }
    },
    "/.well-known/ai-catalog.json": {
      "get": {
        "summary": "ARD capability manifest (Agentic Resource Discovery)",
        "responses": {"200": {"description": "AI catalog manifest", "content": {"application/json": {}}}}
      }
    },
    "/.well-known/oauth-authorization-server": {
      "get": {
        "summary": "OAuth 2.0 Authorization Server Metadata (RFC 8414)",
        "responses": {"200": {"description": "AS metadata", "content": {"application/json": {}}}}
      }
    },
    "/.well-known/oauth-protected-resource": {
      "get": {
        "summary": "OAuth Protected Resource Metadata (RFC 9728)",
        "responses": {"200": {"description": "PRM document", "content": {"application/json": {}}}}
      }
    },
    "/.well-known/jwks.json": {
      "get": {
        "summary": "JSON Web Key Set for access tokens",
        "responses": {"200": {"description": "JWK Set", "content": {"application/json": {}}}}
      }
    },
    "/.well-known/mcp/server-card.json": {
      "get": {
        "summary": "MCP Server Card (SEP-1649)",
        "responses": {"200": {"description": "Server card", "content": {"application/json": {}}}}
      }
    },
    "/.well-known/agent-skills/index.json": {
      "get": {
        "summary": "Agent skills discovery index",
        "responses": {"200": {"description": "Skills index", "content": {"application/json": {}}}}
      }
    },
    "/auth.md": {
      "get": {
        "summary": "Agent registration instructions (Auth.md)",
        "responses": {"200": {"description": "Markdown document", "content": {"text/markdown": {}}}}
      }
    },
    "/openapi.json": {
      "get": {
        "summary": "This OpenAPI description",
        "responses": {"200": {"description": "OpenAPI document", "content": {"application/json": {}}}}
      }
    }
  }
}