{
  "openapi": "3.1.0",
  "info": {
    "title": "SurfCash public API",
    "version": "1.0.0",
    "summary": "Agent and public-stats interface for SurfCash",
    "description": "Machine-readable surface for the SurfCash marketing site and public product stats. HTML pages also speak Markdown when requested with Accept: text/markdown.",
    "contact": {
      "name": "SurfCash",
      "email": "hello@getsurf.cash",
      "url": "https://getsurf.cash/contact"
    },
    "license": {
      "name": "Proprietary"
    }
  },
  "servers": [
    {
      "url": "https://getsurf.cash",
      "description": "Marketing site and agent interface"
    },
    {
      "url": "https://apigateway-pwa.getsurf.cash/api/v1",
      "description": "Public product stats"
    }
  ],
  "tags": [
    { "name": "site", "description": "Agent discovery files and content negotiation on getsurf.cash" },
    { "name": "stats", "description": "Public read-only product stats" }
  ],
  "paths": {
    "/openapi.json": {
      "get": {
        "tags": ["site"],
        "summary": "OpenAPI document",
        "operationId": "getOpenApi",
        "responses": {
          "200": {
            "description": "OpenAPI 3.1 document",
            "content": {
              "application/json": {
                "schema": { "type": "object" }
              }
            }
          }
        }
      }
    },
    "/api/health": {
      "get": {
        "tags": ["site"],
        "summary": "Liveness check",
        "operationId": "getHealth",
        "responses": {
          "200": {
            "description": "Service is up",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["ok", "service"],
                  "properties": {
                    "ok": { "type": "boolean" },
                    "service": { "type": "string" },
                    "docs": { "type": "string" },
                    "llms": { "type": "string" }
                  }
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      }
    },
    "/llms.txt": {
      "get": {
        "tags": ["site"],
        "summary": "LLM context file",
        "operationId": "getLlmsTxt",
        "responses": {
          "200": {
            "description": "llms.txt",
            "content": { "text/plain": { "schema": { "type": "string" } } }
          }
        }
      }
    },
    "/llms-full.txt": {
      "get": {
        "tags": ["site"],
        "summary": "Full-site dump for agents",
        "operationId": "getLlmsFull",
        "responses": {
          "200": {
            "description": "llms-full.txt",
            "content": { "text/plain": { "schema": { "type": "string" } } }
          }
        }
      }
    },
    "/pricing.md": {
      "get": {
        "tags": ["site"],
        "summary": "Fees and pricing in Markdown",
        "operationId": "getPricing",
        "responses": {
          "200": {
            "description": "Pricing markdown",
            "content": { "text/markdown": { "schema": { "type": "string" } } }
          }
        }
      }
    },
    "/sitemap.xml": {
      "get": {
        "tags": ["site"],
        "summary": "XML sitemap",
        "operationId": "getSitemap",
        "responses": {
          "200": {
            "description": "Sitemap",
            "content": { "application/xml": { "schema": { "type": "string" } } }
          }
        }
      }
    },
    "/": {
      "get": {
        "tags": ["site"],
        "summary": "Homepage (HTML or Markdown via Accept)",
        "operationId": "getHome",
        "parameters": [
          {
            "name": "Accept",
            "in": "header",
            "schema": {
              "type": "string",
              "examples": ["text/html", "text/markdown", "application/json"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Homepage",
            "headers": {
              "Vary": {
                "schema": { "type": "string", "example": "Accept, Accept-Encoding" }
              }
            },
            "content": {
              "text/html": { "schema": { "type": "string" } },
              "text/markdown": { "schema": { "type": "string" } }
            }
          }
        }
      }
    },
    "/{page}": {
      "get": {
        "tags": ["site"],
        "summary": "Marketing page (HTML or Markdown via Accept)",
        "operationId": "getPage",
        "parameters": [
          {
            "name": "page",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "about",
                "contact",
                "faq",
                "resources",
                "pay-rent",
                "for-landlords",
                "for-hosts",
                "education",
                "vietnam",
                "brazil",
                "nigeria",
                "philippines",
                "mexico",
                "moretapay-vs-surfcash",
                "localpay-vs-surfcash",
                "how-to-pay-with-crypto-in-vietnam",
                "how-to-pay-rent-in-vietnam-without-a-bank-account",
                "terms",
                "privacy"
              ]
            }
          },
          {
            "name": "Accept",
            "in": "header",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Page",
            "headers": {
              "Vary": {
                "schema": { "type": "string", "example": "Accept, Accept-Encoding" }
              }
            },
            "content": {
              "text/html": { "schema": { "type": "string" } },
              "text/markdown": { "schema": { "type": "string" } }
            }
          },
          "404": {
            "description": "Unknown path",
            "content": {
              "text/html": { "schema": { "type": "string" } },
              "text/markdown": { "schema": { "type": "string" } },
              "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }
            }
          }
        }
      }
    },
    "/public/network-stats": {
      "get": {
        "tags": ["stats"],
        "summary": "Public network volume and user counts",
        "operationId": "getNetworkStats",
        "servers": [
          { "url": "https://apigateway-pwa.getsurf.cash/api/v1" }
        ],
        "responses": {
          "200": {
            "description": "Network stats envelope",
            "content": {
              "application/json": {
                "schema": { "type": "object" }
              }
            }
          }
        }
      }
    },
    "/public/weekly-stats": {
      "get": {
        "tags": ["stats"],
        "summary": "Weekly transaction volume",
        "operationId": "getWeeklyStats",
        "servers": [
          { "url": "https://apigateway-pwa.getsurf.cash/api/v1" }
        ],
        "parameters": [
          {
            "name": "weeks",
            "in": "query",
            "schema": { "type": "integer", "default": 26 }
          }
        ],
        "responses": {
          "200": {
            "description": "Weekly stats envelope",
            "content": {
              "application/json": {
                "schema": { "type": "object" }
              }
            }
          }
        }
      }
    },
    "/public/referral-leaderboard": {
      "get": {
        "tags": ["stats"],
        "summary": "Public referral leaderboard",
        "operationId": "getReferralLeaderboard",
        "servers": [
          { "url": "https://apigateway-pwa.getsurf.cash/api/v1" }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": { "type": "integer", "default": 200 }
          }
        ],
        "responses": {
          "200": {
            "description": "Leaderboard envelope",
            "content": {
              "application/json": {
                "schema": { "type": "object" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["code", "message", "status"],
            "properties": {
              "code": { "type": "string", "examples": ["not_found", "method_not_allowed"] },
              "message": { "type": "string" },
              "status": { "type": "integer" },
              "hint": { "type": "string" }
            }
          }
        }
      }
    }
  }
}