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 时间和覆盖范围页面，以了解可用快照。