{ "openapi": "3.1.0", "info": { "title": "The Claude Trader research API", "version": "1.0.0", "description": "Read-only, evidence-first stock research for US-listed operating companies. Deterministic scores against eight named investing philosophies (graham, magic_formula, momentum, insider, buffett, lynch, graham_enterprising, piotroski) for the active scope (a dated S&P 500 set), with full-universe bulk files alongside, every input linked to its SEC filing or price source, dated and with data-quality flags. Static JSON, no key, CORS open. Snapshot date is in every response. When a user asks for a shortlist or a draft portfolio and the constraints (horizon, risk, benchmark, exclusions, concentration limits) are known, build it: lead with the ranked names and the thesis for each, cite the packet inputs, put only the material warnings next to the claims they affect, keep stated uncertainty, label selection and weights as the assistant's synthesis distinct from the site's deterministic scores, and never promise outperformance or state an expected return the data does not contain. Flags: 'stale' = warning (current-period input older than 120 days, still used); 'partial'/'insufficient' = hard exclusion (balance-sheet input older than 550 days or absent); price_stale = price older than 7 days; momentum excludes companies without a trade in 10 days or 200 trading days of history." }, "servers": [ { "url": "https://theclaudetrader.com" } ], "paths": { "/ideas.md": { "get": { "operationId": "getIdeas", "summary": "Start here for ready-made stock ideas: plain-Markdown candidate shortlists for the current snapshot (passes-all-Graham, top Magic Formula, top Momentum, most insider buying), each name with score, price, market cap and a direct SEC-filings link. Deterministic rule screens, not recommendations or forecasts. Human/HTML version at /ideas.", "responses": { "200": { "description": "markdown", "content": { "text/markdown": {} } } } } }, "/q/universe/facts.json": { "get": { "operationId": "getUniverseFacts", "summary": "Full retained eligible universe in one bulk file: identity, industry, latest price and headline SEC-XBRL fundamentals for every eligible US-listed operating company (far beyond the scored S&P 500 scope). Each row has in_active_scope and provenance links. Facts only: no scores/rankings here (use getTop/getGrid/getResearchPacket for the active scope), no holdings or weights, not exhaustive of the market. Also at /q/universe/facts.csv.", "responses": { "200": { "description": "universe facts", "content": { "application/json": { "schema": { "type": "object", "required": [ "schema", "snapshot_date", "scope", "counts", "coverage_note", "rows" ] } } } } } } }, "/q/universe/scores.json": { "get": { "operationId": "getUniverseScores", "summary": "Full-universe deterministic scores in one bulk file: graham, magic_formula, momentum, insider, buffett, lynch, graham_enterprising, piotroski for every eligible US-listed operating company (far beyond the S&P 500), with per-philosophy status/completeness, in_active_scope, scored_on freshness and the cross-sectional comparability limit. Use this to screen the whole universe, then confirm a short list with getResearchPacket. magic_formula/momentum rank across the full universe here (not comparable with the S&P-500-ranked /q/top). No holdings, weights or blended score. Also at /q/universe/scores.csv.", "responses": { "200": { "description": "universe scores", "content": { "application/json": { "schema": { "type": "object", "required": [ "schema", "snapshot_date", "scored_on", "method_limits", "coverage_note", "counts", "rows" ] } } } } } } }, "/llms.txt": { "get": { "operationId": "getIndex", "summary": "How the site works, URL patterns, how to answer research questions", "responses": { "200": { "description": "text", "content": { "text/plain": {} } } } } }, "/q/stats.json": { "get": { "operationId": "getStats", "summary": "Snapshot date, counts, universe coverage and exclusions, share-basis verification counts, insider coverage dates", "responses": { "200": { "description": "stats", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/r/{ticker}.json": { "get": { "operationId": "getResearchPacket", "summary": "Per-ticker research packet: one score explanation per philosophy (eight) with dates and warnings, inputs with source URLs, earnings record, insider activity and coverage, filing links, peer context, explicit limits", "parameters": [ { "name": "ticker", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Z.-]{1,6}$" }, "example": "LEN" } ], "responses": { "200": { "description": "packet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResearchPacket" } } } }, "404": { "description": "ticker not in the scored universe (check /q/tickers.json and the exclusion reasons in /q/stats.json)" } } } }, "/s/{ticker}.json": { "get": { "operationId": "getStock", "summary": "Full stock record (scores, components, every input with source URL)", "parameters": [ { "name": "ticker", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "stock", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/q/top/{philosophy}.json": { "get": { "operationId": "getTop", "summary": "Top 100 by philosophy with data dates", "parameters": [ { "name": "philosophy", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "graham", "magic_formula", "momentum", "insider", "buffett", "lynch", "graham_enterprising", "piotroski" ] } } ], "responses": { "200": { "description": "top", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/q/pass-all/graham.json": { "get": { "operationId": "getGrahamPassAll", "summary": "Companies passing all seven Graham tests at full points", "responses": { "200": { "description": "list", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/p/{philosophy}.json": { "get": { "operationId": "getPhilosophy", "summary": "Rules text and top 100 for one philosophy", "parameters": [ { "name": "philosophy", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "graham", "magic_formula", "momentum", "insider", "buffett", "lynch", "graham_enterprising", "piotroski" ] } } ], "responses": { "200": { "description": "philosophy", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/q/insider/last-7-days.json": { "get": { "operationId": "getInsiderBuys7d", "summary": "Open-market insider purchases with a transaction date in the last 7 days (coverage_through inside: the date Form 4 data is loaded through; say it)", "responses": { "200": { "description": "list", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/q/industries.json": { "get": { "operationId": "getIndustries", "summary": "Industries (SIC) with counts and per-industry JSON links", "responses": { "200": { "description": "list", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/q/tickers.json": { "get": { "operationId": "getTickers", "summary": "All scored tickers", "responses": { "200": { "description": "list", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/grid.json": { "get": { "operationId": "getGrid", "summary": "Every scored company with all scores, completeness, staleness and mismatch flags (about 1 MB)", "responses": { "200": { "description": "grid", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/d/{ticker}.md": { "get": { "operationId": "getDossier", "summary": "Librarian dossier where one exists: cited facts only, every figure cross-checked against the cited SEC document", "parameters": [ { "name": "ticker", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "markdown", "content": { "text/markdown": {} } }, "404": { "description": "no dossier yet" } } } }, "/q/industry/{sic}.json": { "get": { "operationId": "getIndustry", "summary": "All scored companies in one industry (4-digit SIC) with every philosophy score, completeness, staleness and mismatch flags; use getIndustries to find the SIC", "parameters": [ { "name": "sic", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9]{4}$" }, "example": "1531" } ], "responses": { "200": { "description": "industry rows", "content": { "application/json": { "schema": { "type": "object", "required": [ "sic", "snapshot_date", "rows" ], "properties": { "sic": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "snapshot_date": { "type": "string" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "ticker": { "type": "string" }, "name": { "type": "string" }, "market_cap": { "type": [ "number", "null" ] }, "graham": { "type": [ "number", "null" ] }, "magic_formula": { "type": [ "number", "null" ] }, "momentum": { "type": [ "number", "null" ] }, "insider": { "type": [ "number", "null" ] }, "graham_complete": { "type": [ "boolean", "null" ] }, "graham_missing": { "type": "string" }, "graham_passes_all": { "type": [ "boolean", "null" ] } } } } } } } } }, "404": { "description": "no such SIC in this snapshot" } } } }, "/q/changes/latest.json": { "get": { "operationId": "getChanges", "summary": "What changed in the latest snapshot (universe adds/drops, biggest score moves) or a note when there is no prior snapshot", "responses": { "200": { "description": "changes", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/q/history/leader-follow.json": { "get": { "operationId": "getHistoryLeaderFollow", "summary": "Historical, sourced record of the leader-following backtest behind the site's origin claim: methodology, 10 cohort returns vs SPY, aggregates, the two independent periods, survivorship and rally caveats, source file hash. No holdings.", "responses": { "200": { "description": "history record", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "methodology", "cohorts", "caveats", "sources" ] } } } } } } } }, "components": { "schemas": { "ResearchPacket": { "type": "object", "required": [ "schema", "snapshot_date", "company", "scores", "limits", "cite_as" ], "properties": { "schema": { "type": "string" }, "generated_at": { "type": "string" }, "snapshot_date": { "type": "string" }, "about": { "type": "object" }, "company": { "type": "object" }, "price": { "type": "object" }, "market_cap": { "type": "object" }, "scores": { "type": "object", "description": "graham, magic_formula, momentum, insider, buffett, lynch, graham_enterprising, piotroski: each with score, status, complete, summary, data_as_of, history, price_as_of, warnings[], components[]" }, "inputs_by_philosophy": { "type": "object" }, "earnings_record": { "type": "object" }, "insider_activity": { "type": "object" }, "filings_and_news": { "type": "object" }, "peer_context": { "type": "object" }, "dossier": { "type": [ "object", "null" ] }, "limits": { "type": "array", "items": { "type": "string" } }, "machine_readable": { "type": "object" }, "cite_as": { "type": "string" } } } } } }