{
  "info": {
    "_postman_id": "d307a383-9455-4dd2-b4b8-f03383df7e9e",
    "name": "SurgeFlow Research API",
    "description": "Dated research snapshots for US, China A-share, Japan and Hong Kong stocks as JSON or CSV. Public snapshots need no key; member endpoints use a free key. Data may be delayed or historical. Research, not investment advice.\n\nStart with the no-key public snapshots (/api/public/*, OpenAPI 3.1). For member endpoints (/api/v1/*), join at surgeflows.capital with Google, Apple or an email sign-in link, then create a key on the Account page. A member can hold up to five named keys. The free member beta allows 2,000 requests per day and 180 per minute. Each response carries its own observation dates. Free access does not grant redistribution rights.\n\nDocumentation: https://surgeflows.capital/membership/api\n\nResearch data only; not investment advice.",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "variable": [
    {
      "key": "api_base_url",
      "value": "https://stock-api-c4qdowjxva-uc.a.run.app",
      "type": "default"
    },
    {
      "key": "site_base_url",
      "value": "https://surgeflows.capital",
      "type": "default"
    },
    {
      "key": "sf_api_key",
      "value": "",
      "type": "secret"
    },
    {
      "key": "market",
      "value": "us",
      "type": "default"
    },
    {
      "key": "page",
      "value": "1",
      "type": "default"
    },
    {
      "key": "page_size",
      "value": "25",
      "type": "default"
    },
    {
      "key": "limit",
      "value": "25",
      "type": "default"
    },
    {
      "key": "news_limit",
      "value": "20",
      "type": "default"
    },
    {
      "key": "notes_market",
      "value": "all",
      "type": "default"
    },
    {
      "key": "days",
      "value": "30",
      "type": "default"
    }
  ],
  "item": [
    {
      "name": "01 No-key public snapshots",
      "description": "Public research snapshots for external agents, notebooks, search systems, and attribution-safe sharing.",
      "item": [
        {
          "name": "Public data manifest",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Accept",
                "value": "application/json"
              }
            ],
            "url": "{{site_base_url}}/api/public/manifest.json",
            "description": "Public research snapshots for external agents, notebooks, search systems, and attribution-safe sharing.",
            "auth": {
              "type": "noauth"
            }
          }
        },
        {
          "name": "Public snapshot OpenAPI",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Accept",
                "value": "application/json"
              }
            ],
            "url": "{{site_base_url}}/api/public/openapi.json",
            "description": "OpenAPI document for SurgeFlow Public Data Contract. Research data only; not investment advice.",
            "auth": {
              "type": "noauth"
            }
          }
        },
        {
          "name": "Momentum Hotlist - JSON",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Accept",
                "value": "application/json"
              }
            ],
            "url": "{{site_base_url}}/api/public/snapshots/momentum-hotlist.json?market={{market}}",
            "description": "momentum-hotlist JSON snapshot from SurgeFlow Public Data Contract. Research data only; not investment advice.",
            "auth": {
              "type": "noauth"
            }
          }
        },
        {
          "name": "Momentum Hotlist - CSV",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Accept",
                "value": "text/csv"
              }
            ],
            "url": "{{site_base_url}}/api/public/snapshots/momentum-hotlist.csv?market={{market}}",
            "description": "momentum-hotlist CSV snapshot from SurgeFlow Public Data Contract. Research data only; not investment advice.",
            "auth": {
              "type": "noauth"
            }
          }
        },
        {
          "name": "Macro Indicators - JSON",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Accept",
                "value": "application/json"
              }
            ],
            "url": "{{site_base_url}}/api/public/snapshots/macro-indicators.json",
            "description": "macro-indicators JSON snapshot from SurgeFlow Public Data Contract. Research data only; not investment advice.",
            "auth": {
              "type": "noauth"
            }
          }
        },
        {
          "name": "Macro Indicators - CSV",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Accept",
                "value": "text/csv"
              }
            ],
            "url": "{{site_base_url}}/api/public/snapshots/macro-indicators.csv",
            "description": "macro-indicators CSV snapshot from SurgeFlow Public Data Contract. Research data only; not investment advice.",
            "auth": {
              "type": "noauth"
            }
          }
        },
        {
          "name": "News Sentiment - JSON",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Accept",
                "value": "application/json"
              }
            ],
            "url": "{{site_base_url}}/api/public/snapshots/news-sentiment.json?days={{days}}",
            "description": "news-sentiment JSON snapshot from SurgeFlow Public Data Contract. Research data only; not investment advice.",
            "auth": {
              "type": "noauth"
            }
          }
        },
        {
          "name": "News Sentiment - CSV",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Accept",
                "value": "text/csv"
              }
            ],
            "url": "{{site_base_url}}/api/public/snapshots/news-sentiment.csv?days={{days}}",
            "description": "news-sentiment CSV snapshot from SurgeFlow Public Data Contract. Research data only; not investment advice.",
            "auth": {
              "type": "noauth"
            }
          }
        },
        {
          "name": "Factor Overview - JSON",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Accept",
                "value": "application/json"
              }
            ],
            "url": "{{site_base_url}}/api/public/snapshots/factor-overview.json?market={{market}}",
            "description": "factor-overview JSON snapshot from SurgeFlow Public Data Contract. Research data only; not investment advice.",
            "auth": {
              "type": "noauth"
            }
          }
        },
        {
          "name": "Factor Overview - CSV",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Accept",
                "value": "text/csv"
              }
            ],
            "url": "{{site_base_url}}/api/public/snapshots/factor-overview.csv?market={{market}}",
            "description": "factor-overview CSV snapshot from SurgeFlow Public Data Contract. Research data only; not investment advice.",
            "auth": {
              "type": "noauth"
            }
          }
        },
        {
          "name": "Data Freshness - JSON",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Accept",
                "value": "application/json"
              }
            ],
            "url": "{{site_base_url}}/api/public/snapshots/data-freshness.json",
            "description": "data-freshness JSON snapshot from SurgeFlow Public Data Contract. Research data only; not investment advice.",
            "auth": {
              "type": "noauth"
            }
          }
        },
        {
          "name": "Data Freshness - CSV",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Accept",
                "value": "text/csv"
              }
            ],
            "url": "{{site_base_url}}/api/public/snapshots/data-freshness.csv",
            "description": "data-freshness CSV snapshot from SurgeFlow Public Data Contract. Research data only; not investment advice.",
            "auth": {
              "type": "noauth"
            }
          }
        }
      ]
    },
    {
      "name": "02 Member API",
      "description": "Health and catalog need no key. Other requests use a key created at https://surgeflows.capital/account after sign-in.",
      "item": [
        {
          "name": "Health and data-quality disclosures",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Accept",
                "value": "application/json"
              }
            ],
            "url": "{{api_base_url}}/api/v1/health",
            "description": "Operational health and data-quality disclosures.",
            "auth": {
              "type": "noauth"
            }
          }
        },
        {
          "name": "API catalog",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Accept",
                "value": "application/json"
              }
            ],
            "url": "{{api_base_url}}/api/v1/catalog",
            "description": "Stable endpoint catalogue, plans, limits, and schemas.",
            "auth": {
              "type": "noauth"
            }
          }
        },
        {
          "name": "Key plan and usage",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Accept",
                "value": "application/json"
              },
              {
                "key": "Authorization",
                "value": "Bearer {{sf_api_key}}"
              }
            ],
            "url": "{{api_base_url}}/api/v1/me",
            "description": "Inspect the active API key \u2014 plan, scopes, and rolling usage (used_7d/used_30d) \u2014 without exposing its secret."
          }
        },
        {
          "name": "Four-market summary",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Accept",
                "value": "application/json"
              },
              {
                "key": "Authorization",
                "value": "Bearer {{sf_api_key}}"
              }
            ],
            "url": "{{api_base_url}}/api/v1/summary",
            "description": "Four-market market-watch summary, freshness metadata, and FX context."
          }
        },
        {
          "name": "Market screen",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Accept",
                "value": "application/json"
              },
              {
                "key": "Authorization",
                "value": "Bearer {{sf_api_key}}"
              }
            ],
            "url": "{{api_base_url}}/api/v1/markets/{{market}}/screen?page={{page}}&page_size={{page_size}}",
            "description": "Paged institutional market screen for us/cn/jp/hk."
          }
        },
        {
          "name": "Realtime turnover board",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Accept",
                "value": "application/json"
              },
              {
                "key": "Authorization",
                "value": "Bearer {{sf_api_key}}"
              }
            ],
            "url": "{{api_base_url}}/api/v1/markets/{{market}}/realtime?limit={{limit}}",
            "description": "Spreadsheet-safe realtime turnover board."
          }
        },
        {
          "name": "Momentum hotlist",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Accept",
                "value": "application/json"
              },
              {
                "key": "Authorization",
                "value": "Bearer {{sf_api_key}}"
              }
            ],
            "url": "{{api_base_url}}/api/v1/markets/{{market}}/hotlist",
            "description": "Spreadsheet-safe momentum hotlist."
          }
        },
        {
          "name": "Cluster profiles",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Accept",
                "value": "application/json"
              },
              {
                "key": "Authorization",
                "value": "Bearer {{sf_api_key}}"
              }
            ],
            "url": "{{api_base_url}}/api/v1/markets/{{market}}/ml/clusters",
            "description": "Latest ML clustering run: cluster profiles, sector mix, representative tickers, anomaly watch, and stability diagnostics. Descriptive analytics, not prediction."
          }
        },
        {
          "name": "Institutional holdings signals",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Accept",
                "value": "application/json"
              },
              {
                "key": "Authorization",
                "value": "Bearer {{sf_api_key}}"
              }
            ],
            "url": "{{api_base_url}}/api/v1/markets/{{market}}/whales",
            "description": "Institutional-holdings signal board: consensus, conviction, crowdedness, position deltas, and network reads from disclosure filings."
          }
        },
        {
          "name": "Sector and industry snapshot",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Accept",
                "value": "application/json"
              },
              {
                "key": "Authorization",
                "value": "Bearer {{sf_api_key}}"
              }
            ],
            "url": "{{api_base_url}}/api/v1/markets/{{market}}/sector",
            "description": "Compact sector snapshot: per-ticker daily change with market-cap-weighted sector and industry means plus whale overlay."
          }
        },
        {
          "name": "Scored market news",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Accept",
                "value": "application/json"
              },
              {
                "key": "Authorization",
                "value": "Bearer {{sf_api_key}}"
              }
            ],
            "url": "{{api_base_url}}/api/v1/markets/{{market}}/news?limit={{news_limit}}",
            "description": "Latest scored news articles with sentiment, tickers, and keywords. Query: ticker, sentiment, limit (max 50)."
          }
        },
        {
          "name": "Factor portfolios",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Accept",
                "value": "application/json"
              },
              {
                "key": "Authorization",
                "value": "Bearer {{sf_api_key}}"
              }
            ],
            "url": "{{api_base_url}}/api/v1/markets/{{market}}/factor-portfolios",
            "description": "Weekly long-only factor books (three-model; the served book family and its definition are named in the payload's labels and machine fields): publication, weekly series, per-book exposures and realised weekly returns, holdings on request, labels, caveats, degraded rule and return basis. A market without a publication answers its empty state. Query: factor, formation_date (YYYY-MM-DD), weeks (max 1000), holdings (0-5000), measurement."
          }
        },
        {
          "name": "Factor portfolio metadata",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Accept",
                "value": "application/json"
              },
              {
                "key": "Authorization",
                "value": "Bearer {{sf_api_key}}"
              }
            ],
            "url": "{{api_base_url}}/api/v1/markets/{{market}}/factor-portfolios/meta",
            "description": "Publication metadata for the long-only factor books: publications, per-model state and window, universe, hold-out, cost basis, caveats and return basis."
          }
        },
        {
          "name": "Daily research notes",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Accept",
                "value": "application/json"
              },
              {
                "key": "Authorization",
                "value": "Bearer {{sf_api_key}}"
              }
            ],
            "url": "{{api_base_url}}/api/v1/notes/daily?market={{notes_market}}",
            "description": "The complete daily research notes: per-market sections plus the global note. Query: market (default all), as_of_date."
          }
        },
        {
          "name": "Macro calendar",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Accept",
                "value": "application/json"
              },
              {
                "key": "Authorization",
                "value": "Bearer {{sf_api_key}}"
              }
            ],
            "url": "{{api_base_url}}/api/v1/macro/calendar?market={{market}}&days={{days}}",
            "description": "Per-market macro release calendar with consensus, actuals, and surprises. Query: market, days (max 60)."
          }
        },
        {
          "name": "Bond ETF board",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Accept",
                "value": "application/json"
              },
              {
                "key": "Authorization",
                "value": "Bearer {{sf_api_key}}"
              }
            ],
            "url": "{{api_base_url}}/api/v1/bond/etfs",
            "description": "Bond ETF board: AUM, expense, last close, and 1y/YTD returns for the credit and rates complex."
          }
        }
      ]
    }
  ]
}
