공시 API 레퍼런스

REST와 MCP를 통해 공식 공시 기관의 기업 재무 정보, 공시, 5% 이상 보유자를 조회합니다.

8개 작업으로 기업 검색과 기본 정보, 재무제표, 기업별 공시 목록, 개별 공시, 최신 공시, 5% 이상 보유자, 공시 원문 기준 재무 데이터를 조회합니다. 보고서는 SEC EDGAR, EDINET, DART, EU/EEA 연차보고서 등록 시스템 및 대만에서 제공됩니다.

REST와 MCP는 Bearer 키, 스키마, 할당량을 공유하며, 각 요청은 호출 1회로 계산됩니다. 검색으로 기업을 찾은 다음, 반환된 id를 기업 관련 요청에 사용합니다.

작업

작업	REST 경로	MCP 도구	반환 내용
기업 검색	`GET /v1/companies`	`filings_search_companies`	검색 조건에 맞는 기업
기업 조회	`GET /v1/companies/{company_id}`	`filings_get_company`	기업 기본 정보 및 증권
재무 정보 조회	`GET /v1/companies/{company_id}/financials`	`filings_get_financials`	기간별 표준 재무 항목
기업 공시 목록 조회	`GET /v1/companies/{company_id}/filings`	`filings_list_company_filings`	기업 공시, 최신순
공시 조회	`GET /v1/filings/{filing_id}`	`filings_get_filing`	공시 상세 정보 및 공식 링크
최신 공시	`GET /v1/filings/latest`	`filings_list_latest_filings`	전체 기업의 최신 공시
보유자	`GET /v1/companies/{company_id}/holders`	`filings_list_holders`	공시된 5% 이상 보유자
공시 원문 기준	`GET /v1/filings/{filing_id}/financials/as-reported`	`filings_get_as_reported`	원문 태그 그대로의 재무 데이터

모든 요청에는 Bearer 키가 필요합니다. REST 요청에는 Authorization: Bearer $NARWHAL_API_KEY를 사용합니다. 인증

기업 및 공시 ID

검색에서 반환된 기업 id를 사용합니다. 대만 ID는 접두사 twn: 뒤에 검색에서 반환된 코드가 붙습니다.

공시 시스템	기업 ID	예시
SEC EDGAR, 미국	`usa:<CIK>`	`usa:0000320193`
EDINET, 일본	`jpn:<EDINET code>`	`jpn:E02144`
DART, 대한민국	`kor:<corp code>`	`kor:00126380`
EU 및 EEA 연차보고서	`<iso3>:<LEI>`	`prt:213800NI6JNPX5F44U15`

공시 ID는 기업 ID와 공시 시스템의 접수번호를 콜론으로 구분해 결합한 값입니다. 예: usa:0000320193:0000320193-25-000079.

기업 경로에는 usa:AAPL과 같은 티커 별칭도 사용할 수 있으며, 해당 기업 ID로 해석됩니다.

기업 검색

기업명, 티커 또는 코드로 기업을 검색하며, 국가 및 공시 시스템 필터를 선택적으로 적용할 수 있습니다. 특정 날짜에 유효했던 티커를 선택하려면 as_of를 사용합니다.

q: 기업명, 티커 또는 코드입니다. 최대 200자입니다.
country: 대문자 alpha-3 국가 코드입니다.
registry: usa, jpn, kor 등의 소문자 공시 시스템 코드입니다.
as_of: 해당 시점에 유효했던 티커를 선택하는 기준 날짜입니다.
lang: 기본값은 en이며, original도 사용할 수 있습니다.
limit: 결과 수는 1~100개이며, 기본값은 20입니다.

companies 목록에는 기업 기본 정보와 상장 상세 정보가 포함됩니다. matched는 id, code, name, former_code 또는 former_name으로 검색 일치 근거를 나타냅니다. 해당하는 경우 이전 기업명과 값이 true인 delisted 플래그가 표시됩니다. q가 없으면 응답에 공시 시스템별로 적재된 기업 수인 coverage도 포함됩니다.

curl --request GET \
  --url "https://api.narwhalapi.com/v1/companies?q=AAPL&limit=2" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "companies": [
    {
      "id": "usa:0000320193",
      "name": "Apple Inc.",
      "country": "USA",
      "mic": "XNAS",
      "code": "AAPL",
      "matched": "code"
    }
  ]
}

기업 조회

기업의 기본 정보, 회계기준, 기업명 이력, 증권 및 관련 기업을 조회합니다.

as_of: 해당 시점에 유효했던 티커를 선택하는 기준 날짜입니다.
lang: 기본값은 en이며, original도 사용할 수 있습니다.

기본 정보에는 제공 가능한 법적 식별자, 산업 분류 및 상태 상세 정보가 포함됩니다. fiscal_year_end는 MMDD 형식을 사용하며, 9월 26일은 0926으로 표시합니다. standard는 us_gaap, ifrs, j_gaap, jmis 또는 k_gaap을 나타냅니다. names에는 이전 기업명과 날짜가 기록됩니다. securities에는 주식 종류, 증권 유형, 식별자 및 날짜가 포함된 상장 정보가 담깁니다. related는 교차 상장 기업, 승계 기업 또는 전신 기업을 나타냅니다. 이 세 필드는 항상 목록입니다.

curl --request GET \
  --url "https://api.narwhalapi.com/v1/companies/usa:0000320193" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "id": "usa:0000320193",
  "name": "Apple Inc.",
  "country": "USA",
  "fiscal_year_end": "0926",
  "standard": "us_gaap",
  "industry": {
    "isic": "2620",
    "sector": "Manufacturing",
    "industry": "Manufacture of computer, electronic and optical products",
    "source_scheme": "us_sic",
    "source_code": "3571"
  },
  "names": [
    {
      "name": "APPLE INC",
      "from": "2007-01-10",
      "to": "2019-08-05"
    },
    {
      "name": "APPLE COMPUTER INC",
      "from": "1994-01-26",
      "to": "2007-01-04"
    },
    {
      "name": "APPLE COMPUTER INC/ FA",
      "from": "1997-07-28",
      "to": "1997-07-28"
    }
  ],
  "securities": [
    {
      "class": "common",
      "type": "common",
      "primary": true,
      "listings": [
        {
          "mic": "XNAS",
          "code": "AAPL",
          "from": "2026-10-20"
        }
      ]
    }
  ],
  "related": []
}

재무 정보 조회

기업의 회계기간별 표준 재무 항목을 최신순으로 조회합니다. 응답은 period에 따라 annual, semiannual 또는 quarterly를 행 키로 사용합니다.

fields: 쉼표로 구분한 표준 항목명 또는 all입니다. 기본값은 자주 사용하는 15개 항목입니다.
statement: income, balance, cash_flow, per_share, shares 또는 other에 속한 모든 항목입니다.
period: 기본값은 annual이며, semiannual 또는 quarterly도 사용할 수 있습니다. 공시 시스템 및 요금제의 제한이 적용됩니다.
fiscal_year: 요금제에서 제공하는 과거 조회 범위 내의 단일 회계연도입니다.
basis: consolidated 또는 standalone입니다.
version: 기본값은 latest입니다. first_reported를 사용하려면 Pro가 필요합니다.
as_of: 지정한 날짜 당시 알려진 수치입니다. Pro가 필요합니다.

표준 항목은 총 77개로, 손익계산서 29개, 재무상태표 28개, 현금흐름 14개, 주당 지표 3개, 주식 수 3개입니다. fields로 항목명을 선택하거나, fields=all로 모든 항목을 조회하거나, statement로 재무제표를 선택합니다. 기본 15개 항목은 revenue, gross_profit, operating_income, net_income, cash, total_assets, total_debt, total_liabilities, total_equity, operating_cash_flow, capex, free_cash_flow, eps_diluted, dividend_per_share, shares_outstanding입니다. 알 수 없는 필드명을 지정하면 400 unknown_field를 반환합니다.

curl --request GET \
  --url "https://api.narwhalapi.com/v1/companies/usa:0000320193/financials?fields=revenue,net_income,total_assets,eps_diluted" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "id": "usa:0000320193",
  "currency": "USD",
  "from_fy": 2023,
  "annual": [
    {
      "fy": 2025,
      "end": "2025-09-27",
      "derived": [],
      "revenue": "416161000000",
      "net_income": "112010000000",
      "total_assets": "359241000000",
      "eps_diluted": "7.46"
    },
    {
      "fy": 2024,
      "end": "2024-09-28",
      "derived": [],
      "revenue": "391035000000",
      "net_income": "93736000000",
      "total_assets": "364980000000",
      "eps_diluted": "6.08"
    },
    {
      "fy": 2023,
      "end": "2023-09-30",
      "derived": [],
      "revenue": "383285000000",
      "net_income": "96995000000",
      "total_assets": "352583000000",
      "eps_diluted": "6.13"
    }
  ]
}

금액은 공시에 사용된 통화의 십진수 문자열로 제공되며, 환산하거나 단위를 조정하지 않습니다. 누락된 항목은 생략하며, 공시된 0은 "0"으로 유지합니다. 각 행에는 회계연도와 기간 종료일이 표시되며, 해당하는 경우 회계 분기 또는 반기도 표시됩니다. derived에는 free_cash_flow처럼 Narwhal이 계산한 항목이 나열됩니다. 최종 기준은 항상 공식 공시입니다.

curl --request GET \
  --url "https://api.narwhalapi.com/v1/companies/usa:0000320193/financials?statement=per_share" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "id": "usa:0000320193",
  "from_fy": 2023,
  "annual": [
    {
      "fy": 2025,
      "end": "2025-09-27",
      "currency": "USD",
      "derived": [],
      "eps_diluted": "7.46",
      "dividend_per_share": "1.02"
    },
    {
      "fy": 2024,
      "end": "2024-09-28",
      "currency": "USD",
      "derived": [],
      "eps_diluted": "6.08",
      "dividend_per_share": "0.98"
    },
    {
      "fy": 2023,
      "end": "2023-09-30",
      "currency": "USD",
      "derived": [],
      "eps_diluted": "6.13",
      "dividend_per_share": "0.94"
    }
  ]
}

일본은 연간 및 반기 보고서를 공표하며, 분기 보고서는 공표하지 않습니다. 미국 기업은 연간 및 분기 보고서를 공표하며, 반기 보고서는 공표하지 않습니다. 대만도 반기 보고서가 없습니다. EU/EEA 보고서는 연간 보고서입니다. 공시 시스템에서 공표하지 않는 기간을 요청하면 404 period_not_published와 함께 사용할 기간을 명시한 상세 정보를 반환합니다.

기업 공시 목록 조회

유형, 서식 및 제출일 필터를 적용해 기업의 공시를 조회합니다.

type: annual, semiannual, quarterly, event, ownership, insider 또는 other입니다.
form: 10-K와 같은 정확한 서식명입니다. 최대 20자입니다.
filed_from: 제출일 조회 범위의 시작일입니다.
filed_to: 제출일 조회 범위의 종료일입니다.
include_amendments: 정정 공시 포함 여부입니다. 기본값은 false입니다.
cursor: 동일한 필터로 다음 페이지를 조회할 때 사용하는 커서입니다.
limit: 결과 수는 1~200개이며, 기본값은 50입니다.
lang: 기본값은 en이며, original도 사용할 수 있습니다.

각 행에는 공시, 제출일, 서식, 유형 및 기간 종료일이 표시되며, 공시 시스템에서 제목을 제공하는 경우 제목도 포함됩니다. 결과는 최신순이며, 다음 페이지를 조회하려면 next_cursor를 사용합니다. 마지막 페이지에서는 값이 null입니다. 요금제에 따라 시작일이 더 늦은 날짜로 조정되면 응답에 filed_from이 다시 포함됩니다.

curl --request GET \
  --url "https://api.narwhalapi.com/v1/companies/usa:0000320193/filings?type=annual&limit=2" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "id": "usa:0000320193",
  "filed_from": "2023-10-27",
  "filings": [
    {
      "id": "usa:0000320193:0000320193-25-000079",
      "filed": "2025-10-31",
      "form": "10-K",
      "type": "annual",
      "period_end": "2025-09-27"
    },
    {
      "id": "usa:0000320193:0000320193-24-000123",
      "filed": "2024-11-01",
      "form": "10-K",
      "type": "annual",
      "period_end": "2024-09-28"
    }
  ],
  "next_cursor": "eyJpIjo0MTUwNjcsImtpbmQiOiJmaWxpbmdzIiwicSI6IjExYzkyYjY4YWJjZTMyM2YiLCJ0IjoiMjAyNC0xMS0wMVQxMDowMTozNiswMDowMCIsInYiOjF9.j2L56WYc-pkZ4UoI0z1vAN4htuG4nzEDOJUTtT_CZOY"
}

공시 조회

개별 공시의 메타데이터와 공식 공시 시스템 링크를 조회합니다. lang의 기본값은 en이며, original도 사용할 수 있습니다.

응답은 공시와 기업을 식별하며, 제출 주체가 다른 경우 filer_id를 포함합니다. 제공 가능한 경우 서식, 유형, 제목, 회계연도, 기간 종료일 및 UTC 기준 filed_at 타임스탬프를 포함합니다. fp는 FY, H1, H2 또는 Q1부터 Q4까지의 값을 나타내며, url은 공시 시스템의 공식 공시 페이지로 연결됩니다. amends는 정정 대상 공시를 식별하며, withdrawn은 값이 true인 경우에만 표시됩니다.

curl --request GET \
  --url "https://api.narwhalapi.com/v1/filings/usa:0000320193:0000320193-25-000079" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "id": "usa:0000320193:0000320193-25-000079",
  "company_id": "usa:0000320193",
  "form": "10-K",
  "type": "annual",
  "fy": 2025,
  "fp": "FY",
  "period_end": "2025-09-27",
  "filed_at": "2025-10-31T10:01:26Z",
  "url": "https://www.sec.gov/Archives/edgar/data/320193/000032019325000079/0000320193-25-000079-index.htm"
}

5% 이상 보유자

미국, 일본, 한국의 지분 공시에 보고된 보유자를 조회합니다. 목록은 각 보유자의 최신 보고서를 기준으로 하며, 지분을 전량 처분한 보유자는 제외합니다.

security: 주식 종류입니다. 최대 40자입니다.
lang: 기본값은 en이며, original도 사용할 수 있습니다.
limit: 결과 수는 1부터 500까지이며, 기본값은 100입니다.

각 행에는 확인 가능한 경우 보유자, 지분율, 주식 수, 사유 발생일, 공시일, 공시 ID, 주식 종류가 포함됩니다. 목록은 페이지로 나누지 않습니다. 플랜에 따라 시작일이 조정되면 조정된 filed_from이 응답에 포함됩니다.

curl --request GET \
  --url "https://api.narwhalapi.com/v1/companies/usa:0000320193/holders?limit=2" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "id": "usa:0000320193",
  "filed_from": "2023-10-27",
  "holders": [
    {
      "holder": "Vanguard Capital Management",
      "percent": "7.48",
      "shares": "1099168953",
      "event_date": "2026-03-31",
      "filed": "2026-04-30",
      "filing_id": "usa:0000320193:0002100119-26-000139",
      "security": {
        "class": "common"
      }
    }
  ]
}

공시 원문 기준 재무 정보

개별 공시의 재무 데이터를 태그된 그대로 개념별로 묶어 조회합니다. 이 작업은 공시 조회 내에서 모든 플랜에 제공됩니다.

concepts의 각 항목에는 taxonomy, concept, label, unit과 values 목록이 포함됩니다. 각 값에는 해당 정보가 있는 경우 start, end, value가 포함됩니다.

curl --request GET \
  --url "https://api.narwhalapi.com/v1/filings/usa:0000320193:0000320193-25-000079/financials/as-reported" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "concepts": [
    {
      "taxonomy": "us-gaap",
      "concept": "Revenues",
      "label": "Revenues",
      "unit": "USD",
      "values": [
        {
          "start": "2023-10-01",
          "end": "2024-09-28",
          "value": "391035000000"
        },
        {
          "start": "2022-09-25",
          "end": "2023-09-30",
          "value": "383285000000"
        }
      ]
    }
  ]
}

미국 공시만 지원하며, 일본과 한국 공시는 404 as_reported_unavailable을 반환합니다. 하나의 공시에 수천 개의 데이터 항목이 포함될 수 있으므로 응답 크기가 수백 킬로바이트에 이를 수 있습니다. 결과는 페이지로 나누지 않습니다.

요금제별 제한

모든 작업과 표준 항목은 모든 플랜에서 이용할 수 있으며, 과거 데이터 조회 범위와 제공 시점은 플랜에 따라 달라집니다.

	무료	Basic	Pro
재무 정보 조회 범위	최근 3개 회계연도	최근 10개 회계연도	전체 이력
보고 주기	연간	연간, 반기, 분기	연간, 반기, 분기
공시 목록 및 보유자	최근 3년	최근 10년	전체 이력
전달	다음 날	라이브	라이브
최초 보고 수치 및 특정 시점 기준 수치	아니요	아니요	예

시작 시점만 플랜의 조회 범위보다 이른 요청은 해당 범위에 맞게 조정되며, 재무 정보에는 from_fy, 공시와 보유자에는 filed_from이 사용됩니다. 공시와 보유자의 조회 범위는 역년을 기준으로 합니다. Free에서는 오늘 00:00 UTC 이전에 제출된 공시만 제공됩니다.

Free에서 분기 또는 반기 재무 정보를 요청하거나, 과거 데이터 조회 범위보다 이른 fiscal_year 또는 filed_to를 지정하거나, Pro 미만 플랜에서 version=first_reported 또는 as_of를 사용해 재무 정보를 요청하면 쿼터를 차감하기 전에 403 plan_upgrade_required를 반환합니다.

응답 규칙

숫자는 십진수 문자열로 반환됩니다.
값이 없는 스칼라 필드는 생략되며, null로 반환되지 않습니다.
목록은 항상 포함되며, 비어 있으면 []로 반환됩니다.
delisted, withdrawn 등의 플래그는 참일 때만 포함됩니다.
마지막 페이지에서는 next_cursor가 null입니다.
lang=original은 제공 가능한 경우 이름과 제목을 공시 기관의 원어로 반환합니다. 기본값은 en입니다.

오류

400 invalid_query 쿼리가 유효하지 않습니다.
400 unknown_field fields에 표준 재무 항목이 아닌 이름이 포함되어 있습니다.
400 invalid_cursor 커서 형식이 잘못되었거나 다른 필터에 대해 발급된 커서입니다.
401 invalid_api_key API 키가 유효하지 않습니다.
403 plan_upgrade_required 요청한 과거 데이터 범위, 보고 주기 또는 재무 정보 버전이 플랜의 제공 범위를 벗어납니다.
404 company_not_found 기업을 찾을 수 없습니다.
404 filing_not_found 공시를 찾을 수 없습니다.
404 period_not_published 공시 기관에서 요청한 보고 주기의 자료를 제공하지 않습니다. 상세 설명에 사용할 보고 주기가 명시됩니다.
404 as_reported_unavailable 해당 공시의 원문 기준 재무 데이터를 이용할 수 없습니다.
429 rate_limit_exceeded 요청 빈도 제한을 초과했습니다.
429 quota_exhausted 요청 쿼터를 모두 사용했습니다.
503 database_unavailable 데이터 저장소를 이용할 수 없습니다. 요청을 다시 시도하세요.

오류는 표준 문제 응답 형식을 사용합니다. 오류 및 할당량

인증 문서에서는 Bearer 키를, 오류 문서에서는 표준 문제 응답 형식을, MCP 문서에서는 도구 접근 방법을 설명합니다. 인증 · 오류 및 할당량 · MCP