{
  "openapi": "3.1.0",
  "info": {
    "title": "SurgeFlow Public Data API",
    "version": "public-data-v1",
    "description": "Cacheable public read models for SurgeFlow research surfaces. No API key required.",
    "contact": {
      "name": "SurgeFlow support",
      "email": "support@surgeflows.capital",
      "url": "https://surgeflows.capital/contact"
    },
    "termsOfService": "https://surgeflows.capital/terms",
    "x-logo": {
      "url": "https://surgeflows.capital/brand/surgeflow-emblem.svg",
      "altText": "SurgeFlow"
    }
  },
  "servers": [
    {
      "url": "https://surgeflows.capital"
    }
  ],
  "tags": [
    {
      "name": "snapshots",
      "description": "Cacheable public research snapshots in JSON or CSV format."
    },
    {
      "name": "signature",
      "description": "Small dated JSON answers and chart series for public research pages."
    },
    {
      "name": "companies",
      "description": "Company previews and company lists for the covered markets."
    },
    {
      "name": "meta",
      "description": "API discovery documents and the public data manifest."
    }
  ],
  "externalDocs": {
    "url": "https://surgeflows.capital/developers",
    "description": "Developer documentation, API access, limits, and examples."
  },
  "paths": {
    "/api/public/manifest.json": {
      "get": {
        "tags": [
          "meta"
        ],
        "summary": "Public data manifest",
        "responses": {
          "200": {
            "description": "Manifest JSON"
          }
        }
      }
    },
    "/api/public/openapi.json": {
      "get": {
        "tags": [
          "meta"
        ],
        "summary": "OpenAPI document",
        "responses": {
          "200": {
            "description": "OpenAPI JSON"
          }
        }
      }
    },
    "/api/public/snapshots/{snapshot}.json": {
      "get": {
        "tags": [
          "snapshots"
        ],
        "summary": "Public snapshot as JSON",
        "parameters": [
          {
            "name": "snapshot",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "momentum-hotlist",
                "macro-indicators",
                "news-sentiment",
                "factor-overview",
                "data-freshness"
              ]
            }
          },
          {
            "name": "market",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "us",
                "cn",
                "jp",
                "hk"
              ]
            }
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 365,
              "default": 30
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Snapshot JSON"
          },
          "404": {
            "description": "Unknown snapshot"
          },
          "502": {
            "description": "Upstream unavailable"
          }
        }
      }
    },
    "/api/public/snapshots/{snapshot}.csv": {
      "get": {
        "tags": [
          "snapshots"
        ],
        "summary": "Public snapshot as CSV",
        "parameters": [
          {
            "name": "snapshot",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "momentum-hotlist",
                "macro-indicators",
                "news-sentiment",
                "factor-overview",
                "data-freshness"
              ]
            }
          },
          {
            "name": "market",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "us",
                "cn",
                "jp",
                "hk"
              ]
            }
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 365,
              "default": 30
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Snapshot CSV"
          },
          "404": {
            "description": "Unknown snapshot"
          },
          "502": {
            "description": "Upstream unavailable"
          }
        }
      }
    },
    "/api/public/signature/{source}.json": {
      "get": {
        "tags": [
          "signature"
        ],
        "summary": "Small dated answer for one topic (the market pulse sources are chart series)",
        "parameters": [
          {
            "name": "source",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "breadth",
                "macro",
                "hotlist",
                "news",
                "factor-reference",
                "factor-overview",
                "pulse-us",
                "pulse-jp",
                "pulse-hk",
                "pulse-cn"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Answer JSON with its own observation dates"
          },
          "404": {
            "description": "Unknown source"
          },
          "502": {
            "description": "Source unavailable"
          }
        }
      }
    },
    "/api/public/companies/{market}.json": {
      "get": {
        "tags": [
          "companies"
        ],
        "summary": "The most-traded companies covered in one market, by a 30-day liquidity measure (ticker and name)",
        "parameters": [
          {
            "name": "market",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "us",
                "cn",
                "jp",
                "hk"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Company list JSON"
          },
          "404": {
            "description": "Unknown market"
          },
          "502": {
            "description": "List unavailable"
          }
        }
      }
    },
    "/api/public/company-preview": {
      "get": {
        "tags": [
          "companies"
        ],
        "summary": "Dated public company preview",
        "parameters": [
          {
            "name": "market",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "us",
                "cn",
                "jp",
                "hk"
              ]
            }
          },
          {
            "name": "ticker",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Preview JSON; an empty or unavailable answer is not a forecast"
          },
          "422": {
            "description": "Missing or invalid market or ticker"
          }
        }
      }
    }
  }
}