{ "openapi": "3.1.0", "info": { "title": "Listed API", "version": "0.1.0", "description": "Read-only access to Listed's data: US public companies, their SEC filings, standardized XBRL financials and Form 4 insider trades, from SEC EDGAR. No prices. No account needed; send an API key or OAuth access token as a bearer token to have calls attributed to you. The same data is available over MCP at https://www.listed.markets/mcp.", "termsOfService": "https://www.listed.markets/legal/agent-api-terms" }, "servers": [ { "url": "https://www.listed.markets/api/v1" } ], "security": [ {}, { "bearer": [] } ], "paths": { "/companies": { "get": { "summary": "Search companies", "description": "Finds US public companies by name, ticker or CIK. Returns up to 25 matches, each with CIK, ticker, sector and its latest SEC filing (form, date, accession). No account needed. Free.", "parameters": [ { "name": "q", "in": "query", "description": "Name, ticker or CIK.", "schema": { "type": "string" }, "example": "nvidia" }, { "name": "limit", "in": "query", "description": "At most 25.", "schema": { "type": "integer", "minimum": 1, "maximum": 25, "default": 10 }, "example": 10 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/companies/{ref}": { "get": { "summary": "A company", "description": "Profile, trailing-twelve-month metrics, the latest annual report and links. Every metric is computed from XBRL company facts.", "parameters": [ { "name": "ref", "in": "path", "required": true, "description": "A ticker (any share class, e.g. NVDA or BRK-B) or a CIK.", "schema": { "type": "string" }, "example": "NVDA" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/companies/{ref}/financials": { "get": { "summary": "Standardized financials", "description": "Standardized income statement, balance sheet and cash-flow figures from a company's XBRL filings, quarterly or annual. Every value carries its XBRL concept, period, form, filed date and accession number, plus derived=true when a quarter was computed from year-to-date figures. When a later filing reports a period again (a prior-year comparative or a restatement), the value and its accession are from that later filing. Missing figures are omitted, never estimated. No prices. Free.", "parameters": [ { "name": "ref", "in": "path", "required": true, "description": "A ticker (any share class, e.g. NVDA or BRK-B) or a CIK.", "schema": { "type": "string" }, "example": "NVDA" }, { "name": "period", "in": "query", "description": "quarterly or annual.", "schema": { "type": "string", "enum": [ "quarterly", "annual" ], "default": "quarterly" }, "example": "quarterly" }, { "name": "periods", "in": "query", "description": "Most recent periods per line item, up to 40.", "schema": { "type": "integer", "minimum": 1, "maximum": 40, "default": 8 }, "example": 8 }, { "name": "line_items", "in": "query", "description": "Line item keys such as revenue, net_income, eps_diluted. Repeat the parameter or separate values with commas.", "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "revenue", "net_income" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/companies/{ref}/filings": { "get": { "summary": "A company's filings", "description": "Lists SEC filings, newest first, optionally for one company and filtered by form (e.g. 8-K, 10-Q, 10-K, 4), filing date range and 8-K item (e.g. 2.02 results, 5.02 officer changes). Up to 100 per call. Free.", "parameters": [ { "name": "ref", "in": "path", "required": true, "description": "A ticker (any share class, e.g. NVDA or BRK-B) or a CIK.", "schema": { "type": "string" }, "example": "NVDA" }, { "name": "forms", "in": "query", "description": "Form types. Repeat the parameter or separate values with commas.", "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "10-K", "10-Q" ] }, { "name": "from", "in": "query", "description": "Filed on or after, YYYY-MM-DD.", "schema": { "type": "string" }, "example": "2026-07-01" }, { "name": "to", "in": "query", "description": "Filed on or before, YYYY-MM-DD.", "schema": { "type": "string" }, "example": "2026-09-30" }, { "name": "items", "in": "query", "description": "8-K items such as 2.02. Repeat the parameter or separate values with commas.", "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "2.02" ] }, { "name": "limit", "in": "query", "description": "At most 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "example": 25 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/companies/{ref}/insiders": { "get": { "summary": "A company's insider transactions", "description": "Form 4 transactions by a company's insiders, or by one insider across companies. Defaults to open-market purchases (P) and sales (S). Each row has the insider, relationship, transaction code and meaning, shares, the price as reported on the Form 4 (filing data, not a market price), and the accession. Up to 100 per call. Free.", "parameters": [ { "name": "ref", "in": "path", "required": true, "description": "A ticker (any share class, e.g. NVDA or BRK-B) or a CIK.", "schema": { "type": "string" }, "example": "NVDA" }, { "name": "codes", "in": "query", "description": "Transaction codes; default P and S. Repeat the parameter or separate values with commas.", "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "P", "S" ] }, { "name": "limit", "in": "query", "description": "At most 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "example": 20 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/filings": { "get": { "summary": "Latest filings", "description": "Lists SEC filings, newest first, optionally for one company and filtered by form (e.g. 8-K, 10-Q, 10-K, 4), filing date range and 8-K item (e.g. 2.02 results, 5.02 officer changes). Up to 100 per call. Free.", "parameters": [ { "name": "forms", "in": "query", "description": "Form types. Repeat the parameter or separate values with commas.", "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "8-K" ] }, { "name": "from", "in": "query", "description": "Filed on or after, YYYY-MM-DD.", "schema": { "type": "string" }, "example": "2026-07-01" }, { "name": "to", "in": "query", "description": "Filed on or before, YYYY-MM-DD.", "schema": { "type": "string" }, "example": "2026-09-30" }, { "name": "items", "in": "query", "description": "8-K items such as 2.02. Repeat the parameter or separate values with commas.", "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "2.02" ] }, { "name": "limit", "in": "query", "description": "At most 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "example": 25 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/filings/{accession}/sections/{section}": { "get": { "summary": "A section of a 10-K or 10-Q", "description": "One section of a 10-K or 10-Q as Markdown, as filed, with its headings, lists and tables: business, risk_factors, mdna, market_risk, controls, legal, properties or cybersecurity. Returns the source URL on sec.gov. Sections are extracted on first request; if one is not ready, the tool says so and you can retry in a minute. Free.", "parameters": [ { "name": "accession", "in": "path", "required": true, "description": "Accession number, e.g. 0001045810-26-000052.", "schema": { "type": "string" }, "example": "0001045810-26-000052" }, { "name": "section", "in": "path", "required": true, "description": "Section key.", "schema": { "type": "string", "enum": [ "business", "risk_factors", "cybersecurity", "properties", "legal", "mdna", "market_risk", "controls" ] }, "example": "business" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/insiders/{cik}": { "get": { "summary": "An insider's transactions", "description": "Form 4 transactions by a company's insiders, or by one insider across companies. Defaults to open-market purchases (P) and sales (S). Each row has the insider, relationship, transaction code and meaning, shares, the price as reported on the Form 4 (filing data, not a market price), and the accession. Up to 100 per call. Free.", "parameters": [ { "name": "cik", "in": "path", "required": true, "description": "The insider's CIK.", "schema": { "type": "string" }, "example": "1197649" }, { "name": "codes", "in": "query", "description": "Transaction codes; default P and S. Repeat the parameter or separate values with commas.", "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "P", "S" ] }, { "name": "limit", "in": "query", "description": "At most 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "example": 20 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/screen": { "get": { "summary": "Screen companies", "description": "Finds companies whose computed metrics pass every filter. Metrics: revenue_ttm, revenue_yoy, gross_margin_ttm, operating_margin_ttm, net_margin_ttm, eps_diluted_ttm, free_cash_flow_ttm, cash, total_debt, net_debt, return_on_equity, current_ratio, debt_to_equity. Ratios are fractions (0.25 = 25%). A company missing a metric never passes a filter on it. Returns 25 results per call without Pro (use offset to page); unlimited per call for Pro members. Free.", "parameters": [ { "name": "filter", "in": "query", "description": "::, repeated. op is gt, gte, lt or lte.", "schema": { "type": "array", "items": { "type": "string", "pattern": "^[a-z_]+:(gt|gte|lt|lte):-?[0-9.]+$" } }, "example": [ "revenue_yoy:gt:0.2" ] }, { "name": "sector", "in": "query", "description": "Sector slug.", "schema": { "type": "string" }, "example": "technology" }, { "name": "sort", "in": "query", "description": "Metric to sort by.", "schema": { "type": "string", "enum": [ "revenue_ttm", "revenue_yoy", "gross_margin_ttm", "operating_margin_ttm", "net_margin_ttm", "eps_diluted_ttm", "free_cash_flow_ttm", "cash", "total_debt", "net_debt", "return_on_equity", "current_ratio", "debt_to_equity" ] }, "example": "revenue_ttm" }, { "name": "order", "in": "query", "description": "asc or desc.", "schema": { "type": "string", "enum": [ "asc", "desc" ] }, "example": "asc" }, { "name": "offset", "in": "query", "description": "Rows to skip.", "schema": { "type": "integer", "minimum": 0 }, "example": 0 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/activity": { "get": { "summary": "Market activity", "description": "The home page's live room as data: NYSE and Nasdaq session status and EDGAR's hours (computed from the published calendars), how many filings EDGAR listed today across EDGAR and from covered companies, by form and by hour against the prior business day, the day's insider open-market purchases and sales (reported value), the league's forecasts today, and the latest 30 filings as EDGAR listed them. scope \"covered\" (default) lists only companies Listed covers; \"all\" lists every filer. No prices. For what arrives next, subscribe to the stream at stream.url (protocol in stream.docs). Free; the API copy is limited to 60 calls a minute per address.", "parameters": [ { "name": "scope", "in": "query", "description": "covered (default) or all.", "schema": { "type": "string", "enum": [ "covered", "all" ], "default": "covered" }, "example": "covered" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/forecasters/{handle}": { "get": { "summary": "A forecaster's public track record", "description": "A forecaster's league record: each scored call with the forecast, the reported actual, the error, the score, its comment count and reasoning rating; the forecasts not yet scored (figures sealed until each target locks); and the member's season and all-time ranks. Give a handle for a member's public profile (only members who opted in). Omit the handle to get your own, which needs the read scope. Reasoning comes back exactly as written, in user_content fields, only where it is published. Free.", "parameters": [ { "name": "handle", "in": "path", "required": true, "description": "The member's handle.", "schema": { "type": "string" }, "example": "harbor_lane" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } } }, "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "An API key (llk_…) from your account, or an OAuth access token." } }, "responses": { "Error": { "description": "An error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "examples": [ "not_found" ] }, "message": { "type": "string", "examples": [ "No company matches NVDAX." ] } } } } }, "example": { "error": { "code": "not_found", "message": "No company matches NVDAX." } } } } } } } }