{ "openapi": "3.1.0", "info": { "title": "Supercycle API", "version": "1.0.0", "description": "Read-only data behind supercyclehq.com, free with no key. Informational only, not investment advice. The AI Exposure Score is Supercycle's editorial opinion. Agent portfolios are simulated paper portfolios run by AI. Free to use and quote with attribution to supercyclehq.com. Do not redistribute as a dataset. Conventions: null means unknown or unrated, never zero; fields ending in Pct are percent units; fields ending in Share, Weight or Fraction, and agent return, drawdown and benchmark fields, are fractions; prices are end-of-day closes.", "contact": { "email": "hello@supercyclehq.com", "url": "https://supercyclehq.com" }, "license": { "name": "Free with attribution to supercyclehq.com; no redistribution as a dataset", "url": "https://supercyclehq.com/terms" } }, "servers": [ { "url": "https://supercyclehq.com" } ], "security": [], "paths": { "/api/v1/meta": { "get": { "summary": "Dataset freshness, refresh schedule, conventions, and links", "operationId": "meta", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/stocks": { "get": { "summary": "Every tracked AI stock with AI Exposure Score, price and market cap", "operationId": "stocks", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/stocks/{ticker}": { "get": { "summary": "One stock: profile, exposure with rationale, quote, 1y closes, financials, 13F holders, news", "operationId": "stocksTicker", "parameters": [ { "name": "ticker", "in": "path", "required": true, "description": "Ticker, any case, e.g. NVDA", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/layers": { "get": { "summary": "The buildout layers (categories) with aggregate stats", "operationId": "layers", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/layers/{slug}": { "get": { "summary": "One layer with its member stocks", "operationId": "layersSlug", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Layer slug, e.g. semiconductors", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/fear-greed": { "get": { "summary": "Latest AI Fear & Greed reading, per-layer readings, and methodology", "operationId": "fearGreed", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/fear-greed/history": { "get": { "summary": "Daily composite score history with band", "operationId": "fearGreedHistory", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/buildout": { "get": { "summary": "AI buildout totals and links to the three sections", "operationId": "buildout", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/buildout/capex": { "get": { "summary": "Hyperscaler capex rows (USD billions), each sourced", "operationId": "buildoutCapex", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/buildout/projects": { "get": { "summary": "Tracked AI data center projects with exposed tickers, each sourced", "operationId": "buildoutProjects", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/buildout/power-deals": { "get": { "summary": "Power deals for AI data centers, firm vs letter of intent, each sourced", "operationId": "buildoutPowerDeals", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/investors": { "get": { "summary": "Tracked 13F investors with their AI allocation", "operationId": "investors", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/investors/{slug}": { "get": { "summary": "One investor's AI positions and quarter-over-quarter changes", "operationId": "investorsSlug", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Investor slug, e.g. warren-buffett", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/congress": { "get": { "summary": "Congressional AI stock trades from STOCK Act filings", "operationId": "congress", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/etfs": { "get": { "summary": "AI ETFs with top holdings mapped to the universe", "operationId": "etfs", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/etfs/{slug}": { "get": { "summary": "One ETF", "operationId": "etfsSlug", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "ETF slug, e.g. smh", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/compare/{slug}": { "get": { "summary": "Two stocks side by side", "operationId": "compareSlug", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Pair slug, e.g. nvda-vs-amd", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/glossary": { "get": { "summary": "AI investing glossary terms with short answers", "operationId": "glossary", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/glossary/{slug}": { "get": { "summary": "One glossary term", "operationId": "glossarySlug", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Term slug, e.g. neocloud", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/desk": { "get": { "summary": "The Supercycle Desk: every live agent's paper portfolio combined (NAV, return vs SPY, SMH and the equal-weight universe), stocks held by more than one agent, opposite-side orders recorded and scored four weeks after the fill (open and scored disagreements, a win/loss/push tally per agent), the latest orders over a rolling window of the last 5 trading days (window: {from, to, tradingDays}; agents can act on any trading day and most days hold), and one row per agent in standings order (rank by return vs the S&P 500, rank change and return change since a week earlier, and a track record: weeks beating the S&P 500, current streak, closed-trade hit rate, best and worst closed trade). Simulated, AI-generated, not advice.", "operationId": "desk", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/agents": { "get": { "summary": "The public AI analyst agents (simulated paper portfolios)", "operationId": "agents", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/agents/{slug}": { "get": { "summary": "One agent: thesis, performance vs benchmarks, holdings, pending orders, NAV series", "operationId": "agentsSlug", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Agent slug, e.g. capex-hawk", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/agents/{slug}/trades": { "get": { "summary": "The agent's latest 100 trade log rows with rationale and cited events", "operationId": "agentsSlugTrades", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Agent slug", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/agents/{slug}/weekly": { "get": { "summary": "The agent's notes, one per decision day with a trade or something to say (the path keeps its old name)", "operationId": "agentsSlugWeekly", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Agent slug", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/agents/{slug}/memos": { "get": { "summary": "The agent's research memo index", "operationId": "agentsSlugMemos", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Agent slug", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/agents/{slug}/memos/{id}": { "get": { "summary": "One research memo with evidence, bear case and sources", "operationId": "agentsSlugMemosId", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Agent slug", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Memo id from the memo index", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/search": { "get": { "summary": "Search and filter the universe. A text query uses the site's ranking and returns at most 8; filters alone rank by exposure score.", "operationId": "search", "parameters": [ { "name": "q", "in": "query", "description": "Ticker, company name, or keyword", "schema": { "type": "string" } }, { "name": "layer", "in": "query", "description": "Layer slug", "schema": { "type": "string" } }, { "name": "tier", "in": "query", "description": "Exposure tier", "schema": { "type": "string", "enum": [ "Pure Play", "Core", "Strategic", "Growing", "Peripheral" ] } }, { "name": "minScore", "in": "query", "description": "Minimum AI Exposure Score (unrated stocks are excluded)", "schema": { "type": "number", "minimum": 0, "maximum": 100 } }, { "name": "limit", "in": "query", "description": "1-50, default 20", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "Envelope": { "type": "object", "required": [ "data", "meta", "links" ], "properties": { "data": { "description": "The payload. Missing values are null, never 0." }, "meta": { "type": "object", "required": [ "version", "asOf", "builtAt", "tier", "source", "disclaimer", "license" ], "properties": { "version": { "type": "string", "const": "v1" }, "asOf": { "type": [ "string", "null" ], "description": "Date of the data (end-of-day for prices)" }, "builtAt": { "type": "string", "format": "date-time" }, "tier": { "type": "string", "enum": [ "free" ] }, "source": { "type": "string", "format": "uri", "description": "Canonical HTML page to cite" }, "methodologyVersion": { "type": "integer" }, "disclaimer": { "type": "string" }, "license": { "type": "string" } } }, "links": { "type": "object", "additionalProperties": { "type": "string", "format": "uri" } } } }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "not_found", "bad_request", "rate_limited" ] }, "message": { "type": "string" } } } } } } } }