{"openapi": "3.2.0", "$self": "https://www.algoum.de/v1/openapi.yaml", "info": {"title": "algoum API", "summary": "Financial Data-as-a-Service for US financial regulatory data (SEC EDGAR).", "description": "REST API that turns hard-to-access US financial regulatory data\n(SEC EDGAR) into clean, consistent JSON.\n\nData areas:\n  * Insider transactions (SEC Form 4 and Form 5) · `/v1/insider`\n  * Material events (SEC Form 8-K) · `/v1/events`\n  * Institutional holdings (SEC Form 13F) · `/v1/institutional`\n  * Shared helpers – ticker/CIK resolution, raw filings, data freshness\n\n**Authentication.** Every endpoint below `/v1` expects your API key as a\nbearer token: `Authorization: Bearer <key>`. You create and revoke the key\nyourself in the portal dashboard. Without a valid key an endpoint answers\n`401`.\n\n**Response envelope.** Every response carries the same envelope: `data`\nholds the payload, `meta` holds `request_id`, `source`, `data_freshness`,\n`next_cursor` and `warnings`. Quote `meta.request_id` in a support request.\n\n**Pagination.** List endpoints page through an opaque cursor. Pass\n`meta.next_cursor` back as `?cursor=`; `null` means you have reached the\nend. Treat the value as a black box – its content is not part of the\ncontract.\n\n**Sorting.** Every list endpoint has a fixed sort order, stated in its own\ndescription. It cannot be chosen through a parameter – that keeps the\npagination cursor stable.\n\n**Unknown query parameters** do not cause an error, but they do add a note\nto `meta.warnings`. That way a typo such as `?tickr=AAPL` does not go\nunnoticed, which would otherwise return a valid but unfiltered response.\n\n**Timestamps.** All timestamps are in Eastern Time with offset\n(`2026-08-03T15:29:25-04:00`) – the time zone the SEC reports its filings\nin. The time in `filed_at` therefore matches the time in the original\nfiling. The offset switches with US daylight saving time between `-04:00`\nand `-05:00`; if you need UTC, convert it yourself.\n\n**Rate limit.** Requests are limited per client at the edge. Going over the\nlimit answers `429`; because that answer comes from the edge rather than\nfrom the API, it does not necessarily carry the JSON error envelope. Slow\ndown and retry.\n\n**MCP.** AI assistants can use the same data through the Model Context\nProtocol: connect an MCP client with Streamable HTTP to\n`https://api.algoum.de/v1/mcp` and send your API key as bearer token.\n\nGuides with worked examples: https://www.algoum.de/docs\n", "version": "1.0.0", "license": {"name": "Proprietary", "identifier": "LicenseRef-Proprietary"}}, "externalDocs": {"description": "Guides – getting started, conventions, streaming.", "url": "https://www.algoum.de/docs"}, "servers": [{"url": "https://api.algoum.de/v1", "name": "production", "description": "Production environment."}], "tags": [{"name": "insider", "summary": "Insider transactions (Form 4)", "description": "Buys and sells reported by officers, directors and 10% owners, plus the\nsignals derived from them (cluster buys, buy/sell ratio). Source are the\nSEC forms 4 and 5, which reach the API within minutes of being filed.\n"}, {"name": "events", "summary": "Material events (Form 8-K)", "description": "Material events a company has to disclose – leadership changes, mergers,\nbankruptcies, cyber incidents and more. Available as searchable history,\nas a cross-market feed and as a push stream.\n"}, {"name": "institutional", "summary": "Institutional holdings (Form 13F)", "description": "Quarterly portfolios of institutional investors and the aggregated\npicture per stock. 13F filings are due 45 days after quarter end, so the\nmost recent quarter fills up over several weeks.\n"}, {"name": "common", "summary": "Shared helper endpoints", "description": "Ticker/CIK resolution and company search, the raw SEC filing behind every\nrecord, and the freshness of each data source.\n"}], "security": [{"bearerAuth": []}], "paths": {"/insider/transactions": {"get": {"tags": ["insider"], "operationId": "listInsiderTransactions", "summary": "Search insider trades", "description": "Searches individual insider trades, one row per reported transaction.\nFixed sort order: `filed_at` descending, then `id` descending.\n\nEither `ticker` or `cik` is required; a request without both is\nanswered with `400`. An unrestricted query would have to scan the\nwhole history.\n", "parameters": [{"$ref": "#/components/parameters/Ticker"}, {"$ref": "#/components/parameters/Cik"}, {"name": "side", "in": "query", "description": "Trade direction.", "schema": {"type": "string", "enum": ["buy", "sell"]}}, {"name": "role", "in": "query", "description": "Insider role.", "schema": {"$ref": "#/components/schemas/InsiderRole"}}, {"name": "form_type", "in": "query", "description": "Filter on the filing source (Form 4 or Form 5).", "schema": {"type": "string", "enum": ["4", "5"]}}, {"$ref": "#/components/parameters/From"}, {"$ref": "#/components/parameters/To"}, {"$ref": "#/components/parameters/Limit"}, {"$ref": "#/components/parameters/Cursor"}], "responses": {"200": {"description": "List of insider transactions.", "content": {"application/json": {"examples": {"default": {"$ref": "#/components/examples/InsiderTransactionList"}}, "schema": {"allOf": [{"$ref": "#/components/schemas/Envelope"}, {"type": "object", "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/InsiderTransaction"}}}}]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "429": {"$ref": "#/components/responses/TooManyRequests"}, "500": {"$ref": "#/components/responses/InternalServerError"}}}}, "/insider/recent": {"get": {"tags": ["insider"], "operationId": "listRecentInsiderTransactions", "summary": "Latest insider trades (cross-market feed)", "description": "Chronological feed of the latest insider trades across all companies\nover the last `days` days – no ticker/CIK required. Meant as a\ndiscovery/screening feed instead of searching symbol by symbol.\n\n`days` filters the **filing time** (`filed_at`), not the trade date.\nForm 4 may be filed up to two business days after the trade; the feed\nshows what has just become public. To filter by trade date, use\n`from`/`to` on `/insider/transactions`.\nFixed sort order: `filed_at` descending, then `id` descending.\n", "parameters": [{"name": "days", "in": "query", "description": "Look-back window in days, capped at 30.", "schema": {"type": "integer", "minimum": 1, "maximum": 30, "default": 1}}, {"name": "side", "in": "query", "description": "Trade direction; `both` = both (default).", "schema": {"type": "string", "enum": ["buy", "sell", "both"], "default": "both"}}, {"name": "role", "in": "query", "description": "Insider role.", "schema": {"$ref": "#/components/schemas/InsiderRole"}}, {"$ref": "#/components/parameters/Limit"}, {"$ref": "#/components/parameters/Cursor"}], "responses": {"200": {"description": "Chronological list of the latest insider transactions.", "content": {"application/json": {"examples": {"default": {"$ref": "#/components/examples/InsiderTransactionList"}}, "schema": {"allOf": [{"$ref": "#/components/schemas/Envelope"}, {"type": "object", "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/InsiderTransaction"}}}}]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "429": {"$ref": "#/components/responses/TooManyRequests"}, "500": {"$ref": "#/components/responses/InternalServerError"}}}}, "/insider/transactions/{id}": {"get": {"tags": ["insider"], "operationId": "getInsiderTransaction", "summary": "Get a single transaction", "description": "Returns a single transaction including its filing reference.", "parameters": [{"$ref": "#/components/parameters/PathId"}], "responses": {"200": {"description": "A single insider transaction.", "content": {"application/json": {"examples": {"default": {"$ref": "#/components/examples/InsiderTransactionItem"}}, "schema": {"allOf": [{"$ref": "#/components/schemas/Envelope"}, {"type": "object", "properties": {"data": {"$ref": "#/components/schemas/InsiderTransaction"}}}]}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/TooManyRequests"}, "500": {"$ref": "#/components/responses/InternalServerError"}}}}, "/insider/cluster-buys": {"get": {"tags": ["insider"], "operationId": "listClusterBuys", "summary": "Find cluster buys", "description": "Aggregates open-market buys across all companies within the time window\nand finds companies where at least `min_insiders` distinct insiders\nreported a buy.\nFixed sort order: number of participating insiders descending, then total value.\n\nHow the window is applied, because it decides what the signal means:\nthe window filters `transaction_date`, not the filing time. Late filings\ncan therefore add earlier trades to the current aggregate. Form 4 may be\nfiled up to two business days after a trade; Form 5 can report much older\ntrades. `sec_known_at` is the earliest stored filing time at which\n`min_insiders` distinct buyers were known for the transactions in the\ncurrent window. It is not the last filing time and does not establish\nwhen a historical rolling-window alert would have fired.\n\n`evidence` lists the contributing filing/buyer pairs once each, ordered\nby filing time, filing ID and insider name, with missing times last.\nEach pair includes the counted owner's role, optional role detail and\nthe stored reporting-owner list. Additional owners are evidence only;\nthey do not increase the buyer count. Missing owner lists are empty.\nTransaction lines still contribute individually to the existing totals.\n`rule_version` identifies the calculation rule; `window` and\n`min_insiders` identify the requested parameters. `roles` echoes the\nnormalized, deduplicated role filter in alphabetical order; an empty\narray means no role restriction. Version `cluster-buys-v1` preserves the\nname-based buyer count, transaction-date window and all form types,\nwith reported rows included without amendment replacement.\n\n`sec_known_at` is null if any contributing filing has no usable time.\nStored filing times from historical archives may have only date-level\nprecision; no intraday accuracy is inferred. The field does not prove\nan executable fill or when the API delivered the cluster.\n\nBuys are counted by distinct `insider_name`, which is the first reporting\nowner of a filing; a joint filing counts as one buyer, and spelling of\nthe same name varies between filings. All roles are included by default.\nOptional `roles=officer,director` filters the stored first owner's role\nbefore buyer count, shares, value, dates, evidence and `sec_known_at`\nare calculated. A matching additional reporting owner does not qualify\na transaction whose first owner's role was excluded. No form-type\nfilter is applied.\nOnly code `P` (open market) ever carries `side: buy`, so awards and\noption exercises are never included.\n", "parameters": [{"name": "window", "in": "query", "description": "Aggregation window, e.g. `7d`.", "schema": {"type": "string", "default": "7d", "example": "7d"}}, {"name": "min_insiders", "in": "query", "description": "Minimum number of independent buyers.", "schema": {"type": "integer", "minimum": 1, "default": 3}}, {"name": "roles", "in": "query", "description": "Optional comma-separated roles of the first reporting owner. Omit to include all roles. Values are case-insensitive, trimmed and deduplicated. Empty entries, unknown roles and repeated query parameters return 400. Applied before aggregation.", "style": "form", "explode": false, "schema": {"type": "array", "minItems": 1, "items": {"$ref": "#/components/schemas/InsiderRole"}}, "example": ["officer", "director"]}, {"$ref": "#/components/parameters/Limit"}], "responses": {"200": {"description": "Companies with a cluster-buy signal.", "content": {"application/json": {"examples": {"default": {"$ref": "#/components/examples/ClusterBuyList"}}, "schema": {"allOf": [{"$ref": "#/components/schemas/Envelope"}, {"type": "object", "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/ClusterBuy"}}}}]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "429": {"$ref": "#/components/responses/TooManyRequests"}, "500": {"$ref": "#/components/responses/InternalServerError"}}}}, "/insider/cluster-buys/stream": {"get": {"tags": ["insider"], "operationId": "streamClusterBuys", "summary": "SSE stream of new cluster buys", "description": "Server-Sent-Events stream. A message is pushed when a newly filed buy\nlifts a company from below to at least `min_insiders` distinct buyers\nunder the same rules as `/insider/cluster-buys` (`window`, `roles`).\nEvery message uses the event name `cluster_buy` and carries one\ncluster-buy object as JSON in its `data` field. Every 30 seconds without\ntraffic the server sends the SSE comment `: keepalive`.\n\nOnly buys filed after the stream service started are considered, so\nclusters that already exist are not announced, and neither are clusters\ncompleted by older filings loaded later. Further buys into an existing\ncluster and the end of a cluster are not pushed; the snapshot endpoint\nshows them. New filings are checked every few seconds; the end-to-end\nlatency has not been measured yet.\n\nMessages carry no ID, so a reconnect does not replay what was missed.\nAfter a connection drop, catch up through `/insider/cluster-buys` and\nthen keep listening. Record your own receipt time if you need it. A\nmessage is not a trading recommendation\nand says nothing about prices or executable fills.\n", "parameters": [{"$ref": "#/components/parameters/Ticker"}, {"name": "window", "in": "query", "description": "Aggregation window on the transaction date, e.g. `7d`.", "schema": {"type": "string", "default": "7d", "example": "7d"}}, {"name": "min_insiders", "in": "query", "description": "Number of distinct buyers that triggers a message.", "schema": {"type": "integer", "minimum": 1, "default": 3}}, {"name": "roles", "in": "query", "description": "Optional comma-separated roles of the first reporting owner, with the same rules as for `/insider/cluster-buys`. Omit for all roles.", "style": "form", "explode": false, "schema": {"type": "array", "minItems": 1, "items": {"$ref": "#/components/schemas/InsiderRole"}}, "example": ["officer", "director"]}], "responses": {"200": {"description": "Continuous cluster-buy stream.", "content": {"text/event-stream": {"itemSchema": {"$ref": "#/components/schemas/ClusterBuy"}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "429": {"$ref": "#/components/responses/TooManyRequests"}, "503": {"$ref": "#/components/responses/ServiceUnavailable"}}}}, "/insider/confidence": {"get": {"tags": ["insider"], "operationId": "getInsiderConfidence", "summary": "Officer buy/sell ratio", "description": "Computes the buy/sell ratio of the reporting officers over a time\nwindow and returns a ratio score from -1 to +1 as well as the absolute\ncapital invested.\n\n**All §16 officers** are taken into account, not just CEO and CFO. The\nreporter's job title is in `role_detail` of the individual transactions;\nto filter more narrowly, evaluate it via `/insider/transactions`.\n", "parameters": [{"$ref": "#/components/parameters/TickerRequired"}, {"name": "window", "in": "query", "description": "Observation period.", "schema": {"type": "string", "default": "90d", "example": "90d"}}], "responses": {"200": {"description": "Confidence metric for one instrument.", "content": {"application/json": {"examples": {"default": {"$ref": "#/components/examples/ConfidenceItem"}}, "schema": {"allOf": [{"$ref": "#/components/schemas/Envelope"}, {"type": "object", "properties": {"data": {"$ref": "#/components/schemas/Confidence"}}}]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "429": {"$ref": "#/components/responses/TooManyRequests"}, "500": {"$ref": "#/components/responses/InternalServerError"}}}}, "/events": {"get": {"tags": ["events"], "operationId": "listEvents", "summary": "Search material events", "description": "Searches the REST history of material events.\nFixed sort order: `filed_at` descending, then `id` descending.\n\nEither `ticker` or `cik` is required; a request without both is\nanswered with `400`. An unrestricted query would have to scan the\nwhole history.\n\n`ticker` matches the symbol at the time of the filing (see `Event`).\nFor the full history of a company that changed its ticker, filter by\n`cik` instead.\n", "parameters": [{"$ref": "#/components/parameters/Ticker"}, {"$ref": "#/components/parameters/Cik"}, {"name": "event_type", "in": "query", "description": "Filter on a taxonomy type.", "schema": {"$ref": "#/components/schemas/EventType"}}, {"$ref": "#/components/parameters/From"}, {"$ref": "#/components/parameters/To"}, {"$ref": "#/components/parameters/Limit"}, {"$ref": "#/components/parameters/Cursor"}], "responses": {"200": {"description": "List of material events.", "content": {"application/json": {"examples": {"default": {"$ref": "#/components/examples/EventList"}}, "schema": {"allOf": [{"$ref": "#/components/schemas/Envelope"}, {"type": "object", "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/Event"}}}}]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "429": {"$ref": "#/components/responses/TooManyRequests"}, "500": {"$ref": "#/components/responses/InternalServerError"}}}}, "/events/recent": {"get": {"tags": ["events"], "operationId": "listRecentEvents", "summary": "Most recently filed events (minute window)", "description": "Returns the material events filed in the last `minutes` minutes across\nall companies – no ticker/CIK required. Filters on the filing time\n(`filed_at`).\nFixed sort order: `filed_at` descending, then `id` descending.\n", "parameters": [{"name": "minutes", "in": "query", "description": "Look-back window in minutes (capped at 10080 = 7 days).", "schema": {"type": "integer", "minimum": 1, "maximum": 10080, "default": 15}}, {"$ref": "#/components/parameters/Ticker"}, {"$ref": "#/components/parameters/Cik"}, {"name": "event_type", "in": "query", "description": "Filter on a taxonomy type.", "schema": {"$ref": "#/components/schemas/EventType"}}, {"$ref": "#/components/parameters/Limit"}, {"$ref": "#/components/parameters/Cursor"}], "responses": {"200": {"description": "Most recently filed material events.", "content": {"application/json": {"examples": {"default": {"$ref": "#/components/examples/EventList"}}, "schema": {"allOf": [{"$ref": "#/components/schemas/Envelope"}, {"type": "object", "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/Event"}}}}]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "429": {"$ref": "#/components/responses/TooManyRequests"}, "500": {"$ref": "#/components/responses/InternalServerError"}}}}, "/events/{id}": {"get": {"tags": ["events"], "operationId": "getEvent", "summary": "Get a single event", "description": "Returns a single event including item code and source document.", "parameters": [{"$ref": "#/components/parameters/PathId"}], "responses": {"200": {"description": "A single material event.", "content": {"application/json": {"examples": {"default": {"$ref": "#/components/examples/EventItem"}}, "schema": {"allOf": [{"$ref": "#/components/schemas/Envelope"}, {"type": "object", "properties": {"data": {"$ref": "#/components/schemas/Event"}}}]}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/TooManyRequests"}, "500": {"$ref": "#/components/responses/InternalServerError"}}}}, "/events/stream": {"get": {"tags": ["events"], "operationId": "streamEvents", "summary": "SSE stream of new events", "description": "Server-Sent-Events stream. The client connects once and has new events\npushed to it as soon as they are processed. Every message uses the event\nname `event` and carries one serialised event object as JSON in its\n`data` field. Every 30 seconds without traffic the server sends the SSE\ncomment `: keepalive`, so a dead connection is noticed.\n\nObserved latency from filing at the SEC to delivery: median 39.8 seconds\nover 14 days of live operation, about 18 seconds of which pass at the\nSEC itself (from acceptance to visibility in its feed). This is a push\nwithin seconds, not within milliseconds, and it is an observation rather\nthan a guaranteed figure.\n\nMessages carry no ID, so a reconnect does not replay what was missed.\nAfter a connection drop, catch up through `/events/recent` and then keep\nlistening. The stream guide walks through a complete client.\n", "externalDocs": {"description": "Streaming guide – reconnect, catching up, example client.", "url": "https://www.algoum.de/docs/streaming"}, "parameters": [{"$ref": "#/components/parameters/Ticker"}, {"name": "event_type", "in": "query", "description": "Stream only events of this type.", "schema": {"$ref": "#/components/schemas/EventType"}}], "responses": {"200": {"description": "Continuous event stream.", "content": {"text/event-stream": {"itemSchema": {"$ref": "#/components/schemas/Event"}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "429": {"$ref": "#/components/responses/TooManyRequests"}, "503": {"$ref": "#/components/responses/ServiceUnavailable"}}}}, "/institutional/funds": {"get": {"tags": ["institutional"], "operationId": "listFunds", "summary": "Search funds/managers", "description": "Searches funds/managers by free text or CIK.\nFixed sort order: fund name ascending.\n", "parameters": [{"name": "query", "in": "query", "description": "Free text, e.g. “Bridgewater”.", "schema": {"type": "string"}}, {"$ref": "#/components/parameters/Cik"}, {"$ref": "#/components/parameters/Limit"}, {"$ref": "#/components/parameters/Cursor"}], "responses": {"200": {"description": "List of funds/managers.", "content": {"application/json": {"examples": {"default": {"$ref": "#/components/examples/FundList"}}, "schema": {"allOf": [{"$ref": "#/components/schemas/Envelope"}, {"type": "object", "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/Fund"}}}}]}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "429": {"$ref": "#/components/responses/TooManyRequests"}, "500": {"$ref": "#/components/responses/InternalServerError"}}}}, "/institutional/funds/{id}/holdings": {"get": {"tags": ["institutional"], "operationId": "getFundHoldings", "summary": "Get a fund's portfolio", "description": "Returns the complete portfolio of a fund for one quarter.\nWithout `quarter`, the latest quarter **of that fund** is used. 13F has a\n45-day filing deadline, so a fund is regularly missing from the most\nrecent quarter; the globally latest quarter would yield an empty list\nfor it.\n\nA fund we hold no 13F filing for at all answers `404`. A fund that does\nexist but reported nothing for the requested quarter answers `200` with\nan empty list plus a note in `meta.warnings` naming its most recent\nreported quarter. Because of the filing deadline that second case is\nroutine rather than an error, and the two are worth telling apart.\nFixed sort order: position value descending, then `id`.\n\nThe path segment is the fund's CIK. Leading zeros are optional:\n`0001067983` and `1067983` address the same fund.\n", "parameters": [{"$ref": "#/components/parameters/PathId"}, {"$ref": "#/components/parameters/Quarter"}, {"$ref": "#/components/parameters/Limit"}, {"$ref": "#/components/parameters/Cursor"}], "responses": {"200": {"description": "Holdings of the fund in that quarter.", "content": {"application/json": {"examples": {"default": {"$ref": "#/components/examples/HoldingList"}}, "schema": {"allOf": [{"$ref": "#/components/schemas/Envelope"}, {"type": "object", "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/Holding"}}}}]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/TooManyRequests"}, "500": {"$ref": "#/components/responses/InternalServerError"}}}}, "/institutional/holdings": {"get": {"tags": ["institutional"], "operationId": "listHoldingsByStock", "summary": "Who holds a stock?", "description": "Returns all funds holding a position in the requested instrument.\nFixed sort order: position value descending, then `id`.\n", "parameters": [{"$ref": "#/components/parameters/TickerRequired"}, {"$ref": "#/components/parameters/Quarter"}, {"$ref": "#/components/parameters/Limit"}, {"$ref": "#/components/parameters/Cursor"}], "responses": {"200": {"description": "Funds with a position in the instrument.", "content": {"application/json": {"examples": {"default": {"$ref": "#/components/examples/HoldingList"}}, "schema": {"allOf": [{"$ref": "#/components/schemas/Envelope"}, {"type": "object", "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/Holding"}}}}]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "429": {"$ref": "#/components/responses/TooManyRequests"}, "500": {"$ref": "#/components/responses/InternalServerError"}}}}, "/institutional/sentiment": {"get": {"tags": ["institutional"], "operationId": "getInstitutionalSentiment", "summary": "Aggregated buy/sell picture per stock", "description": "Aggregates the buy/sell picture of a stock across all funds for one\nquarter. Note: 13F values are reported holdings, not actual cash flow.\n", "parameters": [{"$ref": "#/components/parameters/TickerRequired"}, {"$ref": "#/components/parameters/Quarter"}], "responses": {"200": {"description": "Aggregated institutional sentiment.", "content": {"application/json": {"examples": {"default": {"$ref": "#/components/examples/SentimentItem"}}, "schema": {"allOf": [{"$ref": "#/components/schemas/Envelope"}, {"type": "object", "properties": {"data": {"$ref": "#/components/schemas/InstitutionalSentiment"}}}]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "429": {"$ref": "#/components/responses/TooManyRequests"}, "500": {"$ref": "#/components/responses/InternalServerError"}}}}, "/institutional/disclosures": {"get": {"tags": ["institutional"], "operationId": "listInstitutionalDisclosures", "summary": "Most recently filed 13F disclosures", "description": "13F filings most recently submitted to the SEC, in chronological order\nby filing time (`filed_at`) and aggregated at fund level (not as a\nsingle-position feed). Unlike `insider/recent` this is not a feed of\nindividual transactions: 13F holdings are quarterly snapshots; the\n“freshness” dimension is the filing time of the disclosure.\nFixed sort order: `filed_at` descending, then `filing_id`.\n", "parameters": [{"name": "days", "in": "query", "description": "Window over the filing time in days, capped at 90.", "schema": {"type": "integer", "minimum": 1, "maximum": 90, "default": 7}}, {"$ref": "#/components/parameters/Quarter"}, {"$ref": "#/components/parameters/Limit"}, {"$ref": "#/components/parameters/Cursor"}], "responses": {"200": {"description": "Most recently filed disclosures (fund level).", "content": {"application/json": {"examples": {"default": {"$ref": "#/components/examples/DisclosureList"}}, "schema": {"allOf": [{"$ref": "#/components/schemas/Envelope"}, {"type": "object", "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/Disclosure"}}}}]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "429": {"$ref": "#/components/responses/TooManyRequests"}, "500": {"$ref": "#/components/responses/InternalServerError"}}}}, "/tickers": {"get": {"tags": ["common"], "operationId": "resolveTickers", "summary": "Ticker⇄CIK resolution / company search", "description": "Resolves a ticker or a CIK, or searches companies by free text.\nFixed sort order for the free-text search: best name match first.\n\nEither `query`, `ticker` or `cik` is required; a request without any of\nthem is answered with `400`.\n", "parameters": [{"name": "query", "in": "query", "description": "Free-text company search.", "schema": {"type": "string"}}, {"$ref": "#/components/parameters/Ticker"}, {"$ref": "#/components/parameters/Cik"}, {"$ref": "#/components/parameters/Limit"}, {"$ref": "#/components/parameters/Cursor"}], "responses": {"200": {"description": "Matching tickers/companies.", "content": {"application/json": {"examples": {"default": {"$ref": "#/components/examples/TickerList"}}, "schema": {"allOf": [{"$ref": "#/components/schemas/Envelope"}, {"type": "object", "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/TickerEntry"}}}}]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "429": {"$ref": "#/components/responses/TooManyRequests"}, "503": {"$ref": "#/components/responses/ServiceUnavailable"}}}}, "/filings/{id}": {"get": {"tags": ["common"], "operationId": "getFiling", "summary": "Get a raw SEC filing", "description": "Metadata and source URL of the originating filing behind all modules.", "parameters": [{"$ref": "#/components/parameters/PathId"}], "responses": {"200": {"description": "Filing metadata.", "content": {"application/json": {"examples": {"default": {"$ref": "#/components/examples/FilingItem"}}, "schema": {"allOf": [{"$ref": "#/components/schemas/Envelope"}, {"type": "object", "properties": {"data": {"$ref": "#/components/schemas/Filing"}}}]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/TooManyRequests"}, "500": {"$ref": "#/components/responses/InternalServerError"}}}}, "/status": {"get": {"tags": ["common"], "operationId": "getStatus", "summary": "Data freshness per source", "description": "Data freshness and last successful import per source.\nFixed sort order: form type ascending.\n", "responses": {"200": {"description": "Current import status.", "content": {"application/json": {"examples": {"default": {"$ref": "#/components/examples/StatusList"}}, "schema": {"allOf": [{"$ref": "#/components/schemas/Envelope"}, {"type": "object", "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/SourceStatus"}}}}]}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "429": {"$ref": "#/components/responses/TooManyRequests"}, "500": {"$ref": "#/components/responses/InternalServerError"}}}}}, "components": {"securitySchemes": {"bearerAuth": {"type": "http", "scheme": "bearer", "description": "Your own API key as a bearer token (`Authorization: Bearer <key>`)."}}, "parameters": {"Ticker": {"name": "ticker", "in": "query", "description": "Stock ticker (preferred instrument filter), e.g. `AAPL`.", "schema": {"type": "string", "example": "AAPL"}}, "TickerRequired": {"name": "ticker", "in": "query", "required": true, "description": "Stock ticker, e.g. `AAPL`.", "schema": {"type": "string", "example": "AAPL"}}, "Cik": {"name": "cik", "in": "query", "description": "Central Index Key (alternative to the ticker). Leading zeros are optional: `0000320193` and `320193` return the same rows. In responses the key is always ten digits, so it is safe to use as a join key.", "schema": {"type": "string", "example": "0000320193"}}, "From": {"name": "from", "in": "query", "description": "First day of the window (`YYYY-MM-DD`), inclusive. Filtering happens on a pure date field; of an RFC 3339 value only the calendar day counts.", "schema": {"type": "string", "format": "date"}}, "To": {"name": "to", "in": "query", "description": "Last day of the window (`YYYY-MM-DD`), inclusive. Filtering happens on a pure date field; of an RFC 3339 value only the calendar day counts.", "schema": {"type": "string", "format": "date"}}, "Limit": {"name": "limit", "in": "query", "description": "Maximum number of results.", "schema": {"type": "integer", "minimum": 1, "maximum": 500, "default": 50}}, "Cursor": {"name": "cursor", "in": "query", "description": "Opaque cursor for the next page.", "schema": {"type": "string"}}, "Quarter": {"name": "quarter", "in": "query", "description": "Reporting quarter, e.g. `2026-Q1`.", "schema": {"type": "string", "pattern": "^\\d{4}-Q[1-4]$", "example": "2026-Q1"}}, "PathId": {"name": "id", "in": "path", "required": true, "description": "Resource ID.", "schema": {"type": "string"}}}, "responses": {"BadRequest": {"description": "Invalid request parameters.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}}}}, "Unauthorized": {"description": "Missing or invalid API key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}}}}, "NotFound": {"description": "Resource not found.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}}}}, "InternalServerError": {"description": "Unexpected server-side error, error code `internal_error`. The message is always the same; the cause stays in the server log, keyed by the `request_id` that the response repeats. Quote it in a support request.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}}}}, "TooManyRequests": {"description": "Rate limit exceeded. The rejection is issued at the edge, in front of the API, so it does not necessarily carry the JSON error envelope and has no `request_id`. Slow down and retry.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}}}}, "ServiceUnavailable": {"description": "A prerequisite of the endpoint is not ready: the ticker universe is still loading, or the event stream is not running. Temporary – retrying later is worthwhile.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}}}}}, "examples": {"InsiderTransactionList": {"summary": "Two insider trades of one company", "value": {"meta": {"request_id": "req_01K4W7YV8Q2N", "source": "sec_edgar", "data_freshness": "2026-07-13T21:05:00-04:00", "next_cursor": "eyJvIjo1MH0", "warnings": []}, "data": [{"ticker": "AAPL", "cik": "0000320193", "insider_name": "Cook Timothy D", "role": "officer", "role_detail": "Chief Executive Officer", "reporting_owners": [{"name": "Cook Timothy D", "cik": "0001214128", "role": "officer", "role_detail": "Chief Executive Officer"}], "side": "sell", "code": "S", "form_type": "4", "shares": 511000, "price": {"amount": 190.12, "currency": "USD"}, "transaction_date": "2026-07-10", "filed_at": "2026-07-11T21:03:00-04:00", "is_10b5_1": true, "ownership": "direct", "shares_owned_after": 3280000, "filing_id": "0000320193-26-000073", "source_url": "https://www.sec.gov/Archives/edgar/data/320193/000032019326000073/xslF345X05/wf-form4.xml"}, {"ticker": "AAPL", "cik": "0000320193", "insider_name": "Adams Katherine L", "role": "officer", "role_detail": "General Counsel", "reporting_owners": [{"name": "Adams Katherine L", "cik": "0001647728", "role": "officer", "role_detail": "General Counsel"}], "side": "buy", "code": "P", "form_type": "4", "shares": 12000, "price": {"amount": 188.4, "currency": "USD"}, "transaction_date": "2026-07-08", "filed_at": "2026-07-09T18:22:00-04:00", "is_10b5_1": null, "ownership": "indirect", "ownership_detail": "By family trust", "shares_owned_after": 96500, "filing_id": "0000320193-26-000071", "source_url": "https://www.sec.gov/Archives/edgar/data/320193/000032019326000071/xslF345X05/wf-form4.xml"}]}}, "InsiderTransactionItem": {"summary": "A single insider trade", "value": {"meta": {"request_id": "req_01K4W80MPT7C", "source": "sec_edgar", "data_freshness": "2026-07-13T21:05:00-04:00", "next_cursor": null, "warnings": []}, "data": {"ticker": "AAPL", "cik": "0000320193", "insider_name": "Cook Timothy D", "role": "officer", "role_detail": "Chief Executive Officer", "reporting_owners": [{"name": "Cook Timothy D", "cik": "0001214128", "role": "officer", "role_detail": "Chief Executive Officer"}], "side": "sell", "code": "S", "form_type": "4", "shares": 511000, "price": {"amount": 190.12, "currency": "USD"}, "transaction_date": "2026-07-10", "filed_at": "2026-07-11T21:03:00-04:00", "is_10b5_1": true, "ownership": "direct", "shares_owned_after": 3280000, "filing_id": "0000320193-26-000073", "source_url": "https://www.sec.gov/Archives/edgar/data/320193/000032019326000073/xslF345X05/wf-form4.xml"}}}, "ClusterBuyList": {"summary": "Companies with several buying insiders", "value": {"meta": {"request_id": "req_01K4W81Z4H9D", "source": "sec_edgar", "data_freshness": "2026-07-13T21:05:00-04:00", "next_cursor": null, "warnings": []}, "data": [{"ticker": "RDFN", "cik": "0001382821", "insider_count": 4, "total_shares": 82000, "total_value": {"amount": 1.2464e+06, "currency": "USD"}, "window": "7d", "roles": [], "first_buy_date": "2026-07-08", "last_buy_date": "2026-07-13", "min_insiders": 3, "rule_version": "cluster-buys-v1", "sec_known_at": "2026-07-13T10:00:00-04:00", "evidence": [{"filing_id": "0001382821-26-000101", "insider_name": "Example Insider A", "role": "officer", "role_detail": "CEO", "reporting_owners": [{"name": "Example Insider A", "cik": "0000000001", "role": "officer", "role_detail": "CEO"}], "filed_at": "2026-07-09T10:00:00-04:00", "source_url": "https://www.sec.gov/Archives/edgar/data/1382821/000138282126000101/primary_doc.xml"}, {"filing_id": "0001382821-26-000102", "insider_name": "Example Insider B", "role": "director", "reporting_owners": [], "filed_at": "2026-07-10T11:00:00-04:00", "source_url": "https://www.sec.gov/Archives/edgar/data/1382821/000138282126000102/primary_doc.xml"}, {"filing_id": "0001382821-26-000103", "insider_name": "Example Insider C", "role": "10%-owner", "reporting_owners": [], "filed_at": "2026-07-13T10:00:00-04:00", "source_url": "https://www.sec.gov/Archives/edgar/data/1382821/000138282126000103/primary_doc.xml"}, {"filing_id": "0001382821-26-000104", "insider_name": "Example Insider D", "role": "other", "reporting_owners": [], "filed_at": "2026-07-13T16:00:00-04:00", "source_url": "https://www.sec.gov/Archives/edgar/data/1382821/000138282126000104/primary_doc.xml"}]}, {"ticker": "PLAB", "cik": "0000806968", "insider_count": 3, "total_shares": 21500, "total_value": {"amount": 452150.0, "currency": "USD"}, "window": "7d", "roles": [], "first_buy_date": "2026-07-09", "last_buy_date": "2026-07-12", "min_insiders": 3, "rule_version": "cluster-buys-v1", "sec_known_at": null, "evidence": [{"filing_id": "0000806968-26-000101", "insider_name": "Example Insider A", "role": "officer", "reporting_owners": [], "filed_at": "2026-07-10T10:00:00-04:00", "source_url": "https://www.sec.gov/Archives/edgar/data/806968/000080696826000101/primary_doc.xml"}, {"filing_id": "0000806968-26-000102", "insider_name": "Example Insider B", "role": "director", "reporting_owners": [], "filed_at": "2026-07-13T10:00:00-04:00", "source_url": "https://www.sec.gov/Archives/edgar/data/806968/000080696826000102/primary_doc.xml"}, {"filing_id": "0000806968-26-000103", "insider_name": "Example Insider C", "role": "director", "reporting_owners": [], "filed_at": null, "source_url": "https://www.sec.gov/Archives/edgar/data/806968/000080696826000103/primary_doc.xml"}]}]}}, "ConfidenceItem": {"summary": "Officer buy/sell ratio over 90 days", "value": {"meta": {"request_id": "req_01K4W82F6R1M", "source": "sec_edgar", "data_freshness": "2026-07-13T21:05:00-04:00", "next_cursor": null, "warnings": []}, "data": {"ticker": "AAPL", "window": "90d", "score": 0.42, "buys": 17, "sells": 7, "net_invested": {"amount": 4.82e+06, "currency": "USD"}}}}, "EventList": {"summary": "Two material events", "value": {"meta": {"request_id": "req_01K4W83T2K5B", "source": "sec_edgar", "data_freshness": "2026-07-15T13:42:00-04:00", "next_cursor": "eyJvIjo1MH0", "warnings": []}, "data": [{"ticker": "XYZ", "cik": "0001234567", "event_type": "bankruptcy", "item_code": "1.03", "title": "Chapter 11 Bankruptcy Filing", "event_date": "2026-07-15", "filed_at": "2026-07-15T13:42:00-04:00", "filing_id": "0001234567-26-000045", "source_url": "https://www.sec.gov/Archives/edgar/data/1234567/000123456726000045/form8k.htm"}, {"ticker": "XYZ", "cik": "0001234567", "event_type": "leadership_change", "item_code": "5.02", "title": "Departure of Chief Financial Officer", "event_date": "2026-07-02", "filed_at": "2026-07-02T16:11:00-04:00", "filing_id": "0001234567-26-000039", "source_url": "https://www.sec.gov/Archives/edgar/data/1234567/000123456726000039/form8k.htm"}]}}, "EventItem": {"summary": "A single material event", "value": {"meta": {"request_id": "req_01K4W84B8V3Q", "source": "sec_edgar", "data_freshness": "2026-07-15T13:42:00-04:00", "next_cursor": null, "warnings": []}, "data": {"ticker": "XYZ", "cik": "0001234567", "event_type": "bankruptcy", "item_code": "1.03", "title": "Chapter 11 Bankruptcy Filing", "event_date": "2026-07-15", "filed_at": "2026-07-15T13:42:00-04:00", "filing_id": "0001234567-26-000045", "source_url": "https://www.sec.gov/Archives/edgar/data/1234567/000123456726000045/form8k.htm"}}}, "FundList": {"summary": "Funds matching a free-text search", "value": {"meta": {"request_id": "req_01K4W85D1F8T", "source": "sec_edgar", "data_freshness": "2026-05-15T20:10:00-04:00", "next_cursor": null, "warnings": []}, "data": [{"cik": "0001067983", "name": "Berkshire Hathaway Inc", "latest_quarter": "2026-Q1"}, {"cik": "0001350694", "name": "Bridgewater Associates LP", "latest_quarter": "2026-Q1"}]}}, "HoldingList": {"summary": "Positions of one quarter", "value": {"meta": {"request_id": "req_01K4W86H5G2W", "source": "sec_edgar", "data_freshness": "2026-05-15T20:10:00-04:00", "next_cursor": "eyJvIjo1MH0", "warnings": []}, "data": [{"fund_name": "Berkshire Hathaway Inc", "fund_cik": "0001067983", "ticker": "AAPL", "cusip": "037833100", "issuer_name": "APPLE INC", "shares": 300000000, "value": {"amount": 5.7036e+10, "currency": "USD"}, "put_call": null, "quarter": "2026-Q1", "filed_at": "2026-05-15T20:10:00-04:00", "filing_id": "0001067983-26-000012"}, {"fund_name": "Berkshire Hathaway Inc", "fund_cik": "0001067983", "ticker": "KO", "cusip": "191216100", "issuer_name": "COCA COLA CO", "shares": 400000000, "value": {"amount": 2.76e+10, "currency": "USD"}, "put_call": null, "quarter": "2026-Q1", "filed_at": "2026-05-15T20:10:00-04:00", "filing_id": "0001067983-26-000012"}]}}, "SentimentItem": {"summary": "Aggregated institutional picture of one stock", "value": {"meta": {"request_id": "req_01K4W87M9J4Y", "source": "sec_edgar", "data_freshness": "2026-05-15T20:10:00-04:00", "next_cursor": null, "warnings": ["The filing deadline of quarter 2026-Q1 has not passed yet; the picture is incomplete."]}, "data": {"ticker": "NVDA", "quarter": "2026-Q1", "funds_holding": 570, "funds_increased": 450, "funds_decreased": 120, "funds_new": 65, "funds_exited": 38, "total_shares": 1820000000, "total_value": {"amount": 2.14e+11, "currency": "USD"}, "quarter_complete": false, "filing_deadline": "2026-08-14"}}}, "DisclosureList": {"summary": "Most recently filed 13F disclosures", "value": {"meta": {"request_id": "req_01K4W88P3L6Z", "source": "sec_edgar", "data_freshness": "2026-05-15T20:10:00-04:00", "next_cursor": null, "warnings": []}, "data": [{"fund_name": "Berkshire Hathaway Inc", "fund_cik": "0001067983", "quarter": "2026-Q1", "filed_at": "2026-05-15T20:10:00-04:00", "holdings_count": 42, "total_value": {"amount": 3.02e+11, "currency": "USD"}, "filing_id": "0001067983-26-000012"}, {"fund_name": "Bridgewater Associates LP", "fund_cik": "0001350694", "quarter": "2026-Q1", "filed_at": "2026-05-14T18:45:00-04:00", "holdings_count": 812, "total_value": {"amount": 2.14e+10, "currency": "USD"}, "filing_id": "0001350694-26-000008"}]}}, "TickerList": {"summary": "Resolution of one ticker", "value": {"meta": {"request_id": "req_01K4W89S7N8A", "source": "sec_edgar", "next_cursor": null, "warnings": []}, "data": [{"ticker": "AAPL", "cik": "0000320193", "name": "Apple Inc."}]}}, "FilingItem": {"summary": "The raw filing behind a record", "value": {"meta": {"request_id": "req_01K4W8AV2Q1B", "source": "sec_edgar", "data_freshness": "2026-07-13T21:05:00-04:00", "next_cursor": null, "warnings": []}, "data": {"filing_id": "0000320193-26-000073", "accession_number": "0000320193-26-000073", "form_type": "4", "cik": "0000320193", "filed_at": "2026-07-11T21:03:00-04:00", "source_url": "https://www.sec.gov/Archives/edgar/data/320193/000032019326000073/0000320193-26-000073-index.htm"}}}, "StatusList": {"summary": "Freshness per source", "value": {"meta": {"request_id": "req_01K4W8B27S3C", "source": "sec_edgar", "data_freshness": "2026-07-15T13:42:00-04:00", "next_cursor": null, "warnings": []}, "data": [{"source": "sec_edgar", "form_type": "4", "last_import_at": "2026-07-15T13:58:00-04:00", "filings": 412873, "healthy": true}, {"source": "sec_edgar", "form_type": "8-K", "last_import_at": "2026-07-15T13:59:00-04:00", "filings": 98211, "healthy": true}, {"source": "sec_edgar", "form_type": "13F-HR", "last_import_at": "2026-05-16T02:10:00-04:00", "filings": 7421, "healthy": true}]}}}, "schemas": {"Money": {"type": "object", "description": "Monetary amount with currency.", "required": ["amount", "currency"], "properties": {"amount": {"type": "number", "example": 190.12}, "currency": {"type": "string", "example": "USD"}}}, "Meta": {"type": "object", "description": "Uniform metadata present in every response.", "required": ["request_id", "source"], "properties": {"request_id": {"type": "string", "example": "req_01H..."}, "source": {"type": "string", "example": "sec_edgar"}, "data_freshness": {"type": "string", "format": "date-time", "description": "Filing time of the most recently processed filing. Absent as long as no data has been imported – no freshness is claimed in that case.", "example": "2026-07-13T21:05:00-04:00"}, "next_cursor": {"type": ["string", "null"], "description": "Cursor for the next page; `null` at the end."}, "warnings": {"type": "array", "items": {"type": "string"}}}}, "Envelope": {"type": "object", "description": "Uniform response envelope. `data` is specialised per endpoint.", "required": ["meta"], "properties": {"meta": {"$ref": "#/components/schemas/Meta"}}}, "ErrorResponse": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "example": "invalid_parameter"}, "message": {"type": "string", "example": "Parameter 'ticker' or 'cik' is required."}, "request_id": {"type": "string", "example": "req_01H..."}}}}}, "InsiderRole": {"type": "string", "description": "Relationship of the reporter to the issuer, taken from the four check boxes of the Form 4 section “Relationship of Reporting Person(s) to Issuer”. `other` stands for the *Other* box; the label entered there (e.g. “Trustee”) is in `role_detail`.", "enum": ["officer", "director", "10%-owner", "other"]}, "ReportingOwner": {"type": "object", "description": "A reporting person or entity of a §16 filing.", "required": ["name", "cik", "role"], "properties": {"name": {"type": "string", "example": "Cook Timothy D"}, "cik": {"type": "string", "example": "0001214128"}, "role": {"$ref": "#/components/schemas/InsiderRole"}, "role_detail": {"type": "string", "description": "Free text from the filing about the role: for `officer` the job title, for `other` the kind of relationship.", "example": "Trustee"}}}, "InsiderTransaction": {"type": "object", "required": ["ticker", "cik", "insider_name", "role", "side", "shares", "price", "transaction_date", "filed_at", "filing_id", "source_url", "reporting_owners"], "properties": {"ticker": {"type": "string", "example": "AAPL"}, "cik": {"type": "string", "example": "0000320193"}, "insider_name": {"type": "string", "example": "Cook Timothy D"}, "role": {"$ref": "#/components/schemas/InsiderRole"}, "role_detail": {"type": "string", "description": "Free text from the filing about the role: for `officer` the job title, for `other` the kind of relationship. Not set for `director` and `10%-owner`, and otherwise only when the filing states it.", "example": "Chief Financial Officer"}, "reporting_owners": {"type": "array", "description": "All reporters of the filing. A joint filing (a fund, its general partner and the acting person, for instance) lists several; the transaction itself is still reported only once and appears here once. `insider_name`, `role` and `role_detail` describe the first entry of this list.", "items": {"$ref": "#/components/schemas/ReportingOwner"}}, "side": {"type": "string", "enum": ["buy", "sell", ""], "description": "Trade direction; empty for Form 5 codes without buy/sell."}, "code": {"type": "string", "description": "Raw SEC transaction code (P, S, G, A, …).", "example": "P"}, "form_type": {"type": "string", "enum": ["4", "5"], "description": "Source of the transaction – Form 4 (ongoing) or Form 5 (annual report)."}, "shares": {"type": "number", "example": 511000}, "price": {"oneOf": [{"$ref": "#/components/schemas/Money"}, {"type": "null"}], "description": "Price per share. `null` when the filing states none – that happens when a trade consisted of several partial executions at different prices and the reporter gives the price in a footnote instead. A reported price of `0` is a real statement, by contrast."}, "transaction_date": {"type": "string", "format": "date", "example": "2026-07-10"}, "filed_at": {"type": "string", "format": "date-time", "example": "2026-07-11T21:03:00-04:00"}, "is_10b5_1": {"type": ["boolean", "null"], "description": "Planned 10b5-1 sale where detectable; otherwise `null`."}, "ownership": {"type": "string", "enum": ["direct", "indirect", ""], "description": "Whether the insider holds the shares directly (`direct`) or through a vehicle (`indirect`). Empty when the filing states nothing.", "example": "indirect"}, "ownership_detail": {"type": "string", "description": "The holding vehicle in case of indirect ownership. An insider reports the same trade separately per vehicle; without this field such rows are identical in date, share count and price and look like duplicates.", "example": "By Biglari Reinsurance Ltd."}, "shares_owned_after": {"type": ["number", "null"], "description": "Reported holding after the transaction, relative to the holding vehicle of this row. `null` when the filing does not state it – a holding of `0` after a full sale, by contrast, is a real statement.", "example": 355668}, "filing_id": {"type": "string", "description": "Accession number of the filing. All modules return it without a prefix; `/filings/{id}` additionally accepts the spelling with `fil_`.", "example": "0000320193-26-000073"}, "source_url": {"type": "string", "format": "uri"}}}, "ClusterBuy": {"type": "object", "required": ["ticker", "cik", "insider_count", "window", "roles", "min_insiders", "rule_version", "sec_known_at", "evidence"], "properties": {"ticker": {"type": "string", "example": "XYZ"}, "cik": {"type": "string"}, "insider_count": {"type": "integer", "description": "Number of independent insiders with a buy in the window.", "example": 4}, "total_shares": {"type": "number"}, "total_value": {"$ref": "#/components/schemas/Money"}, "window": {"type": "string", "example": "7d"}, "roles": {"type": "array", "uniqueItems": true, "description": "Effective role filter in alphabetical order; empty means all roles.", "items": {"$ref": "#/components/schemas/InsiderRole"}, "example": ["director", "officer"]}, "first_buy_date": {"type": "string", "format": "date", "example": "2026-07-10"}, "last_buy_date": {"type": "string", "format": "date", "example": "2026-07-14"}, "min_insiders": {"type": "integer", "minimum": 1, "description": "Requested minimum number of distinct insider names.", "example": 3}, "rule_version": {"type": "string", "description": "Version of the name-based, transaction-date aggregation rule.", "enum": ["cluster-buys-v1"]}, "sec_known_at": {"type": ["string", "null"], "format": "date-time", "description": "Earliest stored filing time at which the requested number of distinct buyers was known for the current window's transactions. Null if any contributing filing lacks a usable time. Historical archive times may have only date-level precision. Not a historical API publication time or a reconstructed rolling-window alert.", "example": "2026-07-13T10:00:00-04:00"}, "evidence": {"type": "array", "description": "Contributing filing/buyer pairs without duplicate transaction lines, sorted by filed_at, filing_id and insider_name; missing times last.", "items": {"$ref": "#/components/schemas/ClusterBuyEvidence"}}}}, "ClusterBuyEvidence": {"type": "object", "required": ["filing_id", "insider_name", "role", "reporting_owners", "filed_at", "source_url"], "properties": {"filing_id": {"type": "string", "description": "Accession number of a contributing filing."}, "insider_name": {"type": "string", "description": "First reporting owner's name used by the existing buyer count."}, "role": {"$ref": "#/components/schemas/InsiderRole"}, "role_detail": {"type": "string", "description": "Reported job title or relationship of the counted first owner, when available."}, "reporting_owners": {"type": "array", "description": "Stored reporting owners, including their available CIKs and roles. Additional owners do not increase the buyer count or qualify an excluded first owner. Empty if no owners were stored; no IDs are inferred.", "items": {"$ref": "#/components/schemas/ReportingOwner"}}, "filed_at": {"type": ["string", "null"], "format": "date-time", "description": "Stored SEC filing time in Eastern Time; null if unavailable, possibly date-level for archives."}, "source_url": {"type": "string", "format": "uri", "description": "Link to the source SEC filing."}}}, "Confidence": {"type": "object", "required": ["ticker", "window", "score"], "properties": {"ticker": {"type": "string"}, "window": {"type": "string", "example": "90d"}, "score": {"type": "number", "minimum": -1, "maximum": 1, "description": "-1 (heavy selling) to +1 (heavy buying).", "example": 0.42}, "buys": {"type": "integer"}, "sells": {"type": "integer"}, "net_invested": {"$ref": "#/components/schemas/Money"}}}, "EventType": {"type": "string", "description": "Normalised event type. Every value is derived from a SEC item code and does actually occur in the data.", "enum": ["bankruptcy", "cyber_incident", "leadership_change", "delisting", "earnings_release", "merger_acquisition", "capital_action", "accounting_issue", "auditor_change", "late_filing", "other_material_event"]}, "Event": {"type": "object", "required": ["ticker", "cik", "event_type", "item_code", "title", "event_date", "filed_at", "filing_id", "source_url"], "properties": {"ticker": {"type": "string", "description": "Trading symbol of the common stock at the time of the filing, taken from the cover page of the 8-K. If the cover page does not tag one, the current symbol of the company is used. Empty if neither is known, e.g. for companies without listed stock or delisted since.", "example": "XYZ"}, "cik": {"type": "string", "example": "0001234567"}, "event_type": {"$ref": "#/components/schemas/EventType"}, "item_code": {"type": "string", "example": "1.03"}, "title": {"type": "string", "example": "Chapter 11 Bankruptcy Filing"}, "event_date": {"type": "string", "format": "date", "example": "2026-07-15"}, "filed_at": {"type": "string", "format": "date-time", "example": "2026-07-15T13:42:00-04:00"}, "filing_id": {"type": "string", "example": "fil_0001234567-26-000045"}, "source_url": {"type": "string", "format": "uri"}}}, "Fund": {"type": "object", "required": ["cik", "name"], "properties": {"cik": {"type": "string", "description": "Central Index Key of the fund, always ten digits.", "example": "0001067983"}, "name": {"type": "string", "example": "Berkshire Hathaway Inc"}, "latest_quarter": {"type": "string", "description": "Most recent reporting quarter of the fund.", "example": "2026-Q1"}}}, "Holding": {"type": "object", "required": ["fund_name", "fund_cik", "ticker", "cusip", "shares", "value", "quarter", "filed_at", "filing_id"], "properties": {"fund_name": {"type": "string", "example": "Berkshire Hathaway Inc"}, "fund_cik": {"type": "string", "description": "Central Index Key of the reporting fund, always ten digits.", "example": "0001067983"}, "ticker": {"type": "string", "example": "AAPL"}, "cusip": {"type": "string", "example": "037833100"}, "issuer_name": {"type": "string", "description": "Issuer name from the filing (nameOfIssuer).", "example": "APPLE INC"}, "shares": {"type": "number", "example": 300000000}, "value": {"$ref": "#/components/schemas/Money"}, "put_call": {"type": ["string", "null"], "enum": ["put", "call", null], "description": "Option type; `null` for a stock position."}, "quarter": {"type": "string", "example": "2026-Q1"}, "filed_at": {"type": "string", "format": "date-time", "example": "2026-05-15T20:10:00-04:00"}, "filing_id": {"type": "string", "example": "fil_0001067983-26-000012"}}}, "InstitutionalSentiment": {"type": "object", "required": ["ticker", "quarter", "funds_holding", "funds_increased", "funds_decreased"], "properties": {"ticker": {"type": "string", "example": "NVDA"}, "quarter": {"type": "string", "example": "2026-Q1"}, "funds_holding": {"type": "integer", "description": "Number of funds with a position in the reporting quarter.", "example": 570}, "funds_increased": {"type": "integer", "description": "Funds that increased the position versus the previous quarter.", "example": 450}, "funds_decreased": {"type": "integer", "description": "Funds that reduced the position versus the previous quarter.", "example": 120}, "funds_new": {"type": "integer", "description": "Funds that newly opened the position."}, "funds_exited": {"type": "integer", "description": "Funds that closed the position. As long as quarter_complete is false, the value also contains funds that have simply not reported yet, and is inflated as a result."}, "total_shares": {"type": "number", "description": "Sum of the reported share holdings (not a cash flow)."}, "total_value": {"$ref": "#/components/schemas/Money"}, "quarter_complete": {"type": "boolean", "description": "Whether the 13F filing deadline of the quarter has passed (quarter end plus 45 days). If false, the quarter is still incomplete; meta.warnings then contains a note."}, "filing_deadline": {"type": "string", "format": "date", "description": "Last filing day for this quarter.", "example": "2026-08-14"}}}, "Disclosure": {"type": "object", "required": ["fund_name", "fund_cik", "quarter", "filed_at", "holdings_count", "total_value", "filing_id"], "properties": {"fund_name": {"type": "string", "example": "Berkshire Hathaway Inc"}, "fund_cik": {"type": "string", "description": "Central Index Key of the reporting fund, always ten digits.", "example": "0001067983"}, "quarter": {"type": "string", "example": "2026-Q1"}, "filed_at": {"type": "string", "format": "date-time", "example": "2026-05-15T20:10:00-04:00"}, "holdings_count": {"type": "integer", "description": "Number of positions in the disclosure.", "example": 42}, "total_value": {"$ref": "#/components/schemas/Money"}, "filing_id": {"type": "string", "example": "fil_0001067983-26-000012"}}}, "TickerEntry": {"type": "object", "required": ["ticker", "cik", "name"], "properties": {"ticker": {"type": "string", "example": "AAPL"}, "cik": {"type": "string", "example": "0000320193"}, "name": {"type": "string", "example": "Apple Inc."}}}, "Filing": {"type": "object", "required": ["filing_id", "form_type", "cik", "filed_at", "source_url"], "properties": {"filing_id": {"type": "string", "description": "Accession number of the filing. All modules return it without a prefix; `/filings/{id}` additionally accepts the spelling with `fil_`.", "example": "0000320193-26-000073"}, "accession_number": {"type": "string", "example": "0000320193-26-000073"}, "form_type": {"type": "string", "example": "4"}, "cik": {"type": "string", "example": "0000320193"}, "filed_at": {"type": "string", "format": "date-time"}, "source_url": {"type": "string", "format": "uri"}}}, "SourceStatus": {"type": "object", "required": ["source", "last_import_at"], "properties": {"source": {"type": "string", "example": "sec_edgar"}, "form_type": {"type": "string", "example": "4"}, "last_import_at": {"type": "string", "format": "date-time"}, "filings": {"type": "integer", "description": "Number of stored filings of this form type."}, "healthy": {"type": "boolean", "description": "Freshness measured against the filing rhythm: Form 4/5 and 8-K appear daily (threshold 7 days), 13F only quarterly with a deadline of up to 45 days (threshold 120 days)."}}}}}}