SEC 申報文件 API

按公司列出 SEC 備案元數據，包括 10-K、10-Q、8-K、Form 4 和 13F-HR。

端点與請求

使用 Narwhal API 密鑰即可獲得。

REST 端點

GET /v1/companies/{company_id}/filings

請求

curl --request GET \
  --url "https://api.narwhalapi.com/v1/companies/cmp_a1b2c3d4e5f678901234567890abcdef/filings?forms=10-K,10-Q&filed_from=2020-01-01&filed_to=2027-01-01&limit=50" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

MCP 使用 companies_list_filings 使用下面對應的參數。REST 和 MCP 返回相同的回應架構，並共享額度計數。

參數

名稱	必填	類型	含義
`company_id`	是	路徑·Narwhal 不透明 ID	公司搜尋返回的穩定公司身份。股票代碼和 CIK 仍是別名，不是永久路由身份。
`forms`	否	查詢·以逗號分隔的 SEC 表格	表格標記區分大小寫。基礎表格也會匹配其 /A 修訂版本，除非排除了修訂文件。
`filed_from`	否	查詢·YYYY-MM-DD	包含的提交日期下限。
`filed_to`	否	查詢·YYYY-MM-DD	不包含的提交日期上限，必須晚於 filed_from。
`include_amendments`	否	查詢·布爾值	請求基礎表格時包含修訂件。預設為 true。
`limit`	否	查詢·整數，1–100	返回申報文件的最大數量。預設為 50。
`cursor`	否	查詢·不透明字串	來自上一頁的續接令牌。它綁定到原始查詢和篩選條件。

SEC 表格篩選條件

使用確切的 SEC 表格標記。基礎表格可以包含其 /A 修訂文件，例如 10-K/A 或 4/A，除非明確排除修訂文件。

表格	含義
`10-K`	年度公司報告
`10-Q`	季度公司報告
`8-K`	公司重大事件
`20-F / 6-K`	外國私人發行人報告
`DEF 14A`	代理投票、董事會和高管薪酬
`Forms 3 / 4 / 5`	內部人士受益所有權及其變更
`Schedule 13D / 13G`	大額受益所有人
`13F-HR`	機構管理人持倉
`S-1 / S-3 / 424B`	註冊、發行和招股說明書

此列表解釋常見表格。它不是固定的白名單。

回應

{
  "company": {
    "id": "cmp_a1b2c3d4e5f678901234567890abcdef",
    "name": "Apple Inc.",
    "cik": "0000320193"
  },
  "filings": [
    {
      "accession_number": "0000320193-24-000123",
      "form": "10-K",
      "filed_on": "2024-11-01",
      "accepted_at": "2024-11-01T10:01:36Z",
      "report_period": "2024-09-28",
      "is_amendment": false,
      "items": [],
      "filing_index_url": "https://www.sec.gov/Archives/edgar/data/320193/000032019324000123/0000320193-24-000123-index.html",
      "primary_document_url": "https://www.sec.gov/Archives/edgar/data/320193/000032019324000123/aapl-20240928.htm"
    }
  ],
  "next_cursor": null,
  "as_of": "2026-08-29T12:00:00Z"
}

欄位	類型	必填	含義
`company`	對象	是	所請求發行人的穩定公司 ID、名稱和 CIK。
`filings`	陣列	是	申報文件元數據按接收時間和申報編號排序，最新的在前。
`next_cursor`	字串或 null	是	與篩選條件綁定的不透明續頁令牌；完成時為 null。
`as_of`	UTC時間戳記	是	頁面中每份申報共享的快照時間。

錯誤與配額

400 invalid_query — 查詢、日期、表格、限制或游標無效。
401 invalid_api_key — Bearer 密鑰缺失或被拒絕。
404 company_not_found — 已接受發布版本中不存在該公司 ID。
429 rate_limit_exceeded 或 quota_exhausted — 共享短窗口或月度額度已耗盡。
503 companies_unavailable — Companies 已禁用、權限未啓用，或無法提供完整的已接受發布版本。

認證失敗和被拒絕的限流請求不會消耗月度額度。成功的 REST 和 MCP 呼叫使用同一帳戶限額。

首版發布範圍

第一個版本僅返回元數據和規範 SEC 文件連結。不包含申報正文、附件、XBRL 事實、內部交易、財務報表或 13F 持倉。

覆蓋範圍僅限於已接受的發行方群體。請讀取回應中的 as_of 時間和覆蓋範圍頁面，以瞭解可用快照。