{ "openapi": "3.1.0", "info": { "title": "Korean Tickers Standard Fundamentals API", "version": "dart-fundamentals.v0.2", "description": "Source-verified DART reported financial statements with separately identified basic calculated financial indicators. Core 300 plus AI Value Chain; latest eight reporting slots. Authenticated manual pilot; not a quote or forecast feed.", "termsOfService": "https://www.koreantickers.com/terms", "contact": { "name": "Korean Tickers API support", "email": "deepdivekr@gmail.com", "url": "https://www.koreantickers.com/api-docs" }, "license": { "name": "Korean Tickers Standard API pilot terms", "url": "https://www.koreantickers.com/terms" } }, "servers": [ { "url": "https://www.koreantickers.com" } ], "x-koreantickers": { "schemaVersion": "dart-fundamentals.v0.2", "product": "standard_fundamentals", "coverageUniverse": { "id": "core300-ai54-20260904", "policy": "Pinned union of KOSPI top 200, KOSDAQ top 100, and 54 AI value-chain companies; duplicates count once.", "coreCompanies": 300, "aiValueChainCompanies": 54, "aiAdditionalCompanies": 13, "totalCompanies": 313, "discoveryPath": "/v1/companies", "outsideCoverageStatus": 404, "outsideCoverageCode": "ticker_outside_coverage" }, "endpointStatus": "manual_pilot", "audience": [ "app developers", "research dashboards", "internal data tools", "approved B2B pilots" ], "authentication": [ "Authorization: Bearer", "x-api-key" ], "defaultRateLimits": { "requestsPerMinuteWindow": 120, "requestsPerKstDay": 3000, "authoritativeSource": "response_headers", "pilotEnforcement": "grant_global_fail_closed_env_keys_process_fallback_only", "slaMeter": false }, "quotaAccounting": "reserve_after_auth_before_validation_and_data_work; pre_reservation_401_403_429_503_do_not_consume", "cachePolicy": "private_no_store", "freshness": "filing_backed_no_publication_latency_sla", "financialHistoryRetention": { "mode": "rolling_logical_reporting_periods", "productionPolicy": "fixed_8", "defaultLogicalPeriods": 8, "minimumLogicalPeriods": 8, "maximumLogicalPeriods": 8, "logicalPeriodKey": "fiscalYear + reportCode fiscal reporting quarter slot; 11013=Q1, 11012=Q2/H1, 11014=Q3/9M, 11011=Q4/annual; CFS and OFS share one slot", "evictionRule": "After a new complete fiscal reporting quarter slot is published and validated, normalized Standard rows older than the newest 8 slots are removed.", "archiveIncluded": false }, "numericTimestampUnit": "unix_milliseconds", "valueContract": { "currency": "Uppercase source ISO currency for monetary facts only; no conversion is implied.", "unit": [ "currency", "pct", "ratio" ], "nonMonetaryCurrency": null }, "source": "DART Open API", "metricCatalogUrl": "https://www.koreantickers.com/schemas/dart-standard-metric-catalog.v0.2.json", "officialSourceDocumentation": [ "https://opendart.fss.or.kr/intro/terms.do", "https://engopendart.fss.or.kr/guide/detail.do?apiGrpCd=DE003&apiId=AE00036", "https://engopendart.fss.or.kr/guide/detail.do?apiGrpCd=DE003&apiId=AE00037" ], "fundamentalsMetrics": [ "revenue", "operating_income", "pretax_income", "net_income", "total_assets", "total_liabilities", "total_equity", "cash_and_equivalents", "operating_cash_flow", "investing_cash_flow", "financing_cash_flow" ], "excluded": [ "market-data feed", "broker research", "news bodies", "filing context paragraphs or raw filing bodies", "raw XBRL note fact inventories", "investment advice" ], "reportedDataContract": "dart-reported-financials.v1", "calculatedIndicatorDefinitions": { "operating_margin_pct": { "label": "Operating margin", "formula": "operating_income / revenue * 100", "basis": "reported_income_duration" }, "net_margin_pct": { "label": "Net margin", "formula": "net_income / revenue * 100", "basis": "reported_income_duration" }, "liabilities_to_equity_pct": { "label": "Liabilities to equity", "formula": "total_liabilities / total_equity * 100", "basis": "period_end" }, "quick_ratio_pct": { "label": "Quick ratio (current assets less inventory)", "formula": "(current_assets - inventory) / current_liabilities * 100", "basis": "period_end" }, "roe_total_equity_annual_pct": { "label": "ROE (annual, total equity)", "formula": "annual_net_income / ((prior_year_end_total_equity + current_year_end_total_equity) / 2) * 100", "basis": "annual_not_ttm_not_annualized_quarter" } } }, "externalDocs": { "description": "Korean Tickers data sources and DART normalization methodology", "url": "https://www.koreantickers.com/sources" }, "tags": [ { "name": "Standard fundamentals", "description": "Authenticated, filing-backed Standard API pilot. This is not a quote feed or investment-advice product." } ], "paths": { "/v1/companies": { "get": { "operationId": "listStandardCompanies", "summary": "List the pinned Core 300 plus AI value-chain API coverage.", "description": "Authenticated full membership snapshot, not a live market-cap ranking. Duplicate membership counts once. Membership changes require a new universe version. The website may cover additional companies that are outside this API product.", "tags": [ "Standard fundamentals" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Complete pinned company list and eight-report-slot policy.", "headers": { "cache-control": { "$ref": "#/components/headers/CacheControl" }, "x-ratelimit-scope": { "$ref": "#/components/headers/RateLimitScope" }, "x-ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "x-ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "x-ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" }, "x-ratelimit-daily-limit": { "$ref": "#/components/headers/RateLimitDailyLimit" }, "x-ratelimit-daily-remaining": { "$ref": "#/components/headers/RateLimitDailyRemaining" }, "x-ratelimit-daily-reset": { "$ref": "#/components/headers/RateLimitDailyReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardCompaniesResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/EntitlementRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ApiKeyNotConfigured" } } } }, "/v1/companies/{ticker}/fundamentals": { "get": { "operationId": "getCompanyFundamentals", "summary": "Get DART-derived fundamentals for one Korean listed company.", "description": "Returns company identity, latest DART financial period, readiness checks, completeness, recent period coverage, and a stable map of Standard fundamentals metrics.", "tags": [ "Standard fundamentals" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Ticker" } ], "responses": { "200": { "description": "Successful fundamentals response.", "headers": { "cache-control": { "$ref": "#/components/headers/CacheControl" }, "x-koreantickers-data-freshness": { "$ref": "#/components/headers/DataFreshness" }, "x-ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "x-ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "x-ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" }, "x-ratelimit-daily-limit": { "$ref": "#/components/headers/RateLimitDailyLimit" }, "x-ratelimit-daily-remaining": { "$ref": "#/components/headers/RateLimitDailyRemaining" }, "x-ratelimit-daily-reset": { "$ref": "#/components/headers/RateLimitDailyReset" }, "x-ratelimit-scope": { "$ref": "#/components/headers/RateLimitScope" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Phase1FundamentalsResponse" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/EntitlementRequired" }, "404": { "$ref": "#/components/responses/TickerNotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ApiKeyNotConfigured" } } } }, "/v1/companies/{ticker}/financial-facts": { "get": { "operationId": "getCompanyFinancialFacts", "summary": "Get normalized financial fact history for one Korean listed company.", "tags": [ "Standard fundamentals" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Ticker" }, { "$ref": "#/components/parameters/StandardPageLimit" }, { "$ref": "#/components/parameters/Offset" } ], "responses": { "200": { "$ref": "#/components/responses/FinancialFactsResponse" }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/EntitlementRequired" }, "404": { "$ref": "#/components/responses/TickerNotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ApiKeyNotConfigured" } } } }, "/v1/companies/{ticker}/periods": { "get": { "operationId": "getCompanyReportingPeriods", "summary": "Get source-linked reporting-period coverage for one Korean listed company.", "description": "Returns the retained DART reporting periods, statement scope, receipt identifiers, source URLs, collection timestamps, and the current per-ticker history window. Production Standard keeps the latest 8 fiscal reporting quarter slots: Q1, Q2/H1, Q3/9M, and Q4/annual; CFS and OFS share one slot. Source statements can be cumulative or annual, so this policy does not claim eight standalone quarterly statements. A release is not sale-eligible unless its configured capacity is exactly 8 and its retained rows stay within that capacity.", "tags": [ "Standard fundamentals" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Ticker" }, { "$ref": "#/components/parameters/PeriodLimit" }, { "$ref": "#/components/parameters/Offset" } ], "responses": { "200": { "$ref": "#/components/responses/PeriodsResponse" }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/EntitlementRequired" }, "404": { "$ref": "#/components/responses/TickerNotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ApiKeyNotConfigured" } } } }, "/v1/companies/{ticker}/coverage": { "get": { "operationId": "getCompanyDataCoverage", "summary": "Get ticker-scoped Standard dataset coverage and source freshness.", "description": "Returns null-safe row counts, source timestamp maxima, and the retained reporting history for each Standard serving dataset. Production Standard uses a fixed 8-fiscal-reporting-quarter-slot window and is not a bulk or long-term archive. Filing metadata and independent raw source evidence are outside this normalized financial-history window. It does not claim whole-release readiness or quote-feed freshness.", "tags": [ "Standard fundamentals" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Ticker" } ], "responses": { "200": { "$ref": "#/components/responses/CoverageResponse" }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/EntitlementRequired" }, "404": { "$ref": "#/components/responses/TickerNotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ApiKeyNotConfigured" } } } }, "/v1/companies/{ticker}/indicators": { "get": { "operationId": "getCompanyIndicators", "summary": "Calculate basic financial indicators from source-verified reported values.", "tags": [ "Standard fundamentals" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Ticker" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "$ref": "#/components/parameters/Offset" } ], "responses": { "200": { "$ref": "#/components/responses/IndicatorsResponse" }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/EntitlementRequired" }, "404": { "$ref": "#/components/responses/TickerNotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ApiKeyNotConfigured" } }, "description": "Returns five explicitly defined metrics for each retained reporting scope/period. Inputs and formulas are included. Unverified inputs produce null. Annual total-equity ROE is not TTM or parent-equity ROE." } }, "/v1/companies/{ticker}/statements": { "get": { "operationId": "getCompanyStatements", "summary": "Get raw DART statement lines for one Korean listed company.", "tags": [ "Standard fundamentals" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Ticker" }, { "$ref": "#/components/parameters/StandardPageLimit" }, { "$ref": "#/components/parameters/Offset" } ], "responses": { "200": { "$ref": "#/components/responses/StatementsResponse" }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/EntitlementRequired" }, "404": { "$ref": "#/components/responses/TickerNotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ApiKeyNotConfigured" } } } }, "/v1/companies/{ticker}/filings": { "get": { "operationId": "getCompanyFilings", "summary": "Get filing chronology and source receipts for one Korean listed company.", "tags": [ "Standard fundamentals" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Ticker" }, { "$ref": "#/components/parameters/FilingLimit" }, { "$ref": "#/components/parameters/Offset" } ], "responses": { "200": { "$ref": "#/components/responses/FilingsResponse" }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/EntitlementRequired" }, "404": { "$ref": "#/components/responses/TickerNotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ApiKeyNotConfigured" } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer" }, "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key" } }, "parameters": { "Ticker": { "name": "ticker", "in": "path", "required": true, "description": "Six-character Korean stock ticker. ASCII letters are normalized to uppercase.", "schema": { "type": "string", "pattern": "^[0-9A-Z]{6}$", "examples": [ "005930", "A12B3C" ] } }, "StandardPageLimit": { "name": "limit", "in": "query", "required": false, "description": "Page size for financial facts, indicators, and statement lines. Invalid or out-of-range values return invalid_parameter.", "schema": { "type": "integer", "minimum": 1, "maximum": 2000, "default": 500 } }, "PeriodLimit": { "name": "limit", "in": "query", "required": false, "description": "Page size for source-linked reporting periods. Invalid or out-of-range values return invalid_parameter.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, "FilingLimit": { "name": "limit", "in": "query", "required": false, "description": "Page size for filing chronology. Invalid or out-of-range values return invalid_parameter.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, "Offset": { "name": "offset", "in": "query", "required": false, "description": "Pagination offset. Invalid or out-of-range values return invalid_parameter.", "schema": { "type": "integer", "minimum": 0, "maximum": 100000, "default": 0 } } }, "headers": { "CacheControl": { "description": "Private response cache policy.", "schema": { "type": "string", "const": "private, no-cache, no-store, max-age=0, must-revalidate" } }, "DataFreshness": { "description": "Freshness classification.", "schema": { "type": "string" } }, "RateLimitLimit": { "description": "Allowed requests in the current minute window.", "schema": { "type": "string" } }, "RateLimitRemaining": { "description": "Remaining requests in the current minute window.", "schema": { "type": "string" } }, "RateLimitReset": { "description": "Unix timestamp when the current rate limit window resets.", "schema": { "type": "string" } }, "RateLimitDailyLimit": { "description": "Allowed requests in the current daily window.", "schema": { "type": "string" } }, "RateLimitDailyRemaining": { "description": "Remaining requests in the current daily window.", "schema": { "type": "string" } }, "RateLimitDailyReset": { "description": "Unix timestamp when the current daily window resets.", "schema": { "type": "string" } }, "RateLimitScope": { "description": "Active counter lane. global uses the atomic access-grant counter; process_fallback is limited to environment/internal keys; unavailable accompanies a fail-closed customer metering error.", "schema": { "type": "string", "enum": [ "global", "process_fallback", "unavailable" ] } }, "RetryAfter": { "description": "Seconds until the request can be retried.", "schema": { "type": "string" } }, "WWWAuthenticate": { "description": "Bearer authentication challenge required on HTTP 401 responses.", "schema": { "type": "string", "const": "Bearer realm=\"Korean Tickers API\"" } } }, "responses": { "FinancialFactsResponse": { "description": "Bounded page of normalized financial facts with row-level DART provenance.", "headers": { "cache-control": { "$ref": "#/components/headers/CacheControl" }, "x-koreantickers-data-freshness": { "$ref": "#/components/headers/DataFreshness" }, "x-ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "x-ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "x-ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" }, "x-ratelimit-daily-limit": { "$ref": "#/components/headers/RateLimitDailyLimit" }, "x-ratelimit-daily-remaining": { "$ref": "#/components/headers/RateLimitDailyRemaining" }, "x-ratelimit-daily-reset": { "$ref": "#/components/headers/RateLimitDailyReset" }, "x-ratelimit-scope": { "$ref": "#/components/headers/RateLimitScope" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinancialFactsResponse" } } } }, "PeriodsResponse": { "description": "Bounded page of retained DART reporting periods with source receipts and row-level provenance.", "headers": { "cache-control": { "$ref": "#/components/headers/CacheControl" }, "x-koreantickers-data-freshness": { "$ref": "#/components/headers/DataFreshness" }, "x-ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "x-ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "x-ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" }, "x-ratelimit-daily-limit": { "$ref": "#/components/headers/RateLimitDailyLimit" }, "x-ratelimit-daily-remaining": { "$ref": "#/components/headers/RateLimitDailyRemaining" }, "x-ratelimit-daily-reset": { "$ref": "#/components/headers/RateLimitDailyReset" }, "x-ratelimit-scope": { "$ref": "#/components/headers/RateLimitScope" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PeriodsResponse" } } } }, "CoverageResponse": { "description": "Ticker-scoped Standard serving coverage with explicit missing states and aggregate provenance.", "headers": { "cache-control": { "$ref": "#/components/headers/CacheControl" }, "x-koreantickers-data-freshness": { "$ref": "#/components/headers/DataFreshness" }, "x-ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "x-ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "x-ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" }, "x-ratelimit-daily-limit": { "$ref": "#/components/headers/RateLimitDailyLimit" }, "x-ratelimit-daily-remaining": { "$ref": "#/components/headers/RateLimitDailyRemaining" }, "x-ratelimit-daily-reset": { "$ref": "#/components/headers/RateLimitDailyReset" }, "x-ratelimit-scope": { "$ref": "#/components/headers/RateLimitScope" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CoverageResponse" } } } }, "IndicatorsResponse": { "description": "Source-verified calculated financial indicators, grouped by retained period and scope.", "headers": { "cache-control": { "$ref": "#/components/headers/CacheControl" }, "x-koreantickers-data-freshness": { "$ref": "#/components/headers/DataFreshness" }, "x-ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "x-ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "x-ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" }, "x-ratelimit-daily-limit": { "$ref": "#/components/headers/RateLimitDailyLimit" }, "x-ratelimit-daily-remaining": { "$ref": "#/components/headers/RateLimitDailyRemaining" }, "x-ratelimit-daily-reset": { "$ref": "#/components/headers/RateLimitDailyReset" }, "x-ratelimit-scope": { "$ref": "#/components/headers/RateLimitScope" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IndicatorsResponse" } } } }, "StatementsResponse": { "description": "Bounded page of DART statement lines with source-backed English labels where available, explicit untranslated states, and row-level filing provenance.", "headers": { "cache-control": { "$ref": "#/components/headers/CacheControl" }, "x-koreantickers-data-freshness": { "$ref": "#/components/headers/DataFreshness" }, "x-ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "x-ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "x-ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" }, "x-ratelimit-daily-limit": { "$ref": "#/components/headers/RateLimitDailyLimit" }, "x-ratelimit-daily-remaining": { "$ref": "#/components/headers/RateLimitDailyRemaining" }, "x-ratelimit-daily-reset": { "$ref": "#/components/headers/RateLimitDailyReset" }, "x-ratelimit-scope": { "$ref": "#/components/headers/RateLimitScope" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatementsResponse" } } } }, "FilingsResponse": { "description": "Paginated DART filing chronology with receipt identifiers and source links.", "headers": { "cache-control": { "$ref": "#/components/headers/CacheControl" }, "x-koreantickers-data-freshness": { "$ref": "#/components/headers/DataFreshness" }, "x-ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "x-ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "x-ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" }, "x-ratelimit-daily-limit": { "$ref": "#/components/headers/RateLimitDailyLimit" }, "x-ratelimit-daily-remaining": { "$ref": "#/components/headers/RateLimitDailyRemaining" }, "x-ratelimit-daily-reset": { "$ref": "#/components/headers/RateLimitDailyReset" }, "x-ratelimit-scope": { "$ref": "#/components/headers/RateLimitScope" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilingsResponse" } } } }, "InvalidRequest": { "description": "Ticker or query parameter validation failed. Inspect error.code for invalid_ticker or invalid_parameter.", "headers": { "cache-control": { "$ref": "#/components/headers/CacheControl" }, "x-koreantickers-data-freshness": { "$ref": "#/components/headers/DataFreshness" }, "x-ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "x-ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "x-ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" }, "x-ratelimit-daily-limit": { "$ref": "#/components/headers/RateLimitDailyLimit" }, "x-ratelimit-daily-remaining": { "$ref": "#/components/headers/RateLimitDailyRemaining" }, "x-ratelimit-daily-reset": { "$ref": "#/components/headers/RateLimitDailyReset" }, "x-ratelimit-scope": { "$ref": "#/components/headers/RateLimitScope" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Unauthorized": { "description": "API key was missing or invalid.", "headers": { "cache-control": { "$ref": "#/components/headers/CacheControl" }, "x-koreantickers-data-freshness": { "$ref": "#/components/headers/DataFreshness" }, "www-authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "EntitlementRequired": { "description": "The key lacks the required product entitlement or its linked access grant is inactive, expired, past due, cancelled, or suspended.", "headers": { "cache-control": { "$ref": "#/components/headers/CacheControl" }, "x-koreantickers-data-freshness": { "$ref": "#/components/headers/DataFreshness" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "TickerNotFound": { "description": "No Standard DART financial data is available for the ticker.", "headers": { "cache-control": { "$ref": "#/components/headers/CacheControl" }, "x-koreantickers-data-freshness": { "$ref": "#/components/headers/DataFreshness" }, "x-ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "x-ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "x-ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" }, "x-ratelimit-daily-limit": { "$ref": "#/components/headers/RateLimitDailyLimit" }, "x-ratelimit-daily-remaining": { "$ref": "#/components/headers/RateLimitDailyRemaining" }, "x-ratelimit-daily-reset": { "$ref": "#/components/headers/RateLimitDailyReset" }, "x-ratelimit-scope": { "$ref": "#/components/headers/RateLimitScope" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "RateLimited": { "description": "Rate limit was exceeded.", "headers": { "retry-after": { "$ref": "#/components/headers/RetryAfter" }, "x-ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "x-ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "x-ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" }, "x-ratelimit-daily-limit": { "$ref": "#/components/headers/RateLimitDailyLimit" }, "x-ratelimit-daily-remaining": { "$ref": "#/components/headers/RateLimitDailyRemaining" }, "x-ratelimit-daily-reset": { "$ref": "#/components/headers/RateLimitDailyReset" }, "x-ratelimit-scope": { "$ref": "#/components/headers/RateLimitScope" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "InternalError": { "description": "The authenticated request could not be completed. The response keeps a requestId for support without exposing internal error details.", "headers": { "cache-control": { "$ref": "#/components/headers/CacheControl" }, "x-koreantickers-data-freshness": { "$ref": "#/components/headers/DataFreshness" }, "x-ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "x-ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "x-ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" }, "x-ratelimit-daily-limit": { "$ref": "#/components/headers/RateLimitDailyLimit" }, "x-ratelimit-daily-remaining": { "$ref": "#/components/headers/RateLimitDailyRemaining" }, "x-ratelimit-daily-reset": { "$ref": "#/components/headers/RateLimitDailyReset" }, "x-ratelimit-scope": { "$ref": "#/components/headers/RateLimitScope" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "ApiKeyNotConfigured": { "description": "API key configuration, key storage, or grant-level paid metering is unavailable.", "headers": { "cache-control": { "$ref": "#/components/headers/CacheControl" }, "x-koreantickers-data-freshness": { "$ref": "#/components/headers/DataFreshness" }, "retry-after": { "$ref": "#/components/headers/RetryAfter" }, "x-ratelimit-scope": { "$ref": "#/components/headers/RateLimitScope" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "schemas": { "StandardCompaniesResponse": { "type": "object", "required": [ "apiVersion", "generatedAt", "universeId", "asOfDate", "collectedAt", "source", "sourceUrl", "historyPeriods", "membershipPolicy", "counts", "companies" ], "properties": { "apiVersion": { "type": "string", "const": "standard-universe.v1" }, "generatedAt": { "type": "string", "format": "date-time" }, "universeId": { "type": "string" }, "asOfDate": { "type": "string", "format": "date" }, "collectedAt": { "type": "string", "format": "date-time" }, "source": { "type": "string" }, "sourceUrl": { "type": "string", "format": "uri" }, "historyPeriods": { "type": "integer", "const": 8 }, "membershipPolicy": { "type": "string" }, "counts": { "type": "object", "required": [ "core", "aiValueChain", "aiAdditional", "total" ], "properties": { "core": { "type": "integer", "const": 300 }, "aiValueChain": { "type": "integer", "const": 54 }, "aiAdditional": { "type": "integer", "minimum": 0 }, "total": { "type": "integer", "minimum": 300, "maximum": 354 } } }, "companies": { "type": "array", "minItems": 300, "maxItems": 354, "items": { "type": "object", "required": [ "ticker", "nameKr", "companyName", "market", "coreRank", "aiValueChain", "includedBy" ], "properties": { "ticker": { "type": "string", "pattern": "^[0-9A-Z]{6}$" }, "nameKr": { "type": "string" }, "companyName": { "type": [ "string", "null" ] }, "market": { "type": "string", "enum": [ "KOSPI", "KOSDAQ" ] }, "coreRank": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 200, "description": "Rank within the pinned exchange-specific core list; null for an AI-only addition." }, "aiValueChain": { "type": "boolean" }, "includedBy": { "type": "array", "minItems": 1, "maxItems": 2, "uniqueItems": true, "items": { "type": "string", "enum": [ "core300", "ai_value_chain" ] } } } } } } }, "StandardEnvelope": { "type": "object", "required": [ "apiVersion", "generatedAt", "product", "ticker", "company", "latestPeriod", "requestId" ], "properties": { "apiVersion": { "type": "string", "const": "dart-fundamentals.v0.2" }, "generatedAt": { "type": "string", "format": "date-time" }, "requestId": { "type": "string", "format": "uuid" }, "product": { "$ref": "#/components/schemas/Product" }, "ticker": { "type": "string", "pattern": "^[0-9A-Z]{6}$" }, "company": { "$ref": "#/components/schemas/CompanyIdentity" }, "latestPeriod": { "anyOf": [ { "$ref": "#/components/schemas/LatestPeriod" }, { "type": "null" } ] } } }, "FinancialFactsResponse": { "allOf": [ { "$ref": "#/components/schemas/StandardEnvelope" }, { "type": "object", "required": [ "rowCount", "totalRows", "distinctMetrics", "reportingPeriods", "updatedAt", "pagination", "financialFacts", "dataContract" ], "properties": { "rowCount": { "type": "integer", "minimum": 0 }, "totalRows": { "type": "integer", "minimum": 0 }, "distinctMetrics": { "type": "integer", "minimum": 0 }, "reportingPeriods": { "type": "integer", "minimum": 0 }, "updatedAt": { "type": [ "number", "null" ], "description": "Unix milliseconds." }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "financialFacts": { "type": "array", "items": { "$ref": "#/components/schemas/FinancialFact" } }, "dataContract": { "const": "dart-reported-financials.v1" } } } ] }, "PeriodsResponse": { "allOf": [ { "$ref": "#/components/schemas/StandardEnvelope" }, { "type": "object", "required": [ "available", "missingReason", "rowCount", "totalRows", "updatedAt", "retentionPolicy", "historyWindow", "pagination", "periods" ], "properties": { "available": { "type": "boolean" }, "missingReason": { "type": [ "string", "null" ], "enum": [ "source_not_reported", null ] }, "rowCount": { "type": "integer", "minimum": 0 }, "totalRows": { "type": "integer", "minimum": 0 }, "updatedAt": { "type": [ "number", "null" ], "description": "Unix milliseconds." }, "retentionPolicy": { "$ref": "#/components/schemas/HistoryRetentionPolicy" }, "historyWindow": { "$ref": "#/components/schemas/HistoryWindow" }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "periods": { "type": "array", "items": { "$ref": "#/components/schemas/FinancialPeriod" } } } } ] }, "CoverageResponse": { "allOf": [ { "$ref": "#/components/schemas/StandardEnvelope" }, { "type": "object", "required": [ "available", "missingReason", "retentionPolicy", "coverage" ], "properties": { "available": { "type": "boolean" }, "missingReason": { "type": [ "string", "null" ], "enum": [ "source_not_reported", null ] }, "retentionPolicy": { "$ref": "#/components/schemas/HistoryRetentionPolicy" }, "coverage": { "$ref": "#/components/schemas/CoverageBlock" } } } ] }, "IndicatorsResponse": { "allOf": [ { "type": "object", "required": [ "apiVersion", "generatedAt", "product", "ticker", "company", "latestPeriod", "requestId" ], "properties": { "apiVersion": { "const": "dart-key-financials.v1" }, "generatedAt": { "type": "string", "format": "date-time" }, "requestId": { "type": "string", "format": "uuid" }, "product": { "$ref": "#/components/schemas/Product" }, "ticker": { "type": "string", "pattern": "^[0-9A-Z]{6}$" }, "company": { "$ref": "#/components/schemas/CompanyIdentity" }, "latestPeriod": { "anyOf": [ { "$ref": "#/components/schemas/LatestPeriod" }, { "type": "null" } ] } } }, { "type": "object", "required": [ "definitions", "rowCount", "totalRows", "financialIndicators", "pagination", "conventions" ], "properties": { "definitions": { "type": "object" }, "rowCount": { "type": "integer", "minimum": 0 }, "totalRows": { "type": "integer", "minimum": 0 }, "financialIndicators": { "type": "array", "items": { "$ref": "#/components/schemas/CalculatedFinancialPeriod" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "conventions": { "type": "object" } } } ] }, "StatementsResponse": { "allOf": [ { "$ref": "#/components/schemas/StandardEnvelope" }, { "type": "object", "required": [ "rowCount", "totalRows", "pagination", "sections", "statementLines" ], "properties": { "rowCount": { "type": "integer", "minimum": 0 }, "totalRows": { "type": "integer", "minimum": 0 }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "sections": { "type": "array", "items": { "$ref": "#/components/schemas/StatementSection" } }, "statementLines": { "type": "array", "items": { "$ref": "#/components/schemas/StatementLine" } } } } ] }, "FilingsResponse": { "allOf": [ { "$ref": "#/components/schemas/StandardEnvelope" }, { "type": "object", "required": [ "rowCount", "totalRows", "pagination", "filings" ], "properties": { "rowCount": { "type": "integer", "minimum": 0 }, "totalRows": { "type": "integer", "minimum": 0 }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "filings": { "type": "array", "items": { "$ref": "#/components/schemas/Filing" } } } } ] }, "Phase1FundamentalsResponse": { "type": "object", "required": [ "apiVersion", "generatedAt", "requestId", "product", "ticker", "company", "metricProfile", "readiness", "financials", "dataContract" ], "properties": { "apiVersion": { "type": "string", "const": "dart-fundamentals.v0.2" }, "generatedAt": { "type": "string", "format": "date-time" }, "requestId": { "type": "string", "format": "uuid" }, "product": { "$ref": "#/components/schemas/Product" }, "ticker": { "type": "string", "pattern": "^[0-9A-Z]{6}$" }, "company": { "$ref": "#/components/schemas/CompanyIdentity" }, "metricProfile": { "$ref": "#/components/schemas/MetricProfile" }, "readiness": { "$ref": "#/components/schemas/Readiness" }, "financials": { "$ref": "#/components/schemas/FinancialsBlock" }, "dataContract": { "const": "dart-reported-financials.v1" } }, "additionalProperties": false }, "Product": { "type": "object", "required": [ "key", "label", "requiresContext" ], "properties": { "key": { "type": "string", "const": "standard_fundamentals" }, "label": { "type": "string", "const": "Standard API" }, "requiresContext": { "type": "boolean", "const": false } }, "additionalProperties": false }, "CompanyIdentity": { "type": "object", "required": [ "ticker", "corpCode", "companyName", "listedNameKo", "market", "marketCapKrw", "marketCapAsOf", "marketCapSource", "marketCapCollectedAt" ], "properties": { "ticker": { "type": "string", "pattern": "^[0-9A-Z]{6}$" }, "corpCode": { "type": [ "string", "null" ] }, "companyName": { "type": "string" }, "listedNameKo": { "type": [ "string", "null" ] }, "market": { "type": [ "string", "null" ] }, "marketCapKrw": { "type": [ "number", "null" ], "description": "Daily KRW market-cap reference from the identified data.go.kr price row; not a live or intraday quote." }, "marketCapAsOf": { "type": [ "string", "null" ], "pattern": "^[0-9]{8}$", "description": "Source basis date from public_stock_price_items.bas_dt (YYYYMMDD)." }, "marketCapSource": { "type": [ "string", "null" ], "enum": [ "data.go.kr:GetStockSecuritiesInfoService/getStockPriceInfo", null ], "description": "Provider and operation that supplied marketCapKrw." }, "marketCapCollectedAt": { "type": [ "number", "null" ], "description": "Collection time from public_stock_price_items.fetched_at in Unix milliseconds." } }, "additionalProperties": false }, "MetricProfile": { "type": "object", "required": [ "key", "label", "hardMetrics", "coreMetrics" ], "properties": { "key": { "type": "string", "enum": [ "general", "financials", "investment_holding", "spac" ] }, "label": { "type": "string" }, "hardMetrics": { "type": "array", "items": { "type": "string" } }, "coreMetrics": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "Readiness": { "type": "object", "required": [ "score", "pilotReady", "warnings", "checks" ], "properties": { "score": { "type": "number" }, "pilotReady": { "type": "boolean" }, "warnings": { "type": "array", "items": { "type": "string" } }, "checks": { "type": "object", "required": [ "financialFacts", "sourcePeriod" ], "properties": { "financialFacts": { "type": "boolean" }, "sourcePeriod": { "type": "boolean" } }, "additionalProperties": false } }, "additionalProperties": false }, "FinancialsBlock": { "type": "object", "required": [ "latestPeriod", "periodRows", "statementLines", "facts", "distinctMetrics", "indicatorFacts", "dataCompleteness", "valueSourceCounts", "recentPeriodCoverage", "metrics" ], "properties": { "latestPeriod": { "anyOf": [ { "$ref": "#/components/schemas/LatestPeriod" }, { "type": "null" } ] }, "periodRows": { "type": "number" }, "statementLines": { "type": "number" }, "facts": { "type": "number" }, "distinctMetrics": { "type": "number" }, "indicatorFacts": { "type": "number" }, "dataCompleteness": { "$ref": "#/components/schemas/DataCompleteness" }, "valueSourceCounts": { "type": "array", "items": { "$ref": "#/components/schemas/ValueSourceCount" } }, "recentPeriodCoverage": { "type": "array", "items": { "$ref": "#/components/schemas/RecentPeriodCoverage" } }, "metrics": { "$ref": "#/components/schemas/FundamentalsMetricMap" } }, "additionalProperties": false }, "LatestPeriod": { "type": "object", "required": [ "fiscalYear", "fiscalQuarter", "reportCode", "reportName", "fsDiv", "fsName", "periodEnd", "rceptNo", "filingDate", "sourceEndpoint", "currency", "fetchedAt", "updatedAt" ], "properties": { "fiscalYear": { "type": "number" }, "fiscalQuarter": { "type": [ "number", "null" ] }, "reportCode": { "type": "string" }, "reportName": { "type": [ "string", "null" ] }, "fsDiv": { "type": "string" }, "fsName": { "type": [ "string", "null" ] }, "periodEnd": { "type": [ "string", "null" ] }, "rceptNo": { "type": [ "string", "null" ] }, "filingDate": { "type": [ "string", "null" ] }, "periodType": { "type": [ "string", "null" ] }, "periodStart": { "type": [ "string", "null" ] }, "sourceEndpoint": { "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ] }, "fetchedAt": { "type": [ "number", "null" ], "description": "Unix milliseconds." }, "updatedAt": { "type": [ "number", "null" ], "description": "Unix milliseconds." } }, "additionalProperties": false }, "HistoryWindow": { "type": "object", "required": [ "logicalPeriodCount", "fromFiscalYear", "throughFiscalYear", "fromAsOfDate", "throughAsOfDate" ], "properties": { "logicalPeriodCount": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 8, "description": "Distinct fiscalYear + reportCode fiscal reporting quarter slots; CFS and OFS count once. Production Standard retains at most 8." }, "fromFiscalYear": { "type": [ "integer", "null" ] }, "throughFiscalYear": { "type": [ "integer", "null" ] }, "fromAsOfDate": { "type": [ "string", "null" ] }, "throughAsOfDate": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "HistoryRetentionPolicy": { "type": "object", "required": [ "mode", "configurationMode", "keepLogicalPeriods", "configuredMinimum", "configuredMaximum", "logicalPeriodKey", "evictionRule", "archiveIncluded", "source", "checkpointStatus", "checkpointUpdatedAt" ], "properties": { "mode": { "type": "string", "const": "rolling_logical_reporting_periods" }, "configurationMode": { "type": "string", "enum": [ "default", "override", "legacy_unknown" ], "description": "Checkpoint origin. Every sale-eligible production mode resolves to the same fixed 8-quarter-slot capacity." }, "keepLogicalPeriods": { "type": "integer", "const": 8, "description": "Fixed production Standard fiscal reporting quarter-slot capacity. A disabled or non-8 checkpoint blocks sale readiness." }, "configuredMinimum": { "type": "integer", "const": 8 }, "configuredMaximum": { "type": "integer", "const": 8 }, "logicalPeriodKey": { "type": "string" }, "evictionRule": { "type": "string" }, "archiveIncluded": { "type": "boolean", "const": false }, "source": { "type": "string", "enum": [ "dart_financial_retention_state", "checked_in_default" ] }, "checkpointStatus": { "type": [ "string", "null" ], "description": "Last persisted retention evaluation status. skipped_validation and disabled are not sale-eligible." }, "checkpointUpdatedAt": { "type": [ "number", "null" ], "description": "Retention checkpoint update time in Unix milliseconds, or null when the checked-in default applies." } }, "additionalProperties": false }, "FinancialPeriod": { "allOf": [ { "$ref": "#/components/schemas/DartRowProvenance" }, { "type": "object", "required": [ "ticker", "corpCode", "fiscalYear", "fiscalQuarter", "reportCode", "reportName", "fsDiv", "fsName", "periodType", "periodStart", "periodEnd", "sourceDocumentId", "currency", "isDerived", "formula", "fetchedAt", "updatedAt" ], "properties": { "ticker": { "type": "string", "pattern": "^[0-9A-Z]{6}$" }, "corpCode": { "type": [ "string", "null" ] }, "fiscalYear": { "type": "integer" }, "fiscalQuarter": { "type": [ "integer", "null" ] }, "reportCode": { "type": "string" }, "reportName": { "type": [ "string", "null" ] }, "fsDiv": { "type": "string", "enum": [ "CFS", "OFS" ] }, "fsName": { "type": [ "string", "null" ] }, "periodType": { "type": [ "string", "null" ] }, "periodStart": { "type": [ "string", "null" ] }, "periodEnd": { "type": [ "string", "null" ] }, "sourceDocumentId": { "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ] }, "isDerived": { "type": "boolean", "const": false }, "formula": { "type": "null" }, "fetchedAt": { "type": [ "number", "null" ], "description": "Unix milliseconds." }, "updatedAt": { "type": [ "number", "null" ], "description": "Unix milliseconds." } } } ] }, "CoverageBlock": { "type": "object", "required": [ "source", "sourceUrl", "sourceDocumentId", "asOfDate", "collectedAt", "updatedAt", "isDerived", "formula", "historyWindow", "datasets" ], "properties": { "source": { "type": "string", "const": "DART Open API" }, "sourceUrl": { "type": [ "string", "null" ], "format": "uri" }, "sourceDocumentId": { "type": [ "string", "null" ] }, "asOfDate": { "type": [ "string", "null" ] }, "collectedAt": { "type": [ "number", "null" ], "description": "Maximum source collection timestamp in Unix milliseconds." }, "updatedAt": { "type": [ "number", "null" ], "description": "Maximum serving update timestamp in Unix milliseconds." }, "isDerived": { "type": "boolean", "const": true }, "formula": { "type": "string" }, "historyWindow": { "$ref": "#/components/schemas/CoverageHistoryWindow" }, "datasets": { "type": "array", "items": { "$ref": "#/components/schemas/CoverageDataset" }, "minItems": 7, "maxItems": 7 } }, "additionalProperties": false }, "CoverageHistoryWindow": { "type": "object", "required": [ "periodRows", "logicalPeriodCount", "fromFiscalYear", "throughFiscalYear", "fromAsOfDate", "throughAsOfDate" ], "properties": { "periodRows": { "type": [ "integer", "null" ], "minimum": 0 }, "logicalPeriodCount": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 8, "description": "Distinct fiscalYear + reportCode fiscal reporting quarter slots; CFS and OFS count once. Production Standard retains at most 8." }, "fromFiscalYear": { "type": [ "integer", "null" ] }, "throughFiscalYear": { "type": [ "integer", "null" ] }, "fromAsOfDate": { "type": [ "string", "null" ] }, "throughAsOfDate": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "CoverageDataset": { "type": "object", "required": [ "key", "available", "rowCount", "missingReason", "source", "sourceUrl", "asOfDate", "collectedAt", "updatedAt", "isDerived", "formula" ], "properties": { "key": { "type": "string", "enum": [ "periods", "financialFacts", "indicators", "statementLines", "filings", "snapshots", "earningsBriefs" ] }, "available": { "type": "boolean" }, "rowCount": { "type": [ "integer", "null" ], "minimum": 0 }, "missingReason": { "type": [ "string", "null" ], "enum": [ "source_table_unavailable", "source_not_reported", null ] }, "source": { "type": "string", "const": "DART Open API" }, "sourceUrl": { "type": "null" }, "asOfDate": { "type": [ "string", "null" ] }, "collectedAt": { "type": [ "number", "null" ], "description": "Unix milliseconds." }, "updatedAt": { "type": [ "number", "null" ], "description": "Unix milliseconds." }, "isDerived": { "type": "boolean", "const": true }, "formula": { "type": "string" } }, "additionalProperties": false }, "DataCompleteness": { "type": "object", "required": [ "accountIdCoveragePct", "latestCoreMetricCoveragePct", "latestHardMetricCoveragePct", "missingHardMetrics" ], "properties": { "accountIdCoveragePct": { "type": "number" }, "latestCoreMetricCoveragePct": { "type": "number" }, "latestHardMetricCoveragePct": { "type": "number" }, "missingHardMetrics": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "ValueSourceCount": { "type": "object", "required": [ "valueSource", "facts" ], "properties": { "valueSource": { "type": "string" }, "facts": { "type": "number" } }, "additionalProperties": false }, "RecentPeriodCoverage": { "type": "object", "required": [ "fiscalYear", "fiscalQuarter", "reportCode", "fsDiv", "metrics" ], "properties": { "fiscalYear": { "type": "number" }, "fiscalQuarter": { "type": [ "number", "null" ] }, "reportCode": { "type": "string" }, "fsDiv": { "type": "string" }, "metrics": { "type": "number" } }, "additionalProperties": false }, "FundamentalsMetricMap": { "type": "object", "required": [ "revenue", "operating_income", "pretax_income", "net_income", "total_assets", "total_liabilities", "total_equity", "cash_and_equivalents", "operating_cash_flow", "investing_cash_flow", "financing_cash_flow" ], "properties": { "revenue": { "$ref": "#/components/schemas/MetricValue" }, "operating_income": { "$ref": "#/components/schemas/MetricValue" }, "pretax_income": { "$ref": "#/components/schemas/MetricValue" }, "net_income": { "$ref": "#/components/schemas/MetricValue" }, "total_assets": { "$ref": "#/components/schemas/MetricValue" }, "total_liabilities": { "$ref": "#/components/schemas/MetricValue" }, "total_equity": { "$ref": "#/components/schemas/MetricValue" }, "cash_and_equivalents": { "$ref": "#/components/schemas/MetricValue" }, "operating_cash_flow": { "$ref": "#/components/schemas/MetricValue" }, "investing_cash_flow": { "$ref": "#/components/schemas/MetricValue" }, "financing_cash_flow": { "$ref": "#/components/schemas/MetricValue" } }, "additionalProperties": false }, "MetricValue": { "type": "object", "required": [ "metricKey", "available", "amount", "missingReason", "missingReasonDetail", "currency", "unit", "unitMultiplier", "statement", "durationType", "valueSource", "sourceAccountId", "sourceAccountName", "formulaKey", "formulaExpression", "confidence", "fetchedAt", "updatedAt" ], "properties": { "metricKey": { "type": "string", "enum": [ "revenue", "operating_income", "pretax_income", "net_income", "total_assets", "total_liabilities", "total_equity", "cash_and_equivalents", "operating_cash_flow", "investing_cash_flow", "financing_cash_flow" ] }, "available": { "type": "boolean" }, "amount": { "type": [ "number", "null" ] }, "missingReason": { "type": [ "string", "null" ], "enum": [ "not_applicable_for_industry", "source_not_reported", "source_reported_in_other_scope", "source_reported_but_not_mapped", "derived_inputs_missing", "no_selected_period", null ] }, "missingReasonDetail": { "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ], "description": "Uppercase source ISO currency for monetary facts; null for pct/ratio and unavailable metrics." }, "unit": { "enum": [ "currency", null ] }, "unitMultiplier": { "type": [ "number", "null" ] }, "statement": { "type": [ "string", "null" ] }, "durationType": { "type": [ "string", "null" ] }, "valueSource": { "enum": [ "reported", null ] }, "sourceAccountId": { "type": [ "string", "null" ] }, "sourceAccountName": { "type": [ "string", "null" ] }, "formulaKey": { "type": "null" }, "formulaExpression": { "type": "null" }, "confidence": { "type": [ "number", "null" ] }, "fetchedAt": { "type": [ "number", "null" ] }, "updatedAt": { "type": [ "number", "null" ] } }, "additionalProperties": false }, "Pagination": { "type": "object", "required": [ "limit", "offset", "returned", "totalRows", "hasMore", "nextOffset", "maxLimit", "maxOffset" ], "properties": { "limit": { "type": "integer", "minimum": 1 }, "offset": { "type": "integer", "minimum": 0 }, "returned": { "type": "integer", "minimum": 0 }, "totalRows": { "type": "integer", "minimum": 0 }, "hasMore": { "type": "boolean" }, "nextOffset": { "type": [ "integer", "null" ], "minimum": 0 }, "maxLimit": { "type": "integer", "minimum": 1 }, "maxOffset": { "type": "integer", "const": 100000 } }, "additionalProperties": false }, "DartRowProvenance": { "type": "object", "required": [ "source", "sourceUrl", "asOfDate", "collectedAt", "rceptNo", "filingDate", "sourceEndpoint" ], "properties": { "source": { "type": "string", "const": "DART Open API" }, "sourceUrl": { "type": [ "string", "null" ], "format": "uri" }, "asOfDate": { "type": [ "string", "null" ], "description": "Source period end, settlement date, or filing date used as the row's as-of date." }, "collectedAt": { "type": [ "number", "null" ], "description": "Unix milliseconds." }, "rceptNo": { "type": [ "string", "null" ] }, "filingDate": { "type": [ "string", "null" ] }, "sourceEndpoint": { "type": [ "string", "null" ] } } }, "FinancialFact": { "allOf": [ { "$ref": "#/components/schemas/DartRowProvenance" }, { "type": "object", "required": [ "ticker", "corpCode", "fiscalYear", "fiscalQuarter", "reportCode", "reportName", "fsDiv", "fsName", "metricKey", "statement", "periodType", "durationType", "periodStart", "periodEnd", "amount", "currency", "unit", "unitMultiplier", "valueSource", "isDerived", "sourceAccountId", "sourceAccountName", "mappingBasis", "sourceLineKeys", "derivationInputs", "metricDefinitionVersion", "formulaKey", "formulaExpression", "formula", "confidence", "fetchedAt", "updatedAt" ], "properties": { "ticker": { "type": "string", "pattern": "^[0-9A-Z]{6}$" }, "corpCode": { "type": "string" }, "fiscalYear": { "type": "integer" }, "fiscalQuarter": { "type": [ "integer", "null" ] }, "reportCode": { "type": "string" }, "reportName": { "type": [ "string", "null" ] }, "fsDiv": { "type": "string", "enum": [ "CFS", "OFS" ] }, "fsName": { "type": [ "string", "null" ] }, "metricKey": { "enum": [ "revenue", "operating_income", "pretax_income", "net_income", "total_assets", "total_liabilities", "total_equity", "cash_and_equivalents", "operating_cash_flow", "investing_cash_flow", "financing_cash_flow" ] }, "statement": { "type": "string" }, "periodType": { "type": "string" }, "durationType": { "type": "string" }, "periodStart": { "type": [ "string", "null" ] }, "periodEnd": { "type": [ "string", "null" ] }, "amount": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ], "description": "Uppercase source ISO currency for monetary facts; null for pct/ratio." }, "unit": { "const": "currency" }, "unitMultiplier": { "type": [ "number", "null" ] }, "valueSource": { "const": "reported" }, "isDerived": { "const": false }, "sourceAccountId": { "type": [ "string", "null" ] }, "sourceAccountName": { "type": [ "string", "null" ], "description": "Raw source label retained for lineage; it may be Korean." }, "mappingBasis": { "type": [ "string", "null" ], "enum": [ "account_id", "source_label", "mixed_source_lineage", "indicator_code", "derived_formula", null ] }, "sourceLineKeys": { "type": "array", "items": { "type": "string" } }, "derivationInputs": { "type": "array", "maxItems": 0 }, "metricDefinitionVersion": { "type": "string" }, "formulaKey": { "type": "null" }, "formulaExpression": { "type": "null" }, "formula": { "type": "null" }, "confidence": { "type": [ "number", "null" ] }, "fetchedAt": { "type": [ "number", "null" ], "description": "Unix milliseconds." }, "updatedAt": { "type": [ "number", "null" ], "description": "Unix milliseconds." } } } ] }, "StatementSection": { "type": "object", "required": [ "statementCode", "statementName", "statementLabelEn", "lineCount" ], "properties": { "statementCode": { "type": "string" }, "statementName": { "type": "string" }, "statementLabelEn": { "type": "string" }, "lineCount": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "StatementLine": { "allOf": [ { "$ref": "#/components/schemas/DartRowProvenance" }, { "type": "object", "required": [ "ticker", "corpCode", "fiscalYear", "fiscalQuarter", "reportCode", "reportName", "fsDiv", "fsName", "statementCode", "statementName", "statementLabelEn", "statementLabelKo", "statementLabelSource", "sourceStatementName", "lineKey", "accountId", "accountName", "sourceAccountName", "accountLabelKo", "accountLabelEn", "accountLabelSource", "accountLabelSourceEndpoint", "accountLabelBaselineDate", "canonicalMetricKeys", "canonicalMetricLabels", "accountDetail", "sourceAccountDetail", "accountDetailEn", "accountOrder", "currency", "unit", "currentPeriodName", "currentPeriod", "currentAmount", "priorPeriodName", "priorPeriod", "priorAmount", "beforePriorPeriodName", "beforePriorPeriod", "beforePriorAmount", "periodStart", "periodEnd", "isDerived", "formula", "fetchedAt", "updatedAt" ], "properties": { "ticker": { "type": "string", "pattern": "^[0-9A-Z]{6}$" }, "corpCode": { "type": "string" }, "fiscalYear": { "type": "integer" }, "fiscalQuarter": { "type": [ "integer", "null" ] }, "reportCode": { "type": "string" }, "reportName": { "type": [ "string", "null" ] }, "fsDiv": { "type": "string", "enum": [ "CFS", "OFS" ] }, "fsName": { "type": [ "string", "null" ] }, "statementCode": { "type": "string" }, "statementName": { "type": "string" }, "statementLabelEn": { "type": "string" }, "statementLabelKo": { "type": [ "string", "null" ], "description": "Raw Korean DART statement label when available." }, "statementLabelSource": { "type": "string", "enum": [ "official_open_dart_en", "canonical_statement_code", "source_label" ] }, "sourceStatementName": { "type": "string", "description": "Raw DART source statement label; it may be Korean." }, "lineKey": { "type": "string" }, "accountId": { "type": [ "string", "null" ] }, "accountName": { "type": "string", "description": "Raw DART source account label; it may be Korean." }, "sourceAccountName": { "type": "string", "description": "Alias preserving the raw source account label." }, "accountLabelKo": { "type": [ "string", "null" ], "description": "Raw Korean source label, or the official Korean taxonomy label when available." }, "accountLabelEn": { "type": [ "string", "null" ], "description": "Official OpenDART English label, official English taxonomy label, canonical metric label, or stable account-ID label; null when no source-backed English display label is available." }, "accountLabelSource": { "type": "string", "enum": [ "official_open_dart_en", "official_open_dart_taxonomy", "official_open_dart_taxonomy_reverse", "canonical_metric", "provider_curated_non_official", "account_id", "source_label", "untranslated_source_label" ] }, "accountLabelSourceEndpoint": { "type": [ "string", "null" ] }, "accountLabelBaselineDate": { "type": [ "string", "null" ] }, "canonicalMetricKeys": { "type": "array", "items": { "type": "string" } }, "canonicalMetricLabels": { "type": "array", "items": { "type": "string" } }, "accountDetail": { "type": [ "string", "null" ] }, "sourceAccountDetail": { "type": [ "string", "null" ], "description": "Raw Korean source detail when present." }, "accountDetailEn": { "type": [ "string", "null" ], "description": "Official English OpenDART detail when matched." }, "accountOrder": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "unit": { "type": [ "string", "null" ], "enum": [ "currency", "pct", "ratio", null ] }, "currentPeriodName": { "type": [ "string", "null" ] }, "currentPeriod": { "type": [ "string", "null" ] }, "currentAmount": { "type": [ "number", "null" ] }, "priorPeriodName": { "type": [ "string", "null" ] }, "priorPeriod": { "type": [ "string", "null" ] }, "priorAmount": { "type": [ "number", "null" ] }, "beforePriorPeriodName": { "type": [ "string", "null" ] }, "beforePriorPeriod": { "type": [ "string", "null" ] }, "beforePriorAmount": { "type": [ "number", "null" ] }, "periodStart": { "type": [ "string", "null" ] }, "periodEnd": { "type": [ "string", "null" ] }, "isDerived": { "type": "boolean", "const": false }, "formula": { "type": "null" }, "fetchedAt": { "type": [ "number", "null" ], "description": "Unix milliseconds." }, "updatedAt": { "type": [ "number", "null" ], "description": "Unix milliseconds." } } } ] }, "Filing": { "type": "object", "required": [ "rceptNo", "corpCode", "corpName", "ticker", "reportName", "filingDate", "filerName", "remarks", "source", "sourceUrl", "sourceDocumentId", "asOfDate", "fetchedAt", "collectedAt", "updatedAt" ], "properties": { "rceptNo": { "type": "string" }, "corpCode": { "type": "string" }, "corpName": { "type": "string" }, "ticker": { "type": "string", "pattern": "^[0-9A-Z]{6}$" }, "reportName": { "type": [ "string", "null" ] }, "filingDate": { "type": "string" }, "filerName": { "type": "string" }, "remarks": { "type": [ "string", "null" ] }, "source": { "type": "string", "const": "DART Open API" }, "sourceUrl": { "type": [ "string", "null" ], "format": "uri" }, "sourceDocumentId": { "type": "string" }, "asOfDate": { "type": [ "string", "null" ] }, "fetchedAt": { "type": [ "number", "null" ], "description": "Unix milliseconds." }, "collectedAt": { "type": [ "number", "null" ], "description": "Unix milliseconds." }, "updatedAt": { "type": [ "number", "null" ], "description": "Unix milliseconds." } }, "additionalProperties": false }, "ErrorResponse": { "type": "object", "required": [ "error", "generatedAt" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "invalid_ticker", "invalid_parameter", "ticker_not_found", "ticker_outside_coverage", "history_window_pending", "unauthorized", "entitlement_required", "access_inactive", "api_key_not_configured", "api_key_store_unavailable", "rate_limit_store_unavailable", "financial_store_unavailable", "rate_limit_exceeded", "internal_error" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" }, "details": { "type": "object" } }, "additionalProperties": false }, "generatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "CalculationInput": { "type": "object", "properties": { "ticker": { "type": "string" }, "fiscalYear": { "type": "integer" }, "reportCode": { "type": "string" }, "fsDiv": { "enum": [ "CFS", "OFS" ] }, "metricKey": { "enum": [ "revenue", "operating_income", "pretax_income", "net_income", "total_assets", "total_liabilities", "total_equity", "cash_and_equivalents", "operating_cash_flow", "investing_cash_flow", "financing_cash_flow", "current_assets", "current_liabilities", "inventory" ] }, "amount": { "type": "number" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "unitMultiplier": { "type": "number" }, "durationType": { "type": "string" }, "rceptNo": { "type": "string" }, "sourceUrl": { "type": "string", "format": "uri" }, "sourceAccountId": { "type": [ "string", "null" ] }, "sourceLineKeys": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "collectedAt": { "type": [ "number", "null" ] }, "updatedAt": { "type": [ "number", "null" ] } }, "required": [ "ticker", "fiscalYear", "reportCode", "fsDiv", "metricKey", "amount", "currency", "unitMultiplier", "durationType", "rceptNo", "sourceUrl", "sourceAccountId", "sourceLineKeys", "collectedAt", "updatedAt" ], "additionalProperties": false }, "CalculatedFinancialMetric": { "type": "object", "properties": { "metricKey": { "enum": [ "operating_margin_pct", "net_margin_pct", "liabilities_to_equity_pct", "quick_ratio_pct", "roe_total_equity_annual_pct" ] }, "label": { "type": "string" }, "formula": { "type": "string" }, "basis": { "type": "string" }, "amount": { "type": [ "number", "null" ] }, "available": { "type": "boolean" }, "missingReason": { "type": [ "string", "null" ] }, "unit": { "const": "pct" }, "currency": { "type": "null" }, "isDerived": { "const": true }, "valueSource": { "const": "derived" }, "durationType": { "enum": [ "quarter", "annual", "instant" ] }, "inputs": { "type": "array", "items": { "$ref": "#/components/schemas/CalculationInput" } } }, "required": [ "metricKey", "label", "formula", "basis", "amount", "available", "missingReason", "unit", "currency", "isDerived", "valueSource", "durationType", "inputs" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "available": { "const": true } } }, "then": { "properties": { "amount": { "type": "number" }, "missingReason": { "type": "null" } } } }, { "if": { "properties": { "available": { "const": false } } }, "then": { "properties": { "amount": { "type": "null" }, "missingReason": { "type": "string" } } } } ] }, "CalculatedFinancialPeriod": { "type": "object", "properties": { "ticker": { "type": "string" }, "fiscalYear": { "type": "integer" }, "reportCode": { "type": "string" }, "fsDiv": { "enum": [ "CFS", "OFS" ] }, "rceptNo": { "type": [ "string", "null" ] }, "filingDate": { "type": [ "string", "null" ] }, "periodEnd": { "type": [ "string", "null" ] }, "metrics": { "type": "object", "properties": { "operating_margin_pct": { "$ref": "#/components/schemas/CalculatedFinancialMetric" }, "net_margin_pct": { "$ref": "#/components/schemas/CalculatedFinancialMetric" }, "liabilities_to_equity_pct": { "$ref": "#/components/schemas/CalculatedFinancialMetric" }, "quick_ratio_pct": { "$ref": "#/components/schemas/CalculatedFinancialMetric" }, "roe_total_equity_annual_pct": { "$ref": "#/components/schemas/CalculatedFinancialMetric" } }, "required": [ "operating_margin_pct", "net_margin_pct", "liabilities_to_equity_pct", "quick_ratio_pct", "roe_total_equity_annual_pct" ], "additionalProperties": false } }, "required": [ "ticker", "fiscalYear", "reportCode", "fsDiv", "rceptNo", "filingDate", "periodEnd", "metrics" ], "additionalProperties": false } } } }