{ "openapi": "3.1.0", "info": { "x-lang": "en", "title": "Phoenix AI Data API", "version": "1.16.0", "x-changelog": [ { "version": "1.16.0", "date": "2026-10-28", "changes": [ "GET /us-earnings, GET /us-earnings/{id} and the us_earnings.figures webhook add segments: revenue and segment profit per business segment from the release's segment table (table-cell provenance, growth and margin computed by code, reconciling rows marked), included only when segment revenue with the reconciling rows adds up to revenue; segment_check carries the sums compared. Releases read before extractor v3 have an empty array." ] }, { "version": "1.15.0", "date": "2026-10-28", "changes": [ "GET /us-earnings/{id} and the us_earnings.figures webhook add guidance_comparison: each outlook statement of the release from the guidance ledger (measure, fiscal period, basis, bounds, quote) with the change vs the company's previous statement for the same period (stated or compared by code, reference-value change %) and the comparison with the market consensus for the same period, measure and basis last observed before the release day (guidance_ref, guidance_vs_consensus_pct, consensus_position; values observed after the release are never used; consensus_reason when not comparable). Only statements that two readings agree on (the outlook sentence rules and the release extraction: same bounds, period kind and measure) are included, with the period, label and quote as written; single values equal to a reported actual and annual revenue outlooks below the revenue already reported for that fiscal year are left out. null in the list. No provider names." ] }, { "version": "1.14.0", "date": "2026-10-28", "changes": [ "GET /us-earnings, GET /us-earnings/{id} and the us_earnings.figures webhook add reaction: the change from the last regular-session close before the announcement (SEC acceptance, or an earlier company press release on the same US date; announced_basis) to the first regular-session close after it (change_pct, two decimals, computed by code), with both closes and dates, the US Eastern session of the announcement (pre_market, regular, after_hours, market_closed) and a status (measured, pending until that session closes, unavailable with a reason). A close pair is used when the daily series is split-adjustment-confirmed or agrees with an independent daily change for that day (and is withheld when the two disagree by more than 0.05 pp); no price provider is named." ] }, { "version": "1.13.0", "date": "2026-10-28", "changes": [ "Adds US-only GET /us-earnings (list by symbol and filing date, cursor) and GET /us-earnings/{id}: verified figures of 8-K Item 2.02 earnings releases (revenue, operating and net income, GAAP and adjusted EPS, adjusted EBITDA, cash flow, bank and REIT measures) in base units with the prior-year value, yoy_pct or a turnaround label, provenance per figure (table cell with row label and column header, exact quote, or income-statement column) and a cross-check between two readings; margins; company KPIs and outlook with quotes; timestamps (SEC acceptance, release read, extraction, latency); and flash, a Korean one- or two-line summary built by code (no AI). The detail endpoint and the webhook add surprise: actual vs the last pre-release consensus for the same period and basis (GAAP diluted vs adjusted EPS), with the consensus label, observation date and basis; no provider names.", "Webhooks: new events us_earnings.figures (the GET /us-earnings/{id} object when verified figures first exist; again with revision.number and changed when a new reading changes values) and us_filing.analysis_revoked (once per withdrawn version that was announced, with revocation.revoked_at and the replacement if already public). us_filing.analysis_published is sent again for a corrected re-publication, with publication {id, revision, replaces}. Subscriptions created without events receive all four; existing subscriptions keep their event lists.", "Korean /companies/{symbol}/financials: meta.preliminary_releases describes each preliminary earnings release behind preliminary=true rows — exact KRW values as filed, yoy_pct checked against the amounts, turnaround labels instead of a percentage when the sign changed, the pre-release consensus comparison when that release is the actual, and the Korean flash. Row fields are unchanged." ] }, { "version": "1.12.0", "date": "2026-10-27", "changes": [ "Adds US webhooks: POST/GET /webhooks, PATCH/DELETE /webhooks/{id}, POST /webhooks/{id}/test and GET /webhooks/{id}/deliveries (at most 5 per account, paid tiers and PoC with the US market). Events us_filing.detected and us_filing.analysis_published carry the same object as a GET /us-filings item, filtered by symbols, forms and 8-K item codes. Requests are signed with the Standard Webhooks scheme (webhook-id, webhook-timestamp, webhook-signature; whsec_ secret shown once), retried after 1 min, 5 min, 30 min, 2 h and 6 h, and a webhook is disabled after 100 consecutive failures. The OpenAPI document lists both events under webhooks." ] }, { "version": "1.11.0", "date": "2026-10-27", "changes": [ "Adds US-only GET /us-filings: a market-wide SEC filing feed (8-K, 6-K, 10-Q, 10-K, 20-F, 40-F with amendments) for every US-listed company, newest first by filing date, SEC acceptance time and id, with cursor paging. Each filing carries cik, 8-K item codes with Korean and English labels, accepted_at, detected_at, and analysis {status, headline, headline_en, published_at, latency_seconds, page_url}. Filters: since/until (acceptance time), from/to (filing date), form, items, symbol and analysis=published. Report bodies remain a PRO API feature." ] }, { "version": "1.10.0", "date": "2026-10-27", "changes": [ "Adds US-only GET /companies/{symbol}/earnings-surprises (quarterly EPS estimate, actual and surprise history, next release, EPS/revenue estimates with 7–90 day trend and revisions) and GET /companies/{symbol}/analyst-ratings (broker rating and price-target changes, monthly rating distribution, price-target summary). Korean symbols return 400 UNSUPPORTED_MARKET. MCP tools get_us_earnings_surprises and get_us_analyst_ratings map to them." ] }, { "version": "1.9.0", "date": "2026-10-25", "changes": [ "Shared dividend computation and selection: filed fiscal-year and calendar-payment DPS remain distinct, preferred-share guards and coverage limits are preserved, and current-year KR payments do not extend completed-year streaks (N-28). US coverage/at-least and fiscal-year evidence rules remain unchanged. Batch evidence reads use shared Redis caches.", "Screener filters, sorting and limits use the same dividend and valuation authority as returned rows. Web dividend summaries share the same evidence and no longer cap displayed streaks at four years.", "Price availability follows KR/US trading calendars. Canonical period_display/code/end fields accompany deprecated legacy period labels. Typed absence reasons distinguish missing evidence from confirmed zero.", "Korean and English OpenAPI version and x-changelog are generated from this manifest. Release gates cover actual-route consistency and deterministic SQL budgets; PG17/Redis latency benchmarks are separate.", "Documents a correction omitted from 1.8.0: Samsung Electronics PBR/ROE changed from 2.65/31.6 to 2.23/26.5 because BPS/equity used 2026Q2 capital instead of the earlier annual equity basis. This is a denominator-period correction, not a price-only change or ticker-specific rule." ] }, { "version": "1.8.0", "date": "2026-10-25", "changes": [ "KR annual dividend summaries can fall back to the latest completed calendar-year payment ledger with dps_basis=annual_payments_current_share; filing-only fields stay null. Shared payment streaks are independent of display years. TTM DPS/yield now use payment evidence or explicit reasons.", "KR sector_ranking supports company PER/PBR rankings and rejects unsupported metrics with HTTP 400 BAD_REQUEST and an allowed list. Ratio totals are null with ratio_not_additive.", "KR screener ma is withheld with ma_reason when unavailable or not aligned to price_date; ma_source_as_of preserves the signal observation date.", "Reported-quarter tax identities are guarded as well as derived quarters. Adds amortization account code; generic STOCK/common-share attributes no longer imply common security subtype; KRX closed days/hours override cached market sessions." ] }, { "version": "1.7.1", "date": "2026-10-23", "changes": [ "POST /query returns HTTP 403 MARKET_NOT_ENTITLED with rejected_lines and entitled_markets when every line is outside the contract; no daily or AI usage is charged. Mixed authorized requests retain per-line results." ] }, { "version": "1.7.0", "date": "2026-10-23", "changes": [ "Shared Korean stored-price repricing for single and list valuations; separate financial snapshot and price timestamps; bounded stale-snapshot fallback.", "Adds price_date (YYYY-MM-DD), price_time and snapshot_time (ISO 8601 or null) while preserving legacy price_as_of, snapshot_as_of, as_of and query aliases; adds period_display without replacing the stored period label.", "Adds explicit rejected-balance reasons and clarifies the existing consensus date-basis versus reconstruction flag; existing basis values remain unchanged.", "Documents prior disclosure filters, per-line market errors, consensus provenance, preliminary results, listing/trade evidence, preferred-share holds and discontinued_operations_income." ] } ], "description": "Phoenix AI Data API is an enterprise REST API that delivers filings, financials, quotes, news and calendars for companies listed in Korea and the US behind one symbol.\n\nIt covers news · quotes · financial statements · AI stock briefings · filings with AI summaries · the US SEC filing feed · US earnings release figures · ownership · dividends · credit ratings · corporate actions · IR / IPO calendars · global clinical trials · Korean and US economic calendars · the US earnings calendar. US filing and earnings events are also delivered by webhook.\n\n**Base URL** — `https://api.chickstockfi.com/openapi/v1` (the same API also answers at `https://www.chickstockfi.com/openapi/v1`)\n\n**Authentication** — every request needs a Data API key (`ck_live_…`). Send it as `Authorization: Bearer ` or `X-API-Key: `. → [Authentication](https://openapi.chickstockfi.com/en/docs/authentication)\n\n**MCP** — connect this Data API key (`ck_live_…`) to the remote MCP server (`https://www.chickstockfi.com/openapi/pro/v1/mcp`) as an `Authorization: Bearer` header to get the Data API tools. Each tool call counts as one REST request. PRO tools such as conversational questions appear only when you connect with a PRO API key or OAuth. → [MCP](https://openapi.chickstockfi.com/en/docs/mcp)\n\n**Webhooks** — US filing detection, analysis publication and withdrawal, and US earnings release figures are sent to the HTTPS URLs you register (up to 5 per account, signed with Standard Webhooks). Manage them with the Webhooks endpoints; event payloads are under `webhooks` in this document.\n\n**Accounts and plans** — accounts are issued after we review your [access request](https://openapi.chickstockfi.com/en/request). Sign in to the [developer console](https://openapi.chickstockfi.com/en/login) with the issued account and create keys yourself. A PoC (trial) uses every endpoint at the trial limits of a target tier (Launch · Business · Scale) for 7 days by default (the term can be adjusted by agreement); without a target tier it is Launch. Paid-tier accounts (Launch · Business · Scale · Enterprise) use every endpoint at their tier's limits. Pricing depends on the data you need — [contact us](https://openapi.chickstockfi.com/en/#contact) for a quote. → [Rate limits](https://openapi.chickstockfi.com/en/docs/rate-limits)\n\n**Response envelope** — a single document is `{ data, meta }`; a list is `{ data, next_cursor, has_more, meta }`. `meta` carries `as_of`; company endpoints also carry `disclaimer` and `unit_note`. Errors are `{ error: { code, message, docs } }`.\n\n**Korean values** — URL-encode Korean query values (`curl -G --data-urlencode`). English codes (`account=revenue`, `period=FY2025`) need no encoding.\n\n**Get started** — [Quickstart](https://openapi.chickstockfi.com/en/docs/quickstart) · [Errors](https://openapi.chickstockfi.com/en/docs/errors) · [Conventions](https://openapi.chickstockfi.com/en/docs/conventions) · [Changelog](https://openapi.chickstockfi.com/en/docs/changelog) · for AI agents: [llms.txt](https://openapi.chickstockfi.com/llms.txt) · [llms-full.txt](https://openapi.chickstockfi.com/llms-full.txt)\n\n## OpenAPI document\n\nThis reference is generated from the OpenAPI 3.1 document. Download the JSON (https://openapi.chickstockfi.com/openapi.en.json; Korean: https://openapi.chickstockfi.com/openapi.json) and generate a client in any language with OpenAPI tools such as openapi-generator or oapi-codegen. The PRO API document is https://openapi.chickstockfi.com/openapi-pro.json.\n", "contact": { "name": "Phoenix AI sales and technical support", "email": "help@alpsoft.io", "url": "https://openapi.chickstockfi.com/docs/support" }, "termsOfService": "https://openapi.chickstockfi.com/en/terms" }, "servers": [ { "url": "https://api.chickstockfi.com/openapi/v1", "description": "Production" }, { "url": "https://www.chickstockfi.com/openapi/v1", "description": "Production (www)" } ], "tags": [ { "name": "Service", "description": "Service description, this spec, API key info" }, { "name": "Financial statements", "description": "Financial statement accounts (annual, quarterly) and data queries" }, { "name": "Metrics & growth", "description": "Financial ratios, valuation, CAGR, YoY, QoQ" }, { "name": "Revenue mix", "description": "Revenue by segment, product, and region" }, { "name": "Dividends", "description": "Dividend summary and history, annual-report dividend table" }, { "name": "Net income split", "description": "Net income attributable to owners of the parent, consolidated total, and non-controlling interests (Korea)" }, { "name": "Consensus", "description": "Market consensus for revenue and operating income" }, { "name": "Guidance", "description": "Actuals vs. company guidance" }, { "name": "Filing list", "description": "Korea DART and US SEC filing lists" }, { "name": "US earnings figures", "description": "US 8-K earnings release figures — provenance, year-over-year change, pre-release consensus comparison and a Korean flash line" }, { "name": "Filing documents & summaries", "description": "Korean filing source documents and AI summaries" }, { "name": "Webhooks", "description": "Push of US filing and earnings events (webhooks)" }, { "name": "Symbol master", "description": "Korean symbol codes, names and listing status" }, { "name": "Quotes", "description": "Korean quotes, key financials and daily close history" }, { "name": "Major shareholders", "description": "5% major shareholding" }, { "name": "Insider trading", "description": "Shareholdings of officers and major shareholders" }, { "name": "Treasury stock", "description": "Treasury stock acquisitions, disposals, and retirements" }, { "name": "Employees", "description": "Headcount, tenure, and salaries" }, { "name": "Credit ratings", "description": "Credit rating and bond filings" }, { "name": "Clinical trials", "description": "Global clinical trials" }, { "name": "Earnings calendar", "description": "Earnings release schedule" }, { "name": "IR", "description": "IR calendar & materials" }, { "name": "IPO", "description": "IPO subscriptions & new listings" }, { "name": "Corporate actions", "description": "Corporate actions such as capital increases and mergers" }, { "name": "Economic indicators", "description": "Korean and US economic calendar" }, { "name": "News", "description": "News & search" }, { "name": "Briefing", "description": "Daily symbol briefing" }, { "name": "Q&A", "description": "Grounded answers with citations" }, { "name": "Discontinued", "description": "Endpoints available only to keys under existing contracts (pending legal review)" } ], "x-tagGroups": [ { "name": "Getting started", "tags": [ "Service" ] }, { "name": "Company data", "tags": [ "Financial statements", "Metrics & growth", "Revenue mix", "Dividends", "Net income split" ] }, { "name": "Consensus & guidance", "tags": [ "Consensus", "Guidance" ] }, { "name": "Filings", "tags": [ "Filing list", "US earnings figures", "Filing documents & summaries", "Webhooks" ] }, { "name": "Quotes", "tags": [ "Symbol master", "Quotes" ] }, { "name": "Company information", "tags": [ "Major shareholders", "Insider trading", "Treasury stock", "Employees", "Credit ratings", "Clinical trials" ] }, { "name": "Calendars", "tags": [ "Earnings calendar", "IR", "IPO", "Corporate actions", "Economic indicators" ] }, { "name": "News & briefings", "tags": [ "News", "Briefing", "Q&A" ] }, { "name": "Discontinued", "tags": [ "Discontinued" ] } ], "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Authorization: Bearer ck_live_…" }, "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "X-API-Key: ck_live_…" } }, "headers": { "X-RateLimit-Limit": { "description": "Per-minute plan limit. /key uses a separate 30-call, 60-second window per key.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current one-minute window", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "Daily (KST) request quota — per account", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Requests remaining today (KST)", "schema": { "type": "integer" } }, "X-Quota-Period": { "description": "KST date for which the quota is counted (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, "X-Quota-Reset": { "description": "Time the daily quota resets (next KST midnight, ISO 8601)", "schema": { "type": "string", "format": "date-time" } }, "Retry-After": { "description": "Seconds remaining until you may retry", "schema": { "type": "integer" } }, "X-Plan": { "description": "Currently active plan — Free, PoC, Launch, Business, Scale, Enterprise", "schema": { "type": "string", "enum": [ "Free", "PoC", "Launch", "Business", "Scale", "Enterprise" ] } }, "X-Plan-Tier": { "description": "Effective tier label, separate from X-Plan. PoC: Launch, Business or Scale; other plans: their own label.", "schema": { "type": "string", "enum": [ "Free", "Launch", "Business", "Scale", "Enterprise" ] } }, "X-Plan-Expires": { "description": "Plan end time (ISO 8601). Not sent for indefinite plans or Free", "schema": { "type": "string", "format": "date-time" } }, "X-Plan-Ended": { "description": "Only for accounts whose term has ended — the ended plan and time (e.g. PoC; at=2026-11-04T01:00:00.000Z)", "schema": { "type": "string" } }, "X-AI-Quota-Monthly-Limit": { "description": "Monthly AI-call cap; present only when configured.", "schema": { "type": "integer" } }, "X-AI-Quota-Monthly-Remaining": { "description": "Remaining AI calls in this billing cycle; present only when capped.", "schema": { "type": "integer" } }, "X-AI-Quota-Monthly-Reset": { "description": "Next billing cycle or plan expiry, whichever is first (ISO 8601); present only when capped.", "schema": { "type": "string", "format": "date-time" } }, "X-AI-Quota-Limit": { "description": "Daily (KST) AI call quota for PoC, Launch, Business and Scale; PoC-Launch default 20", "schema": { "type": "integer" } }, "X-AI-Quota-Remaining": { "description": "AI calls remaining today (KST)", "schema": { "type": "integer" } }, "X-AI-Quota-Reset": { "description": "Time the AI call quota resets (next KST midnight, ISO 8601)", "schema": { "type": "string", "format": "date-time" } }, "X-Markets": { "description": "Markets this account has contracted (comma-separated, e.g. KR,US) — on every keyed response", "schema": { "type": "string", "example": "KR,US" } } }, "responses": { "BadRequest": { "description": "Invalid input (BAD_REQUEST — including unknown parameters · BAD_DATE · BAD_PERIOD · BAD_SYMBOL · BAD_ID · BAD_QUERY · BAD_CURSOR · UNSUPPORTED_MARKET) · market not available yet (MARKET_NOT_AVAILABLE — JP, CN). An unencoded non-ASCII query can be rejected at the edge with an empty-body 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "BAD_REQUEST": { "summary": "BAD_REQUEST", "value": { "error": { "code": "BAD_REQUEST", "message": "limit: Too big: expected number to be <=200", "docs": "https://openapi.chickstockfi.com/docs" } } }, "BAD_DATE": { "summary": "BAD_DATE", "value": { "error": { "code": "BAD_DATE", "message": "from: must be a real calendar date in YYYY-MM-DD format", "docs": "https://openapi.chickstockfi.com/docs" } } } } } } }, "Unauthorized": { "description": "Missing or malformed key (UNAUTHORIZED) · unknown or revoked key (INVALID_KEY) · expired API docs session key (KEY_EXPIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "An API key is required. Send it as `Authorization: Bearer ` or in the `X-API-Key` header.", "docs": "https://openapi.chickstockfi.com/docs" } } } } }, "PlanRequired": { "description": "Paid tier required (PLAN_REQUIRED) — Free keys or accounts whose paid-tier term has ended. Accounts whose PoC has ended get POC_ENDED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "PLAN_REQUIRED", "message": "This endpoint requires the Enterprise plan. Contact: help@alpsoft.io", "docs": "https://openapi.chickstockfi.com/docs" } } } } }, "PocEnded": { "description": "Account whose PoC term has ended (POC_ENDED) — all endpoints except API key info (GET /key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "POC_ENDED", "message": "Your PoC period has ended. To continue, contact help@alpsoft.io.", "docs": "https://openapi.chickstockfi.com/docs" } } } } }, "QueryPlanRequiredOrMarket": { "description": "Paid tier required (PLAN_REQUIRED) · PoC ended (POC_ENDED) · every line outside the contract (MARKET_NOT_ENTITLED, zero ordinary daily calls and zero AI calls)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "PLAN_REQUIRED": { "value": { "error": { "code": "PLAN_REQUIRED", "message": "This endpoint requires the Enterprise plan. Contact: help@alpsoft.io", "docs": "https://openapi.chickstockfi.com/docs" } } }, "POC_ENDED": { "value": { "error": { "code": "POC_ENDED", "message": "Your PoC period has ended. To continue, contact help@alpsoft.io.", "docs": "https://openapi.chickstockfi.com/docs" } } }, "MARKET_NOT_ENTITLED": { "summary": "Two US lines with a KR-only key", "value": { "error": { "code": "MARKET_NOT_ENTITLED", "message": "Every query line requests a market outside your contract. Check rejected_lines and entitled_markets.", "docs": "https://openapi.chickstockfi.com/docs", "rejected_lines": [ { "index": 0, "market": "US" }, { "index": 1, "market": "US" } ], "entitled_markets": [ "KR" ] } } } } } } }, "PlanRequiredOrMarket": { "description": "Paid tier required (PLAN_REQUIRED) · PoC ended (POC_ENDED) · market outside the contract (MARKET_NOT_ENTITLED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "PLAN_REQUIRED": { "summary": "PLAN_REQUIRED", "value": { "error": { "code": "PLAN_REQUIRED", "message": "This endpoint requires the Enterprise plan. Contact: help@alpsoft.io", "docs": "https://openapi.chickstockfi.com/docs" } } }, "MARKET_NOT_ENTITLED": { "summary": "MARKET_NOT_ENTITLED", "value": { "error": { "code": "MARKET_NOT_ENTITLED", "message": "Your contract does not include United States (US) data. Markets on this account: KR. To add a market, contact help@alpsoft.io.", "docs": "https://openapi.chickstockfi.com/docs" } } }, "POC_ENDED": { "summary": "POC_ENDED", "value": { "error": { "code": "POC_ENDED", "message": "Your PoC period has ended. To continue, contact help@alpsoft.io.", "docs": "https://openapi.chickstockfi.com/docs" } } } } } } }, "PocEndedOrMarket": { "description": "Account whose PoC has ended (POC_ENDED) · market outside the contract (MARKET_NOT_ENTITLED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "POC_ENDED": { "summary": "POC_ENDED", "value": { "error": { "code": "POC_ENDED", "message": "Your PoC period has ended. To continue, contact help@alpsoft.io.", "docs": "https://openapi.chickstockfi.com/docs" } } }, "MARKET_NOT_ENTITLED": { "summary": "MARKET_NOT_ENTITLED", "value": { "error": { "code": "MARKET_NOT_ENTITLED", "message": "Your contract does not include United States (US) data. Markets on this account: KR. To add a market, contact help@alpsoft.io.", "docs": "https://openapi.chickstockfi.com/docs" } } } } } } }, "PlanRequiredOrFeatureDisabled": { "description": "Paid tier required (PLAN_REQUIRED) or discontinued (FEATURE_DISABLED — available only to keys under existing contracts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "FEATURE_DISABLED", "message": "Research endpoints are discontinued (still open only to keys under existing contracts). For revenue and operating income consensus, use /companies/{symbol}/consensus.", "docs": "https://openapi.chickstockfi.com/docs" } } } } }, "RateLimited": { "description": "Per-minute rate limit exceeded (RATE_LIMITED) or daily quota exceeded (QUOTA_EXCEEDED). Includes Retry-After (seconds)", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Per-minute request limit (6000) exceeded. Retry in 12 s.", "docs": "https://openapi.chickstockfi.com/docs" } } } } }, "RateLimitedOrAiQuota": { "description": "RATE_LIMITED, QUOTA_EXCEEDED, AI_QUOTA_EXCEEDED (next KST midnight), or AI_MONTHLY_QUOTA_EXCEEDED (next billing cycle or expiry). Retry-After is seconds until the relevant boundary.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-AI-Quota-Limit": { "$ref": "#/components/headers/X-AI-Quota-Limit" }, "X-AI-Quota-Remaining": { "$ref": "#/components/headers/X-AI-Quota-Remaining" }, "X-AI-Quota-Reset": { "$ref": "#/components/headers/X-AI-Quota-Reset" }, "X-AI-Quota-Monthly-Limit": { "$ref": "#/components/headers/X-AI-Quota-Monthly-Limit" }, "X-AI-Quota-Monthly-Remaining": { "$ref": "#/components/headers/X-AI-Quota-Monthly-Remaining" }, "X-AI-Quota-Monthly-Reset": { "$ref": "#/components/headers/X-AI-Quota-Monthly-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "AI_QUOTA_EXCEEDED", "message": "Daily AI call limit (20) reached. It resets at 00:00 Korea time (KST); regular data calls keep working. To raise the limit, contact help@alpsoft.io.", "docs": "https://openapi.chickstockfi.com/docs" } } } } }, "EdgeRateLimited": { "description": "Edge rate limit (per IP) exceeded — retry after a moment" }, "Internal": { "description": "Server error (INTERNAL)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL", "message": "Internal server error. Please retry shortly.", "docs": "https://openapi.chickstockfi.com/docs" } } } } }, "Unavailable": { "description": "Temporarily unable to generate (UNAVAILABLE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAVAILABLE", "message": "Data is temporarily unavailable. Please retry shortly.", "docs": "https://openapi.chickstockfi.com/docs" } } } } } }, "schemas": { "GlobalMacroChange": { "type": "object", "properties": { "value": { "type": [ "number", "null" ] }, "unit": { "type": "string", "enum": [ "bp", "%", "%p" ] }, "from": { "type": [ "string", "null" ], "format": "date" }, "to": { "type": "string", "format": "date" }, "unavailable_reason": { "type": [ "string", "null" ], "enum": [ null, "observation_missing", "history_missing", "basis_changed", "invalid_value", "non_trading_day", "source_unavailable" ] } }, "required": [ "value", "unit", "from", "to", "unavailable_reason" ], "additionalProperties": false }, "GlobalMacroFred": { "type": "object", "properties": { "data": { "type": "object", "properties": { "observation_date": { "type": "string", "format": "date" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "series_id": { "type": "string" }, "name": { "type": "string" }, "observation_date": { "type": [ "string", "null" ], "format": "date" }, "requested_date": { "type": "string", "format": "date" }, "value": { "type": [ "number", "null" ] }, "unit": { "type": "string", "enum": [ "%", "%p", "USD/barrel" ] }, "status": { "type": "string", "enum": [ "available", "unavailable" ] }, "unavailable_reason": { "type": [ "string", "null" ] }, "change_1d": { "$ref": "#/components/schemas/GlobalMacroChange" }, "change_5d": { "$ref": "#/components/schemas/GlobalMacroChange" }, "change_20d": { "$ref": "#/components/schemas/GlobalMacroChange" }, "note": { "type": [ "string", "null" ] }, "source": { "const": "FRED", "type": "string" }, "source_url": { "type": "string" } }, "required": [ "series_id", "name", "observation_date", "requested_date", "value", "unit", "status", "unavailable_reason", "change_1d", "change_5d", "change_20d", "note", "source", "source_url" ], "additionalProperties": false } }, "read_status": { "type": "string", "enum": [ "available", "unavailable" ] } }, "required": [ "observation_date", "rows", "read_status" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "market": { "const": "US", "type": "string" }, "observation_date": { "type": "string", "format": "date" }, "as_of": { "type": "string", "format": "date-time" } }, "required": [ "market", "observation_date", "as_of" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false }, "GlobalMacroSectors": { "type": "object", "properties": { "data": { "type": "object", "properties": { "observation_date": { "type": "string", "format": "date" }, "benchmark": { "type": "object", "properties": { "symbol": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string", "enum": [ "sector", "benchmark", "auxiliary" ] }, "observation_date": { "type": [ "string", "null" ], "format": "date" }, "requested_date": { "type": "string", "format": "date" }, "status": { "type": "string", "enum": [ "available", "unavailable" ] }, "return_1d": { "$ref": "#/components/schemas/GlobalMacroChange" }, "return_5d": { "$ref": "#/components/schemas/GlobalMacroChange" }, "return_20d": { "$ref": "#/components/schemas/GlobalMacroChange" }, "excess_5d": { "$ref": "#/components/schemas/GlobalMacroChange" }, "excess_20d": { "$ref": "#/components/schemas/GlobalMacroChange" }, "classification": { "type": "string", "enum": [ "persistent_outperformance", "short_term_recovery", "medium_term_strength_short_term_pullback", "no_relative_strength", "unavailable" ] }, "rank_20d": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 11 } }, "required": [ "symbol", "name", "role", "observation_date", "requested_date", "status", "return_1d", "return_5d", "return_20d", "excess_5d", "excess_20d", "classification", "rank_20d" ], "additionalProperties": false }, "auxiliary": { "type": "object", "properties": { "symbol": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string", "enum": [ "sector", "benchmark", "auxiliary" ] }, "observation_date": { "type": [ "string", "null" ], "format": "date" }, "requested_date": { "type": "string", "format": "date" }, "status": { "type": "string", "enum": [ "available", "unavailable" ] }, "return_1d": { "$ref": "#/components/schemas/GlobalMacroChange" }, "return_5d": { "$ref": "#/components/schemas/GlobalMacroChange" }, "return_20d": { "$ref": "#/components/schemas/GlobalMacroChange" }, "excess_5d": { "$ref": "#/components/schemas/GlobalMacroChange" }, "excess_20d": { "$ref": "#/components/schemas/GlobalMacroChange" }, "classification": { "type": "string", "enum": [ "persistent_outperformance", "short_term_recovery", "medium_term_strength_short_term_pullback", "no_relative_strength", "unavailable" ] }, "rank_20d": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 11 } }, "required": [ "symbol", "name", "role", "observation_date", "requested_date", "status", "return_1d", "return_5d", "return_20d", "excess_5d", "excess_20d", "classification", "rank_20d" ], "additionalProperties": false }, "sectors": { "type": "array", "items": { "type": "object", "properties": { "symbol": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string", "enum": [ "sector", "benchmark", "auxiliary" ] }, "observation_date": { "type": [ "string", "null" ], "format": "date" }, "requested_date": { "type": "string", "format": "date" }, "status": { "type": "string", "enum": [ "available", "unavailable" ] }, "return_1d": { "$ref": "#/components/schemas/GlobalMacroChange" }, "return_5d": { "$ref": "#/components/schemas/GlobalMacroChange" }, "return_20d": { "$ref": "#/components/schemas/GlobalMacroChange" }, "excess_5d": { "$ref": "#/components/schemas/GlobalMacroChange" }, "excess_20d": { "$ref": "#/components/schemas/GlobalMacroChange" }, "classification": { "type": "string", "enum": [ "persistent_outperformance", "short_term_recovery", "medium_term_strength_short_term_pullback", "no_relative_strength", "unavailable" ] }, "rank_20d": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 11 } }, "required": [ "symbol", "name", "role", "observation_date", "requested_date", "status", "return_1d", "return_5d", "return_20d", "excess_5d", "excess_20d", "classification", "rank_20d" ], "additionalProperties": false } }, "ranking_status": { "type": "string", "enum": [ "available", "unavailable" ] }, "top_3": { "type": "array", "items": { "type": "string" } }, "bottom_3": { "type": "array", "items": { "type": "string" } }, "return_basis": { "const": "adjusted_close_price_return", "type": "string" }, "source": { "const": "stored_us_daily", "type": "string" }, "read_status": { "type": "string", "enum": [ "available", "unavailable" ] } }, "required": [ "observation_date", "benchmark", "auxiliary", "sectors", "ranking_status", "top_3", "bottom_3", "return_basis", "source", "read_status" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "market": { "const": "US", "type": "string" }, "observation_date": { "type": "string", "format": "date" }, "as_of": { "type": "string", "format": "date-time" } }, "required": [ "market", "observation_date", "as_of" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "BAD_REQUEST", "BAD_SYMBOL", "BAD_PERIOD", "BAD_DATE", "BAD_ID", "BAD_QUERY", "UNSUPPORTED_MARKET", "MARKET_NOT_AVAILABLE", "BAD_CURSOR", "UNAUTHORIZED", "INVALID_KEY", "KEY_EXPIRED", "PLAN_REQUIRED", "POC_ENDED", "MARKET_NOT_ENTITLED", "READ_ONLY_KEY", "FEATURE_DISABLED", "SYMBOL_NOT_FOUND", "NOT_APPLICABLE", "NOT_FOUND", "NO_HISTORY", "RATE_LIMITED", "QUOTA_EXCEEDED", "AI_MONTHLY_QUOTA_EXCEEDED", "AI_QUOTA_EXCEEDED", "INTERNAL", "UNAVAILABLE" ], "description": "Error code — see the table below" }, "message": { "type": "string", "description": "Human-readable explanation (English). Branch on code — the wording may change" }, "docs": { "type": "string", "format": "uri", "description": "Documentation URL" }, "field": { "type": "string", "description": "The query parameter that failed validation (only when present)" }, "allowed": { "type": "array", "items": { "type": "string" }, "description": "Allowed values of a closed-set parameter, or the parameters this endpoint accepts when an unknown one was sent (only when present)" }, "reason": { "type": "string", "description": "Machine-readable reason (only when present) — e.g. delisted" }, "rejected_lines": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "market": { "type": "string", "enum": [ "KR", "US" ] } }, "required": [ "index", "market" ] }, "description": "/query all-unentitled rejection: zero-based line index and denied market" }, "entitled_markets": { "type": "array", "items": { "type": "string", "enum": [ "KR", "US" ] }, "description": "/query all-unentitled rejection: contract markets (may be empty)" } }, "required": [ "code", "message", "docs" ] } }, "required": [ "error" ] }, "ServiceDescriptor": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "description": { "type": "string", "description": "One-sentence introduction in English" }, "docs": { "type": "string", "format": "uri" }, "openapi": { "type": "string", "format": "uri" }, "servers": { "type": "array", "items": { "type": "string", "format": "uri" } }, "auth": { "type": "string" }, "key_info": { "type": "string", "description": "API key info endpoint" }, "endpoints": { "type": "array", "items": { "type": "string" } }, "mcp": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "auth": { "type": "string" }, "docs": { "type": "string", "format": "uri" }, "note": { "type": "string" } }, "description": "Remote MCP server — connect with the same Data API key (one tool call = one Data API request)" } } }, "KeyInfo": { "type": "object", "properties": { "data": { "type": "object", "properties": { "key": { "type": "object", "properties": { "id": { "type": "integer" }, "prefix": { "type": [ "string", "null" ], "description": "Display prefix (ck_live_ab12cd…; API docs session keys: ck_docs_…) — the full key is never returned" }, "name": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "kind": { "type": "string", "enum": [ "standard", "docs_session" ], "description": "docs_session = a short-lived read-only key issued to a signed-in account in the API docs (GET only, at most 60 minutes)" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Key expiry time — API docs session keys only (null for regular keys)" } } }, "plan": { "type": "string", "enum": [ "free", "poc", "launch", "business", "scale", "enterprise" ], "description": "Currently active plan (free once the term has ended)" }, "plan_tier": { "type": "string", "enum": [ "free", "launch", "business", "scale", "enterprise" ], "description": "Effective tier: PoC target (launch by default), otherwise the effective plan. Does not change plan or existing labels." }, "plan_label": { "type": "string", "enum": [ "Free", "PoC", "Launch", "Business", "Scale", "Enterprise" ] }, "starts_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Plan start time (PoC grant)" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Plan end time (null if indefinite)" }, "days_left": { "type": [ "integer", "null" ], "description": "Days remaining until the end (rounded up, D-n). Null if indefinite" }, "ended": { "type": [ "object", "null" ], "description": "For accounts whose term has ended, the ended plan and time", "properties": { "plan": { "type": "string", "enum": [ "poc", "launch", "business", "scale", "enterprise" ] }, "plan_label": { "type": "string", "enum": [ "PoC", "Launch", "Business", "Scale", "Enterprise" ] }, "plan_tier": { "type": "string", "enum": [ "launch", "business", "scale", "enterprise" ] }, "at": { "type": "string", "format": "date-time" } } }, "status": { "type": "string", "enum": [ "active", "poc_ended" ], "description": "If poc_ended, the PoC has ended, and every endpoint other than API key info returns 403 POC_ENDED for this key" }, "status_label": { "type": "string", "description": "Human-readable status (English — e.g. PoC, Enterprise, PoC ended)" }, "quota": { "type": "object", "properties": { "limit": { "type": "integer", "description": "Daily (KST) quota" }, "used": { "type": "integer" }, "remaining": { "type": "integer" }, "period": { "type": "string", "format": "date" }, "reset_at": { "type": "string", "format": "date-time" } } }, "ai_quota": { "type": [ "object", "null" ], "description": "Shared account AI quota. Null if uncapped. The optional monthly object appears only with a configured billing-cycle cap.", "properties": { "limit": { "type": [ "integer", "null" ] }, "used": { "type": "integer" }, "remaining": { "type": [ "integer", "null" ] }, "reset_at": { "type": "string", "format": "date-time" }, "monthly": { "type": "object", "properties": { "limit": { "type": "integer" }, "used": { "type": "integer" }, "remaining": { "type": "integer" }, "cycle_start": { "type": "string", "format": "date-time" }, "resets_at": { "type": "string", "format": "date-time" } }, "description": "Present only with a monthly cap. KST calendar billing cycle anchored to starts_at, clipped at expiry." } } }, "rate_limit": { "type": "object", "properties": { "per_minute": { "type": "integer", "description": "Per-minute rate limit (plan)" } } }, "markets": { "type": "array", "items": { "type": "string", "enum": [ "KR", "US" ] }, "description": "Markets this account has contracted (data coverage). Markets outside the contract return 403 MARKET_NOT_ENTITLED", "example": [ "KR", "US" ] }, "markets_available": { "type": "array", "items": { "type": "string", "enum": [ "KR", "US" ] }, "description": "Markets available to contract today", "example": [ "KR", "US" ] }, "markets_coming_soon": { "type": "array", "items": { "type": "string", "enum": [ "JP", "CN" ] }, "description": "Markets coming soon — requesting one returns 400 MARKET_NOT_AVAILABLE", "example": [ "JP", "CN" ] } } }, "meta": { "type": "object", "properties": { "as_of": { "type": "string", "format": "date-time" } } } } }, "Article": { "type": "object", "properties": { "id": { "type": "string", "example": "art_3f9k" }, "symbol": { "type": [ "string", "null" ], "example": "005930" }, "market": { "type": "string", "enum": [ "kr", "us" ], "description": "kr = Korean articles (in Korean); us = US articles (English-language articles from international media, press releases, SEC alerts)" }, "lang": { "type": "string", "enum": [ "ko", "en" ], "description": "Language of title" }, "title": { "type": "string", "description": "Original title" }, "title_ko": { "type": [ "string", "null" ], "description": "Korean title for US English-language articles (Phoenix AI translation; null if none). Null for Korean articles" }, "summary": { "type": [ "string", "null" ], "description": "Opening excerpt of the article (up to 140 characters). Full article text is not provided." }, "publisher": { "type": "string", "example": "연합뉴스", "description": "Publisher name. When a provider's name appears in the publisher field, it is shown as '해외 언론' (international media) for international articles or '뉴스' (news) for Korean articles" }, "published_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri", "description": "Link to the original article (/articles/{id}/read)" } }, "required": [ "id", "market", "lang", "title", "publisher", "published_at", "url" ] }, "SearchArticle": { "type": "object", "properties": { "id": { "type": "string", "example": "an_Q2xY" }, "market": { "type": "string", "enum": [ "KR" ], "description": "Present only in search results (not in briefing articles)" }, "title": { "type": "string" }, "summary": { "type": [ "string", "null" ], "description": "Opening excerpt of the article (up to 140 characters)" }, "publisher": { "type": "string" }, "published_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } } }, "Quote": { "type": "object", "properties": { "symbol": { "type": "string", "example": "005930" }, "name": { "type": [ "string", "null" ] }, "market": { "type": [ "string", "null" ] }, "currency": { "type": "string" }, "price": { "type": "object", "properties": { "current": { "type": "number" }, "open": { "type": [ "number", "null" ] }, "high": { "type": [ "number", "null" ] }, "low": { "type": [ "number", "null" ] }, "prev_close": { "type": [ "number", "null" ] }, "change": { "type": [ "number", "null" ] }, "change_rate": { "type": [ "number", "null" ], "description": "Change from the previous day as a decimal ratio (0.0101 = +1.01%)" }, "change_percent": { "type": [ "number", "null" ], "description": "Change in percent, rounded to two decimals; null when unavailable." }, "upper_limit": { "type": [ "number", "null" ] }, "lower_limit": { "type": [ "number", "null" ] } } }, "volume": { "type": "object", "properties": { "trade_value": { "type": [ "number", "null" ], "description": "Trading value (KRW)" }, "shares": { "type": [ "number", "null" ], "description": "Trading volume (shares)" } } }, "range_52w": { "type": "object", "properties": { "high": { "type": [ "number", "null" ] }, "high_date": { "type": [ "string", "null" ] }, "low": { "type": [ "number", "null" ] }, "low_date": { "type": [ "string", "null" ] } } }, "fundamentals": { "type": "object", "properties": { "market_cap": { "type": [ "number", "null" ], "description": "Market cap (KRW) — when data.valuation exists, its market cap (valuation.market_cap_raw)" }, "market_cap_rank": { "type": [ "number", "null" ] }, "per": { "type": [ "number", "null" ], "description": "Same value as data.valuation.per (null when absent)" }, "pbr": { "type": [ "number", "null" ], "description": "Same value as data.valuation.pbr" }, "eps": { "type": [ "number", "null" ], "description": "Same value as data.valuation.eps" }, "bps": { "type": [ "number", "null" ], "description": "Same value as data.valuation.bps" }, "dps": { "type": [ "number", "null" ], "description": "Same value as data.valuation.dividend.dps" }, "foreign_ratio": { "type": [ "number", "null" ], "description": "Foreign ownership (ratio — 0.4608 = 46.08%)" }, "debt_ratio": { "type": [ "number", "null" ], "description": "Ratio (0.311 = 31.1%)" }, "sales": { "type": [ "number", "null" ], "description": "Latest single quarter (KRW, no period label) — use /companies/{symbol}/financials" }, "operating_profit": { "type": [ "number", "null" ], "description": "Latest single quarter (KRW)" }, "net_income": { "type": [ "number", "null" ], "description": "Latest single quarter (KRW)" }, "listed_shares": { "type": [ "number", "null" ] } } }, "sector": { "type": [ "string", "null" ] }, "company_summary": { "type": [ "string", "null" ] }, "market_status": { "type": [ "string", "null" ], "description": "HALTED takes precedence. KRX weekends, holidays and hours outside 08:00–20:00 KST report CLOSED rather than a cached session. During trading-day hours, the stored provider session applies; see quote_detail_as_of." }, "as_of": { "type": "string", "format": "date-time" }, "detail_status": { "type": "string", "enum": [ "fresh", "stale", "detail_unavailable" ], "description": "Detail cache: fresh for 45 seconds after retrieval; stale on refresh failure only until total retrieval age reaches 5 minutes. Stored prices remain authoritative." }, "detail_reason": { "type": [ "string", "null" ], "enum": [ "detail_unavailable", "stale", null ], "description": "Reason for unavailable (null) or stale detail fields; independent of price availability." }, "detail_as_of": { "type": [ "string", "null" ], "format": "date-time", "description": "Observation time of detail fields; null when detail is unavailable." }, "detail_fetched_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Last successful detail retrieval. Stale fallback does not renew this time." }, "data": { "$ref": "#/components/schemas/QuoteData" }, "meta": { "type": "object", "properties": { "quote_detail_as_of": { "type": [ "string", "null" ], "format": "date-time" }, "price_note": { "type": "string" }, "symbol": { "type": "string" }, "market": { "type": "string", "enum": [ "KR" ] }, "as_of": { "type": "string", "format": "date-time" }, "legacy_top_level": { "type": "boolean" }, "valuation_note": { "type": "string" }, "legacy_note": { "type": "string" }, "trade_date_note": { "type": "string" }, "trade_evidence_reason": { "type": "string", "enum": [ "trade_evidence_unavailable" ] }, "issuer_symbol": { "type": "string", "example": "005930", "description": "Symbol whose company-level data (filings, ownership, insiders, treasury stock, financials, consensus …) was read — for Korean preferred shares (e.g. 005935, 005385, 000815) the issuer's common share (005930, 005380, 000810); otherwise the requested symbol" }, "share_class": { "type": [ "string", "null" ], "enum": [ "common", "preferred", null ], "description": "Korean share class — common or preferred. Null for US symbols (not determined)" }, "issuer_note": { "type": "string", "description": "Preferred shares only — note that company-level data is the issuer's" } } } }, "description": "The standard shape is data + meta. Top-level fields (symbol, price, fundamentals …) are kept for legacy clients (deprecated) — per, pbr, eps, bps and dps in fundamentals are the same values as data.valuation (from 2026-10-21; null when absent), market_cap is in KRW, debt_ratio is a ratio (0.311 = 31.1%), and sales, operating_profit and net_income are latest-quarter values." }, "KrSymbol": { "type": "object", "properties": { "symbol": { "type": "string", "example": "005930", "description": "Korean 6-character symbol code (including the new alphanumeric codes)" }, "market": { "type": "string", "enum": [ "KR" ] }, "exchange": { "type": [ "string", "null" ], "description": "Listing market — KOSPI · KOSDAQ" }, "name_ko": { "type": "string", "description": "Korean name" }, "name_en": { "type": [ "string", "null" ], "description": "English company name (the company's registered English name, cleaned up for display). null if none — usually null for ETFs and ETNs" }, "type": { "type": "string", "enum": [ "stock", "etf", "etn", "other" ], "description": "Security type — stock · etf · etn · other" }, "security_subtype": { "type": [ "string", "null" ], "enum": [ "common", "preferred", "reit", "spac", "etf", "etn", "fund", "depositary_receipt", "other", null ], "description": "Detailed security type from official master attributes, or null when unconfirmed." }, "security_subtype_reason": { "type": [ "string", "null" ], "enum": [ "master_subtype_unavailable", null ] }, "type_reason": { "type": [ "string", "null" ], "enum": [ "master_type_unavailable", "master_type_unsupported", null ] }, "listing_status": { "type": [ "string", "null" ], "enum": [ "listed", "suspended", "delisting", "inactive", "delisted", null ], "description": "Same listing state as status." }, "delisted_on": { "type": [ "string", "null" ], "format": "date", "description": "Confirmed delisting date, or null when unconfirmed." }, "delisted_on_reason": { "type": [ "string", "null" ], "enum": [ "reference_schema_unavailable", "delisting_date_unconfirmed", null ] }, "sector": { "type": [ "string", "null" ], "description": "Sector (Korean label). null if unknown" }, "sector_en": { "type": [ "string", "null" ], "description": "Sector in English. null if unknown" }, "status": { "type": [ "string", "null" ], "enum": [ "listed", "suspended", "delisting", "inactive", "delisted", null ], "description": "Listing status. delisted has verified delisting evidence; inactive only lacks recent trades." }, "listed_date": { "type": [ "string", "null" ], "format": "date", "description": "Listing date. null if unknown" }, "halt_notice_date": { "type": [ "string", "null" ], "format": "date" }, "halted_on": { "type": [ "string", "null" ], "format": "date", "description": "Confirmed effective halt date (null when unconfirmed)" }, "last_trade_date": { "type": [ "string", "null" ], "format": "date", "description": "Latest positive-volume trade date, including newer intraday observations" } }, "required": [ "symbol", "market", "exchange", "name_ko", "name_en", "type", "sector", "sector_en", "status", "listed_date", "last_trade_date" ] }, "KrDailyClose": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "description": "Trading date (Korea)" }, "close": { "type": "number", "description": "Official regular-session close (KRW)" }, "change_pct": { "type": [ "number", "null" ], "description": "Change (%, 1.07 = +1.07%)" }, "volume": { "type": [ "number", "null" ], "description": "Trading volume (shares)" }, "trade_value": { "type": [ "number", "null" ], "description": "Trading value (KRW)" }, "market_cap": { "type": [ "number", "null" ], "description": "Market capitalisation (KRW). null if not stored" }, "listed_shares": { "type": [ "number", "null" ], "description": "Listed shares. null if not stored" }, "price_adjustment": { "type": "string", "enum": [ "none", "adjusted" ], "description": "none = value as published that day (no retroactive adjustment) · adjusted = a fund-type product missing from the exchange's stock batch, filled from a secondary daily series (split-adjusted; change computed from consecutive closes)" } }, "required": [ "date", "close", "change_pct", "volume", "trade_value", "market_cap", "listed_shares", "price_adjustment" ] }, "KrSplitEvent": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "description": "Relisting date (Korean trading day)" }, "kind": { "type": "string", "description": "split · reverse (consolidation or capital reduction) · unknown" }, "share_ratio": { "type": "number", "description": "New shares ÷ old shares (multiply holdings by this)" }, "price_ratio": { "type": [ "number", "null" ], "description": "Factor by which the exchange adjusted the base price. null if unknown" }, "confidence": { "type": "string", "description": "high · medium · low" }, "date_precision": { "type": "string", "description": "day = exact date known · quarter = known only to the quarter" } } }, "QuoteData": { "type": "object", "properties": { "symbol": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "market": { "type": "string", "enum": [ "KR" ] }, "exchange": { "type": [ "string", "null" ], "example": "KOSPI" }, "currency": { "type": "string" }, "price": { "type": "object", "properties": { "current": { "type": "number" }, "open": { "type": [ "number", "null" ] }, "high": { "type": [ "number", "null" ] }, "low": { "type": [ "number", "null" ] }, "prev_close": { "type": [ "number", "null" ] }, "change": { "type": [ "number", "null" ] }, "change_rate": { "type": [ "number", "null" ], "description": "Change from the previous day as a decimal ratio (0.0101 = +1.01%)" }, "change_percent": { "type": [ "number", "null" ], "description": "Change in percent, rounded to two decimals; null when unavailable." }, "upper_limit": { "type": [ "number", "null" ] }, "lower_limit": { "type": [ "number", "null" ] } } }, "volume": { "type": "object", "properties": { "trade_value": { "type": [ "number", "null" ], "description": "Trading value (KRW)" }, "shares": { "type": [ "number", "null" ], "description": "Trading volume (shares)" } } }, "range_52w": { "type": "object", "properties": { "high": { "type": [ "number", "null" ] }, "high_date": { "type": [ "string", "null" ] }, "low": { "type": [ "number", "null" ] }, "low_date": { "type": [ "string", "null" ] } } }, "detail_status": { "type": "string", "enum": [ "fresh", "stale", "detail_unavailable" ], "description": "Detail cache: fresh for 45 seconds after retrieval; stale on refresh failure only until total retrieval age reaches 5 minutes. Stored prices remain authoritative." }, "detail_reason": { "type": [ "string", "null" ], "enum": [ "detail_unavailable", "stale", null ], "description": "Reason for unavailable (null) or stale detail fields; independent of price availability." }, "detail_as_of": { "type": [ "string", "null" ], "format": "date-time", "description": "Observation time of detail fields; null when detail is unavailable." }, "detail_fetched_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Last successful detail retrieval. Stale fallback does not renew this time." }, "valuation": { "oneOf": [ { "$ref": "#/components/schemas/Valuation" }, { "type": "null" } ], "description": "Same value as valuation in /companies/{symbol}/metrics (same function, same cache — basis fields price_as_of, eps_period, shares_basis, per_basis)" }, "fundamentals": { "type": "object", "properties": { "foreign_ratio_pct": { "type": [ "number", "null" ], "description": "Foreign ownership (%, 46.08 = 46.08%) — the legacy top-level fundamentals.foreign_ratio (ratio 0.4608) × 100" }, "listed_shares": { "type": [ "number", "null" ] }, "market_cap_rank": { "type": [ "number", "null" ] } }, "description": "Not-applicable values that arrive as 0 are null" }, "sector": { "type": [ "string", "null" ] }, "market_status": { "type": [ "string", "null" ], "description": "HALTED takes precedence. KRX weekends, holidays and hours outside 08:00–20:00 KST report CLOSED rather than a cached session. During trading-day hours, the stored provider session applies; see quote_detail_as_of." }, "status": { "$ref": "#/components/schemas/KrListingStatus" }, "as_of": { "type": "string", "format": "date-time" } } }, "KrListingStatus": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "listed", "suspended", "delisting", "inactive", "delisted", "unknown" ], "description": "Listing status (the same decision as the company meta.listing_status and /symbols) — listed (in the latest trading-day ledger) · suspended (trading halt reported) · delisting (liquidation trading) · delisted (delisting with DART evidence) · inactive (only old trades and no evidence — not asserted as delisted) · unknown (no evidence)" }, "delisted_on": { "type": [ "string", "null" ], "format": "date", "description": "Confirmed delisting date only; null when unconfirmed. See listing_evidence." }, "listing_evidence": { "type": "object", "properties": { "source": { "type": "string" }, "date_kind": { "type": "string" }, "observed_on": { "type": [ "string", "null" ] }, "window_from": { "type": [ "string", "null" ] }, "window_to": { "type": [ "string", "null" ] }, "note": { "type": "string" } }, "description": "Bounded scan evidence, not a confirmed delisting date." }, "last_trading_day": { "type": [ "string", "null" ], "format": "date", "description": "Latest positive-volume trade date, including newer intraday observations" }, "trading_halted": { "type": [ "boolean", "null" ], "description": "Whether trading is halted (as reported). null when unknown" }, "halt_reason": { "type": [ "string", "null" ], "description": "When halted, the title of the latest trading-halt notice filing (verbatim, in Korean). null otherwise" }, "halt_notice_date": { "type": [ "string", "null" ], "format": "date", "description": "Filing date of the halt_reason notice" }, "trade_evidence_reason": { "type": "string", "enum": [ "trade_evidence_unavailable" ] }, "halted_on": { "type": [ "string", "null" ], "format": "date", "description": "Confirmed effective halt date (null when unconfirmed)" }, "designations": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "administrative_issue", "investment_caution", "investment_warning", "investment_risk", "short_term_overheat_notice", "short_term_overheat", "short_term_overheat_extended", "investment_caution_reminder" ] }, "label": { "type": "string", "description": "Exchange label (Korean)" } } }, "description": "Exchange designations — administrative issue, investment caution / warning / risk, short-term overheating, investment caution reminder. Empty when none (empty for a delisted company)" }, "as_of": { "type": [ "string", "null" ], "format": "date-time", "description": "As-of time of the status evidence (the most recently refreshed source)" } }, "description": "Listing and trading status — decided only from stored exchange flags, reference data and filings (no external lookup per request; cached for up to one minute). Designations are the exchange's own flags, not a Phoenix AI judgement." }, "Briefing": { "type": "object", "properties": { "symbol": { "type": "string" }, "name": { "type": "string" }, "market": { "type": "string", "example": "KOSPI" }, "date": { "type": "string", "format": "date", "description": "Regular-session trading day covered by the briefing. Today during the regular session; otherwise the date of the most recently completed regular session" }, "session": { "type": "string", "enum": [ "closed", "intraday" ], "description": "closed = outside the regular session (final); intraday = during the regular session (provisional)" }, "price": { "type": "object", "properties": { "current": { "type": [ "number", "null" ] }, "change": { "type": [ "number", "null" ] }, "change_rate": { "type": [ "number", "null" ], "description": "Decimal ratio (0.0101 = +1.01%)" }, "open": { "type": [ "number", "null" ] }, "high": { "type": [ "number", "null" ] }, "low": { "type": [ "number", "null" ] }, "prev_close": { "type": [ "number", "null" ] }, "as_of": { "type": "string", "format": "date-time" } }, "description": "Values that could not be confirmed are null (not filled with 0)" }, "summary": { "type": "string", "description": "The first sentence covers the session and price, followed by a summary of key issues" }, "briefing": { "type": "object", "properties": { "key_issues": { "type": "array", "items": { "type": "string" } }, "body": { "type": "string" } } }, "articles": { "type": "array", "items": { "$ref": "#/components/schemas/SearchArticle" } }, "data": { "$ref": "#/components/schemas/BriefingData" }, "meta": { "type": "object", "properties": { "tone": { "type": "string", "enum": [ "formal" ] }, "tone_quoted_sentences": { "type": "integer", "description": "Number of sentences or fragments preserved as quotations because no deterministic formal conversion was available" }, "source": { "type": "string", "enum": [ "cache", "fresh" ] }, "session": { "type": "string", "enum": [ "closed", "intraday" ] }, "generated_at": { "type": [ "string", "null" ], "format": "date-time" }, "briefing_date": { "type": "string", "format": "date", "description": "The requested (stored) briefing date — Korea time" }, "as_of": { "type": "string", "format": "date-time" }, "legacy_top_level": { "type": "boolean", "description": "true — the top-level fields are kept for compatibility (deprecated)" }, "legacy_note": { "type": "string" }, "fresh_available_in_sec": { "type": "integer", "description": "When fresh=true was requested but a stored copy was returned because of the cooldown, the seconds remaining until the next regeneration" }, "fresh_ignored": { "type": "boolean", "description": "true only when fresh=true was sent with a past date and ignored (past briefings are never regenerated)" } } } }, "description": "The standard shape is data + meta. The top-level fields (symbol, market = KOSPI/KOSDAQ, date, price, ...) are kept for compatibility (deprecated) with unchanged values." }, "BriefingData": { "type": "object", "properties": { "symbol": { "type": "string" }, "name": { "type": "string" }, "market": { "type": "string", "enum": [ "KR" ] }, "exchange": { "type": [ "string", "null" ], "enum": [ "KOSPI", "KOSDAQ", null ], "description": "Exchange" }, "briefing_date": { "type": "string", "format": "date", "description": "The requested (stored) briefing date — Korea time. It can differ from date (a briefing written before the open covers the previous trading day)" }, "date": { "type": "string", "format": "date", "description": "The regular-session trading day the briefing covers: today during the regular session, otherwise the last completed regular session (for past dates, as of when that briefing was written)" }, "session": { "type": "string", "enum": [ "closed", "intraday" ], "description": "closed = outside the regular session (final), intraday = during the regular session (provisional). For past dates, the session when it was written" }, "price": { "type": "object", "properties": { "current": { "type": [ "number", "null" ] }, "change": { "type": [ "number", "null" ] }, "change_rate": { "type": [ "number", "null" ], "description": "Decimal ratio (0.0101 = +1.01%)" }, "open": { "type": [ "number", "null" ] }, "high": { "type": [ "number", "null" ] }, "low": { "type": [ "number", "null" ] }, "prev_close": { "type": [ "number", "null" ] }, "as_of": { "type": "string" } }, "description": "Today: the current reference price. Past dates: the price stored when the briefing was written. Unverified values are null" }, "summary": { "type": "string" }, "briefing": { "type": "object", "properties": { "key_issues": { "type": "array", "items": { "type": "string" } }, "body": { "type": "string" } } }, "articles": { "type": "array", "items": { "$ref": "#/components/schemas/SearchArticle" } }, "generated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the briefing was written" } } }, "Disclosure": { "type": "object", "properties": { "id": { "type": "string", "description": "DART receipt number (rcept_no, 14 digits)" }, "market": { "type": "string", "enum": [ "KR" ] }, "symbol": { "type": "string" }, "title": { "type": "string", "description": "Report name" }, "filer": { "type": "string", "description": "Filer" }, "published_at": { "type": "string", "format": "date", "description": "Filing date (YYYY-MM-DD) — no time" }, "rcept_no": { "type": "string", "description": "DART receipt number (= id) — the same name as in /companies/{symbol}/disclosures" }, "filed_date": { "type": "string", "format": "date", "description": "Filing date (= published_at) — the same name as in /companies/{symbol}/disclosures" }, "url": { "type": "string", "format": "uri", "description": "Official DART viewer" } } }, "DisclosureDetail": { "type": "object", "properties": { "id": { "type": "string" }, "market": { "type": "string", "enum": [ "KR" ] }, "text": { "type": "string", "description": "Extracted plain-text body" }, "length": { "type": "integer", "description": "Body length (characters)" }, "url": { "type": "string", "format": "uri" }, "data": { "$ref": "#/components/schemas/DisclosureDetailData" }, "meta": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "DART" ] }, "as_of": { "type": "string", "format": "date-time" }, "note": { "type": "string" } } } }, "description": "The standard shape is data + meta. The top-level id, market, text, length and url stay for backward compatibility." }, "DisclosureDetailData": { "type": "object", "properties": { "id": { "type": "string" }, "market": { "type": "string", "enum": [ "KR" ] }, "text": { "type": "string", "description": "Extracted plain-text body (at most 50,000 characters)" }, "length": { "type": "integer", "description": "Body length (characters) — after truncation" }, "truncated": { "type": "boolean", "description": "Whether text was cut because the source is longer than 50,000 characters — use format=raw or url for the full document" }, "full_length": { "type": [ "integer", "null" ], "description": "Plain-text length before truncation (when known, otherwise null)" }, "text_available": { "type": "boolean", "description": "false means this filing has no extractable text (ownership reports, forms filed directly with the exchange, ...) — open the official viewer at url" }, "url": { "type": "string", "format": "uri" } } }, "DisclosureSummary": { "type": "object", "properties": { "id": { "type": "string" }, "market": { "type": "string", "enum": [ "KR" ] }, "symbol": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "filer": { "type": [ "string", "null" ] }, "published_at": { "type": [ "string", "null" ] }, "headline": { "type": "string", "description": "One sentence describing what this filing is" }, "category": { "type": "string" }, "figures": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "string" } } }, "description": "Key figures stated in the source document" }, "key_facts": { "type": "array", "items": { "type": "string" } }, "plain": { "type": "string", "description": "Plain explanation in 2–3 sentences" }, "source": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } } }, "summary_available": { "type": "boolean", "description": "If false, the response provides a link to the source document instead of a summary" }, "note": { "type": "string" }, "withheld": { "type": "string", "enum": [ "amount_check" ], "description": "Summary with figures omitted because they did not pass amount reconciliation" }, "generated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "IrCalendarItem": { "type": "object", "properties": { "id": { "type": "string" }, "market": { "type": "string", "enum": [ "KR" ] }, "symbol": { "type": [ "string", "null" ] }, "company": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "place": { "type": [ "string", "null" ] }, "date": { "type": "string", "format": "date" }, "time": { "type": [ "string", "null" ], "description": "HH:MM (null if not yet set)" }, "material_id": { "type": [ "string", "null" ], "description": "Id of the presentation material attached to this event (null if none)" }, "materialId": { "type": [ "string", "null" ], "description": "Deprecated old name — same value as material_id", "deprecated": true } } }, "IrMaterialItem": { "type": "object", "properties": { "id": { "type": "string" }, "market": { "type": "string", "enum": [ "KR" ] }, "symbol": { "type": [ "string", "null" ] }, "company": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "date": { "type": "string", "format": "date", "description": "Publication date" }, "download_url": { "type": [ "string", "null" ], "format": "uri", "description": "Company IR presentation file — only archived copies held by Phoenix AI (null if none)" }, "view_url": { "type": [ "string", "null" ], "format": "uri", "description": "Reading viewer — archived copies only (null if none)" } } }, "IpoOffering": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique id of the offering — unchanged by amended filings (schedule changes) and company renames" }, "market": { "type": "string", "enum": [ "KR" ] }, "symbol": { "type": [ "string", "null" ], "description": "Stock code verified against the issuer ID, listed-security master and listing date. Null before listing, when uncertain, or when duplicated across offerings." }, "company": { "type": "string" }, "symbol_reason": { "type": [ "string", "null" ], "enum": [ "issuer_not_found", "issuer_ambiguous", "issuer_conflict", "issuer_name_conflict", "master_not_found", "master_conflict", "listing_date_missing", "listing_date_mismatch", "not_yet_listed", "duplicate_offering_symbol", "superseded", "mapping_unavailable", null ], "description": "symbol_reason is one of: listing_date_missing — no valid event listing date; not_yet_listed — event date is after today in Korea (checked before issuer lookup); issuer_not_found — issuer cannot be established; issuer_ambiguous — multiple issuer or code candidates; issuer_conflict — event name/link conflicts with the code owner; issuer_name_conflict — name candidates conflict but code/ownership validation succeeds and symbol is retained; master_not_found — no verifiable master candidate; master_conflict — inconsistent code ownership across masters; listing_date_mismatch — invalid master date or conflict with the event; duplicate_offering_symbol — multiple offerings claim a code without verified transfer history; superseded — replaced historical row; mapping_unavailable — mapping could not be read or resolved. Null means success without an additional reason. All non-null reasons except issuer_name_conflict imply symbol=null. A linked listing reuses its resolution; conflicting/multiple links, superseded rows and duplicates can take precedence over the date decision. Listing day itself is not future: missing evidence returns its actual failure reason, such as master_not_found." }, "exchange": { "type": [ "string", "null" ], "enum": [ "KOSPI", "KOSDAQ", "KONEX", null ], "description": "Listing market" }, "is_spac": { "type": "boolean", "description": "Whether it is a SPAC (special purpose acquisition company) — judged from the company name" }, "filing_date": { "type": [ "string", "null" ], "format": "date", "description": "Registration statement filing date (the amendment date for an amended filing)" }, "demand_from": { "type": [ "string", "null" ], "format": "date" }, "demand_to": { "type": [ "string", "null" ], "format": "date" }, "subscribe_from": { "type": [ "string", "null" ], "format": "date" }, "subscribe_to": { "type": [ "string", "null" ], "format": "date" }, "payment_date": { "type": [ "string", "null" ], "format": "date" }, "price_low": { "type": [ "integer", "null" ], "description": "Lower bound of the indicative offering price range (KRW). Always price_low ≤ price_high. Null for offerings not yet read from the source" }, "price_high": { "type": [ "integer", "null" ], "description": "Upper bound of the indicative offering price range (KRW). SPACs usually have a fixed price equal to the lower bound (2,000)" }, "offer_price": { "type": [ "integer", "null" ], "description": "Final offer price (KRW) — null before book-building" }, "offer_amount": { "type": [ "integer", "null" ], "description": "Offering amount (KRW) — null until priced" }, "offer_shares": { "type": [ "integer", "null" ], "description": "Number of shares offered — null if unknown" }, "offer_price_vs_band": { "type": [ "string", "null" ], "enum": [ "above", "within", "below", null ], "description": "Where the final offer price sits relative to the indicative range — above, within or below (only when both exist)" }, "quality_flags": { "type": "array", "items": { "type": "string", "enum": [ "band_reversed_in_source" ] }, "description": "Source quality flags — band_reversed_in_source = the source listed the lower bound above the upper bound and we corrected it. Empty array if none" }, "expected_listing_date": { "type": [ "string", "null" ], "format": "date" }, "underwriters": { "type": [ "string", "null" ] } } }, "IpoListing": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique id of the listing" }, "market": { "type": "string", "enum": [ "KR" ] }, "symbol": { "type": [ "string", "null" ], "description": "Stock code verified against the issuer ID, listed-security master and listing date. Null when unconfirmed." }, "company": { "type": "string" }, "symbol_reason": { "type": [ "string", "null" ], "enum": [ "issuer_not_found", "issuer_ambiguous", "issuer_conflict", "issuer_name_conflict", "master_not_found", "master_conflict", "listing_date_missing", "listing_date_mismatch", "not_yet_listed", "duplicate_offering_symbol", "superseded", "mapping_unavailable", null ], "description": "symbol_reason is one of: listing_date_missing — no valid event listing date; not_yet_listed — event date is after today in Korea (checked before issuer lookup); issuer_not_found — issuer cannot be established; issuer_ambiguous — multiple issuer or code candidates; issuer_conflict — event name/link conflicts with the code owner; issuer_name_conflict — name candidates conflict but code/ownership validation succeeds and symbol is retained; master_not_found — no verifiable master candidate; master_conflict — inconsistent code ownership across masters; listing_date_mismatch — invalid master date or conflict with the event; duplicate_offering_symbol — multiple offerings claim a code without verified transfer history; superseded — replaced historical row; mapping_unavailable — mapping could not be read or resolved. Null means success without an additional reason. All non-null reasons except issuer_name_conflict imply symbol=null. A linked listing reuses its resolution; conflicting/multiple links, superseded rows and duplicates can take precedence over the date decision. Listing day itself is not future: missing evidence returns its actual failure reason, such as master_not_found." }, "exchange": { "type": [ "string", "null" ], "enum": [ "KOSPI", "KOSDAQ", "KONEX", null ], "description": "Listing market" }, "is_spac": { "type": "boolean", "description": "Whether it is a SPAC (special purpose acquisition company) — judged from the company name" }, "listing_date": { "type": "string", "format": "date" }, "list_type": { "type": [ "string", "null" ] }, "security_type": { "type": [ "string", "null" ], "description": "Security type (shares, REIT, etc.)" }, "industry": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "underwriters": { "type": [ "string", "null" ] } } }, "MajorHolder": { "type": "object", "properties": { "market": { "type": "string", "enum": [ "KR" ] }, "report_date": { "type": [ "string", "null" ], "format": "date" }, "reporter": { "type": [ "string", "null" ] }, "report_type": { "type": [ "string", "null" ] }, "reason": { "type": [ "string", "null" ] }, "holding_qty": { "type": [ "number", "null" ] }, "holding_qty_change": { "type": [ "number", "null" ] }, "holding_rate": { "type": [ "number", "null" ], "description": "Ownership ratio (%)" }, "holding_rate_change": { "type": [ "number", "null" ], "description": "%p" }, "url": { "type": [ "string", "null" ], "format": "uri" }, "rcept_no": { "type": [ "string", "null" ] } } }, "InsiderTrade": { "type": "object", "properties": { "market": { "type": "string", "enum": [ "KR" ] }, "report_date": { "type": [ "string", "null" ], "format": "date" }, "reporter": { "type": [ "string", "null" ] }, "is_registered_officer": { "type": [ "string", "null" ] }, "position": { "type": [ "string", "null" ] }, "is_major_shareholder": { "type": [ "string", "null" ] }, "owned_qty": { "type": [ "number", "null" ] }, "owned_qty_change": { "type": [ "number", "null" ] }, "url": { "type": [ "string", "null" ], "format": "uri" }, "rcept_no": { "type": [ "string", "null" ] }, "owned_rate": { "type": [ "number", "null" ], "description": "Ownership ratio after the report (%)" }, "owned_rate_change": { "type": [ "number", "null" ], "description": "%p" }, "is_new_report": { "type": "boolean", "description": "If true, the change is an initial report (new appointment or inclusion), not a trade" } } }, "DividendItem": { "type": "object", "properties": { "market": { "type": "string", "enum": [ "KR" ] }, "item": { "type": [ "string", "null" ], "description": "Item — the unit is included in the item name (e.g. '주당 현금배당금(원)' (cash dividend per share, KRW), '현금배당성향(%)' (cash dividend payout ratio, %), '(연결)당기순이익(백만원)' (consolidated net income, KRW million))" }, "stock_kind": { "type": [ "string", "null" ], "description": "Common or preferred stock (applicable items only)" }, "this_term": { "type": [ "string", "null" ], "description": "Current-period value — string exactly as written in the filing (e.g. \"1,444\"); null if absent" }, "prev_term": { "type": [ "string", "null" ], "description": "Prior-period value (string)" }, "prev2_term": { "type": [ "string", "null" ], "description": "Value for two periods prior (string)" }, "settle_date": { "type": [ "string", "null" ], "format": "date", "description": "Settlement date" }, "rcept_no": { "type": [ "string", "null" ], "description": "Annual report receipt number" } } }, "TreasuryItem": { "type": "object", "properties": { "market": { "type": "string", "enum": [ "KR" ] }, "acquisition_method": { "type": [ "string", "null" ] }, "stock_kind": { "type": [ "string", "null" ] }, "begin_qty": { "type": [ "number", "null" ] }, "acquired_qty": { "type": [ "number", "null" ] }, "disposed_qty": { "type": [ "number", "null" ] }, "cancelled_qty": { "type": [ "number", "null" ], "description": "Quantity retired" }, "end_qty": { "type": [ "number", "null" ] }, "row_kind": { "type": "string", "enum": [ "total", "subtotal", "detail" ], "description": "total = total; subtotal = subtotal by acquisition method; detail = individual acquisition method. The default response includes only total (detail=1 returns all rows — summing them counts the same quantity multiple times, so filter by row_kind)" }, "settle_date": { "type": [ "string", "null" ], "format": "date" }, "rcept_no": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] } } }, "EmployeeItem": { "type": "object", "properties": { "market": { "type": "string", "enum": [ "KR" ] }, "row_kind": { "type": "string", "enum": [ "detail", "total" ], "description": "detail identifies a component row; total identifies an aggregate or subtotal. Adding both double-counts employees." }, "division": { "type": [ "string", "null" ] }, "gender": { "type": [ "string", "null" ] }, "regular_count": { "type": [ "number", "null" ] }, "contract_count": { "type": [ "number", "null" ] }, "total_count": { "type": [ "number", "null" ] }, "avg_service_years": { "type": [ "number", "null" ] }, "annual_salary_total": { "type": [ "number", "null" ], "description": "Total annual salary (KRW)" }, "avg_salary_per_person": { "type": [ "number", "null" ], "description": "Average salary per employee (KRW)" } } }, "CreditRatingItem": { "type": "object", "properties": { "market": { "type": "string", "enum": [ "KR" ] }, "date": { "type": [ "string", "null" ], "format": "date" }, "title": { "type": "string" }, "filer": { "type": [ "string", "null" ] }, "grade": { "type": [ "string", "null" ], "description": "Normalized grade (AA0 becomes AA; +/- are preserved)" }, "grade_raw": { "type": [ "string", "null" ], "description": "Original grade as stated in the filing" }, "instrument_type": { "type": [ "string", "null" ], "enum": [ "senior", "hybrid", "contingent_capital", null ], "description": "Senior, hybrid or contingent capital instrument explicitly identified next to the rating. Null if unclear or multiple types are present. The rating may not be an issuer-wide rating." }, "outlook": { "type": [ "string", "null" ] }, "agencies": { "type": "array", "items": { "type": "string" } }, "url": { "type": [ "string", "null" ], "format": "uri" } } }, "CorporateAction": { "type": "object", "properties": { "market": { "type": "string", "enum": [ "KR" ] }, "date": { "type": [ "string", "null" ], "format": "date" }, "symbol": { "type": [ "string", "null" ] }, "company": { "type": [ "string", "null" ] }, "type": { "type": "string" }, "title": { "type": "string" }, "filer": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ], "format": "uri", "description": "Null for missing official links and IR rows whose source link is withheld; never an empty string" } } }, "DartEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Receipt number" }, "market": { "type": "string", "enum": [ "KR" ] }, "date": { "type": "string", "format": "date" }, "at": { "type": [ "string", "null" ], "format": "date-time", "description": "Filing time (null if unavailable)" }, "symbol": { "type": [ "string", "null" ] }, "company": { "type": [ "string", "null" ] }, "category": { "type": "string" }, "group": { "type": "string", "enum": [ "corporate_action", "ownership", "bond", "earnings", "distress", "other" ] }, "title": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ], "format": "uri" } } }, "ClinicalTrial": { "type": "object", "properties": { "nct_id": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "phase": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "conditions": { "type": "array", "items": { "type": "string" } }, "sponsor": { "type": [ "string", "null" ] }, "start_date": { "type": [ "string", "null" ] }, "completion_date": { "type": [ "string", "null" ] }, "last_update": { "type": [ "string", "null" ] }, "url": { "type": "string", "format": "uri" } } }, "EconEvent": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "market": { "type": "string", "enum": [ "KR" ] }, "date": { "type": "string", "format": "date" }, "time": { "type": [ "string", "null" ] }, "event": { "type": "string" }, "category": { "type": [ "string", "null" ] }, "importance": { "type": [ "string", "null" ], "enum": [ "high", "med", "low", null ] }, "agency": { "type": [ "string", "null" ] }, "stage": { "type": [ "string", "null" ], "description": "scheduled; preliminary (provisional); final (confirmed)" } } }, "UsEconEvent": { "type": "object", "properties": { "id": { "type": "string" }, "market": { "type": "string", "enum": [ "US" ] }, "category": { "type": "string", "enum": [ "economic", "fda", "commodity" ] }, "date": { "type": "string", "format": "date" }, "time": { "type": [ "string", "null" ] }, "title": { "type": "string" }, "title_en": { "type": [ "string", "null" ] }, "importance": { "type": "integer", "description": "3 = high; 2 = medium; 1 = low" }, "country": { "type": [ "string", "null" ] }, "ticker": { "type": [ "string", "null" ] }, "actual": { "type": [ "string", "null" ] }, "consensus": { "type": [ "string", "null" ], "description": "Forecast before the release" }, "prior": { "type": [ "string", "null" ] }, "unit": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] } } }, "EarningsItem": { "type": "object", "properties": { "ticker": { "type": "string", "example": "NKE" }, "market": { "type": "string", "enum": [ "US" ] }, "report_date": { "type": "string", "format": "date", "description": "Report date (US Eastern date)" }, "reportDate": { "type": "string", "format": "date", "description": "Deprecated old name — same value as report_date", "deprecated": true }, "time": { "type": "string", "enum": [ "bmo", "amc", "--" ], "description": "bmo = before market open; amc = after market close; -- = not yet set" } }, "description": "The report date is report_date (snake_case); reportDate is the deprecated old name with the same value. Since 2026-10-21, external estimates (EPS, revenue) are not included." }, "ResearchReport": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "firm": { "type": [ "string", "null" ], "description": "Publishing brokerage" }, "date": { "type": [ "string", "null" ], "format": "date" }, "opinion": { "type": [ "string", "null" ] }, "targetPrice": { "type": [ "integer", "null" ], "description": "Target price (KRW)" } }, "description": "Discontinued (deprecated) — available only to keys under existing contracts. Analyst names and report file links are not included." }, "QueryRequest": { "type": "object", "properties": { "queries": { "type": "array", "items": { "type": "object", "properties": { "dataset": { "type": "string", "enum": [ "financials", "metrics", "segments", "restatements", "sector", "sector_ranking", "screener", "dividends", "financial_health", "quote" ] }, "company": { "type": "string", "description": "Korean 6-digit code or company name, or US ticker (symbol, code and ticker are accepted too). Required by every dataset except screener and sector_ranking" }, "account": { "type": "string", "description": "financials, restatements — account name (revenue, operating income, net income, etc.)" }, "period": { "type": "string", "description": "financials, metrics — period (e.g. 'FY2025 Q3', or Korean forms such as '2025 연간' (2025 annual) and '2026 2분기' (2026 Q2))" }, "metric": { "type": "string", "description": "metrics — metric ('영업이익률' (operating margin), 'ROE', '매출 CAGR 3년' (3-year revenue CAGR), '영업이익 전년 동기 대비 성장률' (operating income YoY)); sector_ranking — aggregated metric (Korea: 영업이익, 매출액, 당기순이익, 자산총계, 부채총계, 자본총계, PER, PBR; US: 매출, 순이익, 시가총액, ROE, PER)" }, "years": { "type": "integer", "minimum": 1, "maximum": 20, "description": "dividends — years of dividend history" }, "market": { "type": "string", "enum": [ "kr", "us", "KR", "US" ], "description": "screener, sector_ranking — market (kr by default, case-insensitive)" }, "preset": { "type": "string", "enum": [ "value-growth", "cheap-value", "quality-growth", "high-roe-cheap", "cash-cow", "steady-dividend", "golden-cross", "ma-turn", "rebound", "momentum" ], "description": "screener — named set of conditions. With a preset leave the other conditions empty (only sector can be combined)" }, "sector": { "type": "string", "description": "screener, sector_ranking — industry name (Korea e.g. 반도체와반도체장비, 은행; US e.g. 반도체, 소프트웨어)" }, "subindustry": { "type": "string", "enum": [ "ai_design", "foundry", "memory", "equipment", "analog_power", "materials_parts", "packaging_test" ], "description": "screener, sector_ranking — semiconductor sub-industry" }, "perMax": { "type": "number", "description": "screener — maximum P/E (x)" }, "pbrMax": { "type": "number", "description": "screener — maximum P/B (x)" }, "roeMin": { "type": "number", "description": "screener — minimum ROE (%)" }, "niCagrMin": { "type": "number", "description": "screener — minimum 3-year net income CAGR (%)" }, "revCagrMin": { "type": "number", "description": "screener — minimum 3-year revenue CAGR (%)" }, "grossMarginMin": { "type": "number", "description": "screener — minimum gross margin (%)" }, "divYieldMin": { "type": "number", "description": "screener — minimum dividend yield (%)" }, "marketCapMinEok": { "type": "number", "description": "screener — minimum market cap (Korea: KRW 100 million; US: USD million)" }, "groupBy": { "type": "string", "enum": [ "subindustry" ], "description": "sector_ranking — subindustry = group by semiconductor sub-industry" }, "order": { "type": "string", "enum": [ "desc", "asc" ], "description": "sector_ranking sort: financial accounts default desc; PER/PBR default asc." }, "limit": { "type": "integer", "minimum": 1, "maximum": 30, "description": "screener: max 30 (default 15) · sector_ranking: default 12" }, "filters": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Conditions may be grouped in one object (fields written directly on the line win)" } }, "required": [ "dataset" ], "additionalProperties": true, "description": "Field names are accepted in camelCase (perMax) and snake_case (per_max). Fields the dataset does not know are dropped and listed in results[i].ignored_fields" }, "minItems": 1, "maxItems": 20 } }, "required": [ "queries" ] }, "QueryLineResult": { "type": "object", "properties": { "dataset": { "type": "string" }, "ok": { "type": "boolean", "description": "true only when status is ok" }, "status": { "type": "string", "enum": [ "ok", "not_found", "not_ready", "invalid_input", "unsupported_dataset", "failed", "market_not_entitled", "market_not_available", "timeout" ], "description": "Each line includes authorization, execution and projection within 4 seconds. The request budget is 12 seconds from authorization; completed lines are retained and unstarted lines time out. Invalid request parameters still return BAD_REQUEST. A cold screener returns not_ready / NOT_READY while its shared background build continues; retry shortly. Warm selection uses the completed cache." }, "error": { "type": [ "string", "null" ], "enum": [ "NOT_FOUND", "NOT_READY", "INVALID_INPUT", "UNSUPPORTED_DATASET", "FAILED", "MARKET_NOT_ENTITLED", "MARKET_NOT_AVAILABLE", "TIMEOUT", null ], "description": "Code of a failed line (null on success)" }, "message": { "type": [ "string", "null" ], "description": "English message of a failed line (null on success)" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "For invalid_input — which field and why" }, "ignored_fields": { "type": "array", "items": { "type": "string" }, "description": "Fields this dataset does not know (dropped before computing)" }, "data": { "description": "Result of this line (shape differs by dataset — for a failed line, a value carrying the reason or null)" } }, "required": [ "dataset", "ok", "status", "error", "message", "data" ] }, "QueryResult": { "type": "object", "properties": { "as_of": { "type": "string", "format": "date-time" }, "table": { "type": [ "object", "null" ], "description": "Result table (title, columns, rows) — null if none" }, "data": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Legacy summary (ratios, figures, segments, restatements — some datasets only). Per-line results are in results[i].data" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "n": { "type": "integer" }, "tag": { "type": "string" }, "name": { "type": "string" }, "title": { "type": "string" }, "detail": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "date": { "type": [ "string", "null" ] } } } }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/QueryLineResult" }, "description": "Same order as the request lines" }, "meta": { "type": "object", "properties": { "as_of": { "type": "string", "format": "date-time" }, "lines": { "type": "integer" }, "ok": { "type": "integer" }, "failed": { "type": "integer" }, "complete": { "type": "boolean", "description": "Every line succeeded" }, "partial": { "type": "boolean", "description": "Only some lines succeeded" }, "model_invoked": { "type": "boolean", "description": "Whether any line called a model (currently always false)" } } } } }, "FinancialRow": { "type": "object", "properties": { "account": { "type": "string", "example": "매출액", "description": "Ledger account name (Korean display name)" }, "account_code": { "type": [ "string", "null" ], "enum": [ "revenue", "cost_of_revenue", "gross_profit", "sga_expense", "rnd_expense", "operating_income", "finance_income", "finance_costs", "interest_expense", "pretax_income", "income_tax_expense", "discontinued_operations_income", "net_income", "net_income_controlling", "eps", "current_assets", "cash_and_equivalents", "trade_receivables", "inventories", "noncurrent_assets", "property_plant_equipment", "intangible_assets", "total_assets", "current_liabilities", "trade_payables", "short_term_borrowings", "current_portion_long_term_debt", "noncurrent_liabilities", "bonds_payable", "long_term_borrowings", "total_liabilities", "share_capital", "retained_earnings", "equity_controlling", "noncontrolling_interests", "total_equity", "diluted_shares", "shares_outstanding", "operating_cash_flow", "investing_cash_flow", "financing_cash_flow", "capex", "amortization", "depreciation_amortization", "dividends_paid", null ], "description": "English account code (see the \"Account codes\" table below). Null if the account is not in the table" }, "fiscal_year": { "type": [ "integer", "null" ], "description": "Fiscal year (company fiscal calendar) — the year in which the fiscal year ends; for a March year-end company, April 2026 – March 2027 is 2027" }, "fiscal_quarter": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 4, "description": "Quarter 1–4 (null for annual). For cumulative rows, the ending quarter (H1 = 2, Q1–Q3 = 3)" }, "period": { "type": "string", "example": "2025 연간", "description": "Human-readable period (Korean)" }, "period_code": { "type": [ "string", "null" ], "example": "FY2025", "description": "Machine-readable period code — annual 'FY2025'; quarterly '2026Q3'; cumulative '2025YTDQ2' (H1) or '2025YTDQ3'. Can be passed as-is to the period parameter" }, "period_type": { "type": "string", "enum": [ "annual", "quarter", "cumulative", "other" ] }, "period_start": { "type": [ "string", "null" ], "format": "date", "description": "First day of the period (ISO) — for income statement and cash flow values, the start of the period the value covers (quarter = those 3 months; cumulative and annual = start of the fiscal year); for balance sheet values, the first day of the reporting period that the balance closes. Null if the fiscal year-end month is unknown" }, "period_end": { "type": [ "string", "null" ], "format": "date", "description": "Last day of the period (ISO) — balance sheet values are balances as of this date. US = SEC ledger; Korea = fiscal calendar (fiscal year-end month and report month); rows from company IR materials also carry the period end when the fiscal year-end month is known. Null if the fiscal year-end month is unknown" }, "fiscal_year_end_month": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 12, "description": "Fiscal year-end month (1–12). Korea = month of the latest annual report in the filing ledger, then the listed-company directory, then report titles; US = month of the latest fiscal year end. Null if unknown" }, "fs": { "type": [ "string", "null" ], "enum": [ "CFS", "OFS", null ], "description": "CFS = consolidated; OFS = separate (Korea). CFS for the US" }, "fs_code": { "type": [ "string", "null" ], "enum": [ "CFS", "OFS", null ], "description": "Same value as fs (unified machine-readable name)" }, "value": { "type": "number", "description": "Value in the display unit (unit) — KRW 100 million and USD millions are rounded to integers, so small amounts can be 0. Compute with value_raw" }, "unit": { "type": "string", "description": "억원 (KRW 100 million), 백만달러 (USD million), 달러 (USD, per share), 백만주 (million shares)" }, "unit_code": { "type": [ "string", "null" ], "enum": [ "KRW_EOK", "USD_MIL", "USD", "KRW", "SHARES_MIL", "SHARES", "PCT", null ], "description": "Machine-readable code for unit (KRW_EOK = KRW 100 million, USD_MIL = USD 1 million, USD = USD per share, SHARES_MIL = 1 million shares)" }, "unit_scale": { "type": [ "number", "null" ], "description": "Scale — original amount = value × unit_scale (KRW_EOK 1e8 · USD_MIL 1e6 · SHARES_MIL 1e6 · per-share and % 1)" }, "value_raw": { "type": [ "number", "null" ], "description": "Unrounded value in the original unit (KRW, USD or shares — see raw_unit). Small caps are not flattened to 0. Rows from company IR materials carry that material's precision" }, "raw_unit": { "type": [ "string", "null" ], "enum": [ "KRW", "USD", "SHARES", "PCT", null ], "description": "Unit of value_raw (KRW · USD · SHARES · PCT)" }, "basis": { "type": [ "string", "null" ], "description": "Korean quarterly: '3개월' (3 months; income statement) or '분기 말' (quarter-end; balance sheet)" }, "derivation": { "type": [ "string", "null" ], "description": "If the quarterly value was derived from differences between cumulative filed values, that calculation" }, "preliminary": { "type": "boolean", "description": "True for a preliminary earnings filing. Replaced by confirmed statements for the same period and statement basis." }, "source": { "type": "string", "enum": [ "DART", "SEC", "기업 IR 자료", "PheonixAI" ], "description": "Row source — 'DART' or 'SEC' (filing ledger); '기업 IR 자료' (company IR materials: values filled from company IR materials for periods missing from the ledger); 'PheonixAI' (derived values calculated or aggregated by Phoenix AI)" }, "report": { "type": [ "string", "null" ], "description": "For Korean report titles, the receipt-keyed filing ledger takes priority. Otherwise, use all stored report names for the same issuer and receipt across consolidated/separate financial ledgers and already-read rows. Preserve an agreed name; when only correction prefixes differ over the same base title, use the unique corrected title. Different base titles/periods or multiple corrections remain null rather than being chosen arbitrarily. Only when no stored name exists, use an agreed stored financial-statement form for the receipt. Filing titles override conflicting stored names and retain correction prefixes. An absent optional table/column does not erase an already-established stored name. The rule is independent of account, period, page and financial-statement basis filters; absent verifiable title evidence produces null." }, "report_code": { "type": [ "string", "null" ], "description": "Machine-readable report code — Korea: annual_report (annual report), half_year_report (half-year report), q1_report, q3_report (quarterly reports); US: SEC form type (10-K, 10-Q, 20-F…). Null for IR material rows" }, "filed_date": { "type": [ "string", "null" ], "format": "date", "description": "Filing date. Null for company IR material rows (not a filing)" }, "source_url": { "type": [ "string", "null" ], "format": "uri", "description": "Filing source document (DART, SEC). Null for company IR material rows" } }, "required": [ "account", "account_code", "period", "period_code", "value", "unit", "source" ] }, "NetIncomeSplitRow": { "type": "object", "properties": { "period": { "type": "string", "example": "2025 연간" }, "period_code": { "type": "string", "example": "FY2025", "description": "'FY2025' · '2026Q2'" }, "period_type": { "type": "string", "enum": [ "annual", "quarter" ] }, "fiscal_year": { "type": "integer" }, "fiscal_quarter": { "type": [ "integer", "null" ] }, "fs": { "type": "string", "enum": [ "CFS" ] }, "unit": { "type": "string", "enum": [ "억원" ], "description": "Existing amounts use 8-decimal eok (KRW 100 million); *_raw amounts are integer KRW. nci_share_pct uses 2-decimal percent. JSON numbers omit trailing zeros." }, "unit_code": { "type": "string", "enum": [ "KRW_EOK" ] }, "unit_scale": { "type": "number", "enum": [ 100000000 ], "description": "Original amount = value × unit_scale" }, "controlling_net_income_raw": { "type": "integer", "description": "Net income attributable to owners (integer KRW)" }, "total_net_income_raw": { "type": "integer", "description": "Total consolidated net income (integer KRW)" }, "nci_net_income_raw": { "type": "integer", "description": "Non-controlling net income (integer KRW, total minus controlling)" }, "raw_unit": { "type": "string", "enum": [ "KRW" ] }, "controlling_net_income": { "type": "number", "description": "Net income attributable to owners, in KRW 100 million rounded to 2 decimals. Use controlling_net_income_raw for calculations." }, "total_net_income": { "type": "number", "description": "Consolidated net income, in KRW 100 million rounded to 2 decimals. Use total_net_income_raw for calculations." }, "nci_net_income": { "type": "number", "description": "Non-controlling interests share (total − controlling)" }, "nci_share_pct": { "type": [ "number", "null" ], "description": "Non-controlling interests share of the total (%) — null if the signs differ" }, "sign_case": { "type": "string", "enum": [ "profit", "loss", "controlling_loss_total_profit", "controlling_profit_total_loss" ] }, "basis": { "type": "string", "enum": [ "reported", "derived" ], "description": "derived = quarterly value computed by subtracting cumulative values" }, "material": { "type": "boolean", "description": "Non-controlling interests share is 1% or more of the total" }, "source": { "type": "string", "enum": [ "DART" ] }, "report": { "type": [ "string", "null" ] }, "filed_date": { "type": [ "string", "null" ] }, "source_url": { "type": [ "string", "null" ], "format": "uri" } } }, "GrowthRow": { "type": "object", "properties": { "period": { "type": "string" }, "period_code": { "type": [ "string", "null" ], "description": "'FY2025' · '2026Q2'" }, "value": { "type": "number" }, "unit": { "type": [ "string", "null" ] }, "unit_code": { "type": [ "string", "null" ], "enum": [ "KRW_EOK", "USD_MIL", "USD", "KRW", "SHARES_MIL", "SHARES", "PCT", null ], "description": "Machine-readable code for unit" }, "unit_scale": { "type": [ "number", "null" ], "description": "Original amount = value × unit_scale" }, "source": { "type": "string", "enum": [ "DART", "SEC", "기업 IR 자료", "PheonixAI" ], "description": "Row source — 'DART' or 'SEC' (filing ledger); '기업 IR 자료' (company IR materials: values filled from company IR materials for periods missing from the ledger); 'PheonixAI' (derived values calculated or aggregated by Phoenix AI)" }, "prior_period": { "type": [ "string", "null" ] }, "prior_value": { "type": [ "number", "null" ] }, "change_pct": { "type": [ "number", "null" ], "description": "% change vs. the prior year (same period) or the prior quarter" }, "change": { "type": [ "string", "null" ], "description": "If the base is a loss or 0: '흑자전환' (turned to profit), '적자전환' (turned to loss), '적자지속' (loss continued), or '전기 0' (prior period 0) (change_pct is null)" }, "change_detail": { "type": [ "string", "null" ] } } }, "GrowthTable": { "type": "object", "properties": { "account": { "type": "string", "enum": [ "revenue", "operating_income", "net_income" ] }, "account_name": { "type": "string", "example": "매출액" }, "annual_yoy": { "type": "array", "items": { "$ref": "#/components/schemas/GrowthRow" } }, "cagr": { "type": [ "object", "null" ], "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "years": { "type": "integer" }, "requested_years": { "type": "integer" }, "start_value": { "type": "number" }, "end_value": { "type": "number" }, "unit": { "type": "string" }, "unit_code": { "type": [ "string", "null" ] }, "unit_scale": { "type": [ "number", "null" ] }, "pct": { "type": [ "number", "null" ] }, "change": { "type": [ "string", "null" ] }, "formula": { "type": "string" }, "note": { "type": [ "string", "null" ], "description": "Reason, if calculated over fewer years than requested" } } }, "quarterly_yoy": { "type": "array", "items": { "$ref": "#/components/schemas/GrowthRow" } }, "quarterly_qoq": { "type": "array", "items": { "$ref": "#/components/schemas/GrowthRow" } }, "partner_filled_periods": { "type": "array", "items": { "type": "string" }, "description": "Periods filled from company IR materials" } } }, "Valuation": { "type": "object", "properties": { "market_cap": { "type": [ "number", "null" ], "description": "Market cap (in market_cap_unit — integer KRW 100 million for Korea)" }, "market_cap_unit": { "type": "string", "enum": [ "KRW_EOK", "USD_MIL" ] }, "market_cap_unit_scale": { "type": "number", "enum": [ 100000000, 1000000 ], "description": "Original amount = market_cap × market_cap_unit_scale" }, "market_cap_raw": { "type": [ "number", "null" ], "description": "Market cap in the original unit (KRW or USD, unrounded)" }, "as_of": { "type": [ "string", "null" ], "description": "Legacy basis value, preserved without normalization (including compact YYYYMMDD in the Korean calculation path). New consumers should use price_date and price_time." }, "price": { "type": [ "number", "null" ], "description": "Share price used for PER, PBR and market cap (KRW). For a preferred share, the preferred price. Null for US" }, "price_as_of": { "type": [ "string", "null" ], "description": "Legacy price basis, unchanged: YYYY-MM-DD for date-only batch observations, stored snapshots with a date basis, and the US valuation DTO; ISO 8601 with its original offset/precision when the Korean calculation received an instant. A known date is not replaced by null. Prefer the additive price_date and price_time fields." }, "price_date": { "type": [ "string", "null" ], "format": "date", "description": "Additive normalized trading date, always YYYY-MM-DD when known." }, "price_time": { "type": [ "string", "null" ], "format": "date-time", "description": "Additive price observation instant, ISO 8601 UTC Z; null for date-only or unconfirmed observations. No invented midnight." }, "change_percent": { "type": [ "number", "null" ], "description": "Price change in percent, rounded to two decimals using the same observation as /quotes." }, "price_reason": { "type": [ "string", "null" ], "description": "price_unavailable when a confirmed price observation is unavailable." }, "availability_basis": { "type": "string", "enum": [ "stored_snapshot" ], "description": "Financial basis read from a stored snapshot, with prices recalculated from the shared price observation. Snapshots older than 36 hours or with invalid timestamps use the live calculation path." }, "snapshot_as_of": { "type": [ "string", "null" ], "description": "Legacy snapshot build value, preserved verbatim for strings (including PostgreSQL timestamp text and its precision); Date objects retain ISO serialization. Prefer the additive snapshot_time." }, "snapshot_time": { "type": [ "string", "null" ], "format": "date-time", "description": "Additive normalized financial snapshot build instant, ISO 8601 UTC Z or null." }, "period": { "type": [ "string", "null" ], "deprecated": true, "description": "Deprecated legacy label; prefer period_display/period_code/period_end. Numerator period for EPS / PER / PSR. Preserves the existing calculation path's fiscal label and the stored snapshot's original period label." }, "period_reason": { "type": [ "string", "null" ], "enum": [ "fiscal_period_unconfirmed", "financial_period_unavailable", null ] }, "period_display": { "type": [ "string", "null" ], "description": "Additive resolved fiscal label for a stored snapshot, for example TTM through 2027Q1. Does not replace period." }, "basis": { "type": [ "string", "null" ], "description": "ttm (last four quarters) · annual (latest fiscal year, when no TTM is available)" }, "period_code": { "type": [ "string", "null" ] }, "period_end": { "type": [ "string", "null" ], "format": "date" }, "fiscal_year": { "type": [ "integer", "null" ] }, "fiscal_quarter": { "type": [ "integer", "null" ] }, "fiscal_year_end_month": { "type": [ "integer", "null" ] }, "per": { "type": [ "number", "null" ], "description": "PER (x) — see per_basis. Negative for loss-making companies" }, "pbr": { "type": [ "number", "null" ] }, "psr": { "type": [ "number", "null" ] }, "eps": { "type": [ "number", "null" ], "description": "EPS (KRW or USD) — see shares_basis" }, "bps": { "type": [ "number", "null" ] }, "roe": { "type": [ "number", "null" ], "description": "%" }, "eps_basis": { "type": [ "string", "null" ], "enum": [ "controlling", "total", null ], "description": "Numerator for Korean EPS — controlling = net income attributable to owners of the parent; total = consolidated net income (no owners-of-the-parent value available)" }, "eps_reason": { "type": [ "string", "null" ], "description": "snapshot_per_share_basis_unconfirmed when the snapshot cannot establish a per-share earnings basis." }, "eps_shares": { "type": [ "number", "null" ], "description": "Share count used for Korean EPS and BPS (see shares_basis)" }, "eps_period": { "type": [ "string", "null" ], "deprecated": true, "description": "Period of the EPS numerator (net income) — same text as period (null without EPS)" }, "shares_basis": { "type": [ "string", "null" ], "enum": [ "common_listed", "issuer_common_listed", null ], "description": "EPS / BPS denominator — common_listed = this stock's listed common shares (treasury shares included, preferred excluded; derived from live market cap ÷ price, so stock splits and consolidations apply immediately; can differ from the basic EPS in the annual report, which uses weighted-average shares outstanding excluding treasury shares — the more treasury shares, the larger the gap) · issuer_common_listed = preferred share: the issuer's common shares" }, "per_basis": { "type": [ "string", "null" ], "enum": [ "market_cap_over_net_income", "preferred_price_over_issuer_eps", null ], "description": "PER definition — market_cap_over_net_income = market cap ÷ net income (= price ÷ eps) · preferred_price_over_issuer_eps = preferred price ÷ issuer common-share EPS (the Korean market-data convention)" }, "share_class": { "type": [ "object", "null" ], "description": "Set for Korean preferred shares (null for common shares) — EPS, BPS, and ROE are the issuer's common-share values; PER and PBR = preferred share price ÷ that EPS and BPS; market cap and dividends are the preferred share's own values; PSR is null (reason in holds)", "properties": { "class": { "type": "string", "enum": [ "preferred" ] }, "issuer_symbol": { "type": "string", "example": "005930" }, "class_mark": { "type": [ "string", "null" ], "example": "우" }, "per_share_basis": { "type": "string", "enum": [ "issuer_common" ] }, "note": { "type": "string" }, "holds": { "type": "object", "description": "fwd_per is canonical; fwdPer is a deprecated alias retained until the next major version.", "properties": { "fwd_per": { "type": "string" }, "fwdPer": { "type": "string", "deprecated": true } }, "additionalProperties": { "type": "string" } } } }, "dividend": { "type": [ "object", "null" ], "properties": { "price": { "type": [ "number", "null" ], "description": "Shared price used for annual/TTM dividend yields, in currency. Also populated for US while legacy valuation.price remains null." }, "price_as_of": { "type": [ "string", "null" ] }, "price_date": { "type": [ "string", "null" ], "format": "date" }, "price_time": { "type": [ "string", "null" ], "format": "date-time" }, "dps_reason": { "type": [ "string", "null" ], "description": "Null DPS reason: annual_filing_not_stored, annual_common_class_missing, annual_common_class_ambiguous, annual_dps_missing, preferred_filing_not_stored, preferred_class_missing, preferred_class_ambiguous, preferred_dps_missing, invalid_per_share_amount, or an unconfirmed share basis." }, "yield_reason": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] }, "dps": { "type": [ "number", "null" ], "description": "Dividend per share (KRW or USD) — see dps_basis" }, "yield": { "type": [ "number", "null" ], "description": "Dividend yield (%) = dps ÷ price (see yield_basis)" }, "payout": { "type": [ "number", "null" ], "description": "Payout ratio (%)" }, "years": { "type": [ "integer", "null" ], "description": "Consecutive years paid" }, "currency": { "type": [ "string", "null" ] }, "dps_basis": { "type": [ "string", "null" ], "enum": [ "annual_current_share", "annual_payments_current_share", null ], "description": "annual_current_share = fiscal-year filing DPS adjusted to current shares. annual_payments_current_share = latest completed calendar-year payment sum, adjusted to current shares; used only when the annual summary is absent. It is not TTM. dps_reported and share_factor are null for payment sums." }, "fiscal_year": { "type": [ "integer", "null" ], "description": "Fiscal year for filed DPS; calendar year for annual_payments_current_share. See dps_basis." }, "dps_reported": { "type": [ "number", "null" ], "description": "Dividend per share as filed in the annual report (on the share basis of that time)" }, "share_factor": { "type": [ "number", "null" ], "description": "Factor to today's share basis (1 = no restatement)" }, "yield_basis": { "type": [ "string", "null" ], "enum": [ "annual", "ttm", "paid_over_mc", null ], "description": "annual = fiscal-year dps ÷ price" }, "years_reason": { "type": [ "string", "null" ] }, "years_through": { "type": [ "integer", "null" ] }, "years_note": { "type": [ "string", "null" ], "description": "Consecutive positive-payment years counted backwards from the latest completed year in the stored annual payment ledger (up to 20 years, independent of the display window). In-progress years are excluded; missing, zero or unconfirmed years stop the count. Only stored coverage is counted; the actual history may be longer." }, "ttm_dps_reason": { "type": [ "string", "null" ], "description": "ttm_payment_history_unavailable when a KR trailing payment sum cannot be confirmed." }, "ttm_yield_reason": { "type": [ "string", "null" ], "description": "ttm_payment_history_unavailable or price_unavailable; null when computed." }, "ttm_dps": { "type": [ "number", "null" ], "description": "Dividends over the last 365 days (record-date window, on today's share basis) — a different axis from the fiscal-year dps. For a preferred share, its own dividends" }, "ttm_yield": { "type": [ "number", "null" ], "description": "ttm_dps ÷ current price (%)" } } } } }, "MixAxis": { "type": "object", "properties": { "axis": { "type": "string", "enum": [ "business", "product", "geography", "main_product", "ir_business" ] }, "group": { "type": "string" }, "share_base": { "type": "string", "enum": [ "total", "segment_sum" ] }, "basis_note": { "type": "string" }, "unit": { "type": "string", "enum": [ "억원", "백만달러" ] }, "total": { "type": [ "number", "null" ] }, "base": { "type": [ "number", "null" ] }, "unallocated": { "type": [ "number", "null" ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "pct": { "type": [ "number", "null" ] }, "amount": { "type": [ "number", "null" ] } } } }, "adjustments": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "amount": { "type": [ "number", "null" ] }, "pct": { "type": [ "number", "null" ] } } } }, "excluded_subtotals": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "amount": { "type": [ "number", "null" ] } } } } } }, "ConsensusMetric": { "type": "object", "properties": { "metric": { "type": "string", "enum": [ "revenue", "operating_income" ], "description": "Korea: revenue, operating_income; US: revenue only" }, "name": { "type": "string" }, "currency": { "type": [ "string", "null" ], "enum": [ "KRW", "USD", null ] }, "unit": { "type": [ "string", "null" ], "enum": [ "KRW", "USD", "KRW_EOK", "KRW_MIL", "USD_MIL", null ], "description": "Unit of the amount fields (consensus, revisions.from, actual, consensus_at_report) — set by the unit parameter (default raw = KRW/USD as-is)" }, "unit_scale": { "type": "number", "description": "Size of 1 unit (raw 1, eok 1e8, million 1e6). Original amount = value × unit_scale" }, "consensus": { "type": "number", "description": "Market consensus (in unit)" }, "as_of": { "type": "string", "format": "date" }, "estimate_date": { "type": [ "string", "null" ], "format": "date" }, "revisions": { "type": "object", "properties": { "1w": { "type": [ "object", "null" ], "properties": { "from": { "type": [ "number", "null" ] }, "from_date": { "type": "string", "format": "date" }, "change_pct": { "type": [ "number", "null" ] } } }, "4w": { "type": [ "object", "null" ] }, "12w": { "type": [ "object", "null" ] } } }, "actual": { "type": [ "number", "null" ], "description": "Reported actual value (reported periods, in unit) — the official filing's value when one exists (actual_source)" }, "reported_on": { "type": [ "string", "null" ], "format": "date", "description": "Date the results were first made public (the US Eastern date of the 8-K acceptance time, the Korean preliminary-results filing date, etc.). Null if the source does not provide the report time (some US periods)" }, "actual_source": { "type": [ "object", "null" ], "description": "Official filing (DART, SEC) behind the actual value — null if none", "properties": { "kind": { "type": "string", "enum": [ "dart", "sec" ] }, "doc": { "type": "string" }, "id": { "type": "string", "description": "Receipt number" }, "url": { "type": [ "string", "null" ], "format": "uri" } } }, "consensus_at_report": { "type": [ "number", "null" ], "description": "Consensus just before the report (in unit; its basis is consensus_at_report_basis). Null if none" }, "consensus_at_report_date": { "type": [ "string", "null" ], "format": "date", "description": "Dated basis of the pre-report estimate; for reconstructed values this is the historical estimate date, not the later capture date." }, "consensus_at_report_basis": { "type": [ "string", "null" ], "enum": [ "observed", "captured", "provider", null ], "description": "Legacy date-evidence classification, preserved: observed = historical estimate with a dated basis before release; captured = captured before release; provider = identified as a pre-report estimate without a dated basis. observed does not assert when this service captured the value. Reconstruction is a separate dimension, given by consensus_at_report_reconstructed." }, "consensus_at_report_as_of": { "type": [ "string", "null" ], "format": "date", "description": "Optional report-comparison cutoff (day before release), including in latest responses. Does not change the latest consensus or its as_of; absent when no comparison cutoff is established." }, "consensus_at_report_source": { "type": [ "string", "null" ], "enum": [ "market_consensus", null ], "description": "Optional report-comparison source; null when no historical estimate is available." }, "consensus_at_report_reconstructed": { "type": [ "boolean", "null" ], "description": "Optional report-comparison provenance: true for reconstruction from dated estimates, false for a recorded observation, null when no historical estimate is available. This describes the acquisition/calculation method; basis describes date evidence, so observed and true can coexist without claiming a same-day capture." }, "vs_consensus_pct": { "type": [ "number", "null" ], "description": "(actual − consensus_at_report) ÷ |consensus_at_report| × 100. Null if consensus_at_report is absent" }, "comparison_status": { "type": "string", "enum": [ "compared", "basis_unconfirmed", "no_pre_report_estimate", "no_actual", "upcoming" ], "description": "compared = calculated; basis_unconfirmed = could not confirm that the estimate and the reported value share the same basis; no_pre_report_estimate = no consensus before the report date, or the report date (reported_on) is unknown; no_actual = reported period, but no actual value on the same basis; upcoming = not yet reported" }, "comparison_note": { "type": [ "string", "null" ], "description": "Reason vs_consensus_pct is null (human-readable sentence)" } }, "not": { "required": [ "observed_on" ] } }, "ConsensusCoverage": { "type": "object", "properties": { "as_of": { "type": "string", "format": "date" }, "date_basis": { "type": "string", "enum": [ "KST (Asia/Seoul) date" ], "description": "Date boundary — Korea-time calendar day" }, "coverage_start": { "type": [ "string", "null" ], "format": "date", "description": "First observation recorded for this symbol (requested metrics) — record depth" }, "status": { "type": "string", "enum": [ "covered", "partial", "not_covered" ], "description": "covered = every item answered from values recorded by as_of; partial = some items had no record on that date (not_covered); not_covered = nothing had been recorded on that date" }, "not_covered": { "type": "array", "items": { "type": "object", "properties": { "period": { "type": "string" }, "period_type": { "type": "string", "enum": [ "annual", "quarterly" ] }, "fiscal_year": { "type": [ "integer", "null" ] }, "fiscal_quarter": { "type": [ "integer", "null" ] }, "metric": { "type": "string", "enum": [ "revenue", "operating_income" ] }, "coverage_start": { "type": [ "string", "null" ], "format": "date" } } }, "description": "Items with no record on as_of — never filled with later values" }, "reconstruction_unavailable": { "type": "boolean", "description": "true = the Korean broker-report median could not be recomputed for this request (temporary error)" } } }, "VarianceSource": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "dart", "sec" ] }, "doc": { "type": "string", "example": "10-Q" }, "id": { "type": "string", "description": "Receipt number" }, "filed_on": { "type": [ "string", "null" ], "format": "date" }, "url": { "type": [ "string", "null" ], "format": "uri" } } }, "GuidanceRow": { "type": "object", "properties": { "metric": { "type": "string", "enum": [ "revenue", "operating_income", "net_income", "net_income_controlling", "eps", "eps_adjusted" ] }, "name": { "type": "string" }, "currency": { "type": "string", "enum": [ "KRW", "USD" ] }, "unit": { "type": "string", "enum": [ "KRW", "USD", "KRW_PER_SHARE", "USD_PER_SHARE" ], "description": "Unit of the values (value, low, high) — amounts in KRW/USD as-is, EPS per share" }, "unit_scale": { "type": "number", "enum": [ 1 ], "description": "Value multiplier (always 1 — values are in base units)" }, "display_unit": { "type": "string", "description": "Display unit for tables (억원 (KRW 100 million), 백만달러 (USD million), 원 (KRW), 달러 (USD))" }, "display_scale": { "type": "number", "description": "Display unit multiplier — value ÷ display_scale = number in display_unit (억원 1e8, 백만달러 1e6)" }, "basis": { "type": "string" }, "status": { "type": "string", "enum": [ "compared", "not_comparable", "actual_missing", "no_reference" ] }, "reported": { "type": [ "object", "null" ], "properties": { "value": { "type": "number" }, "text": { "type": [ "string", "null" ] }, "preliminary": { "type": "boolean" }, "source": { "$ref": "#/components/schemas/VarianceSource" }, "derived_from": { "type": "array", "items": { "$ref": "#/components/schemas/VarianceSource" } }, "derivation": { "type": [ "string", "null" ] } } }, "guidance": { "type": [ "object", "null" ], "properties": { "low": { "type": "number" }, "high": { "type": "number" }, "text": { "type": [ "string", "null" ] }, "issued_on": { "type": "string" }, "comparable": { "type": "boolean" }, "source": { "$ref": "#/components/schemas/VarianceSource" }, "bound": { "type": "string", "enum": [ "range", "point", "approx", "at_least", "at_most" ] }, "action": { "type": [ "string", "null" ], "enum": [ "raised", "lowered", "narrowed", "reaffirmed", "initiated", "updated", null ] }, "quote": { "type": [ "string", "null" ], "description": "Source sentence containing the figure (US 8-K)" } } }, "vs_guidance_pct": { "type": [ "number", "null" ] }, "guidance_position": { "type": [ "string", "null" ], "enum": [ "below", "within", "above", null ] }, "consensus": { "type": [ "object", "null" ], "description": "Pre-report market consensus — revenue and operating income only (null for other items)", "properties": { "value": { "type": "number" }, "text": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "observed_on": { "type": [ "string", "null" ], "description": "Null when basis is provider" }, "basis": { "type": "string", "enum": [ "observed", "captured", "provider" ] }, "comparable": { "type": "boolean" }, "source": { "type": "string", "enum": [ "PheonixAI" ] } } }, "surprise_pct": { "type": [ "number", "null" ] }, "reasons": { "type": "array", "items": { "type": "object", "properties": { "target": { "type": "string", "enum": [ "actual", "consensus", "guidance" ] }, "code": { "type": "string" }, "text": { "type": "string" } } } } } }, "GuidanceOutlook": { "type": "object", "properties": { "metric": { "type": "string", "enum": [ "revenue", "operating_income", "net_income", "eps", "eps_adjusted", "net_interest_income", "ffo_per_share", "affo_per_share", "combined_ratio" ] }, "name": { "type": "string" }, "period": { "type": "string" }, "period_type": { "type": "string", "enum": [ "annual", "quarterly" ] }, "fiscal_year": { "type": "integer" }, "fiscal_quarter": { "type": [ "integer", "null" ] }, "period_end": { "type": [ "string", "null" ], "format": "date" }, "currency": { "type": "string", "enum": [ "KRW", "USD" ] }, "unit": { "type": "string", "enum": [ "KRW", "USD", "KRW_PER_SHARE", "USD_PER_SHARE", "PERCENT" ] }, "unit_scale": { "type": "number", "description": "Always 1" }, "low": { "type": [ "number", "null" ] }, "high": { "type": [ "number", "null" ] }, "bound": { "type": "string", "enum": [ "range", "point", "approx", "at_least", "at_most" ] }, "text": { "type": [ "string", "null" ] }, "basis": { "type": [ "string", "null" ], "enum": [ "reported", "gaap", "adjusted", null ] }, "statement": { "type": [ "string", "null" ], "enum": [ "연결", "별도", null ] }, "issued_on": { "type": "string", "format": "date" }, "action": { "type": [ "string", "null" ], "enum": [ "raised", "lowered", "narrowed", "reaffirmed", "initiated", "updated", null ] }, "action_basis": { "type": [ "string", "null" ], "enum": [ "stated", "vs_prior", null ] }, "prior": { "type": [ "object", "null" ], "properties": { "low": { "type": [ "number", "null" ] }, "high": { "type": [ "number", "null" ] }, "bound": { "type": "string" }, "issued_on": { "type": "string", "format": "date" }, "source": { "$ref": "#/components/schemas/VarianceSource" } } }, "quote": { "type": [ "string", "null" ], "description": "Source sentence containing the figure (for Korea, the row name in the outlook filing table)" }, "source": { "$ref": "#/components/schemas/VarianceSource" } } }, "KrFiling": { "type": "object", "properties": { "id": { "type": "string" }, "market": { "type": "string", "enum": [ "KR" ] }, "rcept_no": { "type": "string" }, "title": { "type": "string" }, "report_code": { "type": [ "string", "null" ], "description": "annual_report, half_year_report, q1_report, or q3_report for periodic reports; null for other filings" }, "filer": { "type": [ "string", "null" ] }, "filed_date": { "type": "string", "format": "date" }, "url": { "type": "string", "format": "uri" }, "page_url": { "type": "string", "format": "uri" }, "summary": { "type": [ "object", "null" ], "description": "Stored filing summary when include_summary=true (null if none)", "properties": { "headline": { "type": "string" }, "category": { "type": "string" }, "plain": { "type": "string" } } } } }, "UsFiling": { "type": "object", "properties": { "id": { "type": "string", "example": "AAPL:0000320193-26-000071" }, "market": { "type": "string", "enum": [ "US" ] }, "accession": { "type": "string" }, "form": { "type": "string", "example": "8-K" }, "report_code": { "type": "string", "example": "8-K", "description": "SEC form type (uppercase) — same field as report_code for Korea" }, "filed_date": { "type": "string", "format": "date" }, "report_date": { "type": [ "string", "null" ], "format": "date" }, "category": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "2.02" }, "label": { "type": [ "string", "null" ] } } } }, "title": { "type": "string" }, "amended": { "type": "boolean" }, "url": { "type": [ "string", "null" ], "format": "uri" }, "analysis": { "type": [ "object", "null" ], "description": "Filing analysis reviewed and published by Phoenix AI (null if none)", "properties": { "headline": { "type": "string" }, "published_at": { "type": "string", "format": "date-time" }, "page_url": { "type": "string", "format": "uri" } } } } }, "UsFilingEvent": { "type": "object", "properties": { "id": { "type": "string", "example": "CMS:0001104659-26-118972", "description": "Ticker:SEC accession number" }, "market": { "type": "string", "enum": [ "US" ] }, "symbol": { "type": "string", "example": "CMS" }, "cik": { "type": [ "string", "null" ], "example": "0000811156", "description": "SEC CIK (10 digits)" }, "accession": { "type": "string", "example": "0001104659-26-118972" }, "company": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "description": "Korean company name (English name when there is none)" }, "name_en": { "type": [ "string", "null" ] } } }, "form": { "type": "string", "enum": [ "8-K", "8-K/A", "6-K", "6-K/A", "10-Q", "10-Q/A", "10-K", "10-K/A", "20-F", "20-F/A", "40-F", "40-F/A" ] }, "amended": { "type": "boolean" }, "items": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "2.02", "description": "SEC 8-K item code — the event classification defined by the SEC" }, "label": { "type": [ "string", "null" ], "example": "실적 발표" }, "label_en": { "type": [ "string", "null" ], "example": "Results of Operations and Financial Condition" } } } }, "category": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "filed_date": { "type": "string", "format": "date" }, "report_date": { "type": [ "string", "null" ], "format": "date" }, "accepted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "SEC acceptance time (EDGAR acceptance). Null for older filings without a recorded time" }, "detected_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When Phoenix AI detected the filing and queued it for analysis. Null for filings outside live collection" }, "source_url": { "type": [ "string", "null" ], "format": "uri", "description": "SEC EDGAR original document" }, "analysis": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "published", "pending", "withheld", "unreadable_source", "not_analyzed" ], "description": "published · pending (queued or being analysed) · withheld (analysed but not published because verification failed; an automatic retry may still publish it) · unreadable_source (materials submitted only as images, or in an exhibit format not read yet such as PDF) · not_analyzed (outside the analysis scope). A point-in-time state that can change" }, "headline": { "type": [ "string", "null" ], "description": "Published one-line headline (Korean, AI-written and verified against the filing). Bodies are a PRO API feature" }, "headline_en": { "type": [ "string", "null" ], "description": "Headline of the published English translation, when there is one" }, "published_at": { "type": [ "string", "null" ], "format": "date-time" }, "latency_seconds": { "type": [ "integer", "null" ], "description": "SEC acceptance → analysis publication (seconds)" }, "page_url": { "type": [ "string", "null" ], "format": "uri" } } } } }, "UsEarningsFigure": { "type": "object", "properties": { "metric": { "type": "string", "enum": [ "revenue", "gross_profit", "operating_income", "net_income", "eps_diluted", "adjusted_eps", "adjusted_net_income", "adjusted_operating_income", "adjusted_ebitda", "operating_cash_flow", "free_cash_flow", "net_interest_income", "provision_credit_losses", "net_interest_margin", "ffo_per_share", "affo_per_share" ] }, "name": { "type": "string", "example": "매출" }, "name_en": { "type": "string", "example": "Revenue" }, "unit": { "type": "string", "enum": [ "USD", "USD_PER_SHARE", "PERCENT" ] }, "basis": { "type": "string", "enum": [ "gaap", "non_gaap", "reported_ratio" ] }, "value": { "type": "number", "description": "Value for the quarter — base units (USD, USD_PER_SHARE, PERCENT)" }, "prior_value": { "type": [ "number", "null" ], "description": "Prior-year value from the same release; null when not stated" }, "yoy_pct": { "type": [ "number", "null" ], "description": "Year-over-year change (%) — (value − prior) ÷ prior × 100, one decimal; only when the prior value is positive and the value is not negative" }, "change_pp": { "type": [ "number", "null" ] }, "turnaround": { "type": [ "string", "null" ], "enum": [ "흑자전환", "적자전환", "적자지속", null ], "description": "Profit sign change — 흑자전환 (turned profitable) · 적자전환 (turned to a loss) · 적자지속 (loss in both periods); yoy_pct is then null" }, "source": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "table_cell", "quote", "income_statement" ] }, "ref": { "type": "string", "example": "T2.R3.C1" }, "row_label": { "type": "string" }, "column": { "type": [ "string", "null" ] }, "quote": { "type": "string" }, "text": { "type": "string" } }, "description": "Provenance — table_cell (cell id, row label, column header) · quote (exact sentence and the number as written) · income_statement (three-month income-statement column)" }, "prior_source": { "type": [ "object", "null" ], "properties": { "kind": { "type": "string", "enum": [ "table_cell", "quote", "income_statement" ] }, "ref": { "type": "string" }, "row_label": { "type": "string" }, "column": { "type": [ "string", "null" ] }, "quote": { "type": "string" }, "text": { "type": "string" } } }, "cross_check": { "type": [ "string", "null" ], "enum": [ "match", "differs", null ], "description": "Cross-check when both the income-statement parser and the extraction read the figure — match (within 0.5%) · differs (left out of the flash) · null (one reading only)" } } }, "UsEarningsSurprise": { "type": "object", "properties": { "metric": { "type": "string", "enum": [ "revenue", "operating_income", "net_income", "eps", "eps_adjusted" ] }, "name": { "type": "string", "example": "EPS(주당순이익)" }, "basis": { "type": "string", "example": "GAAP 희석 · 3개월" }, "eps_basis": { "type": [ "string", "null" ], "enum": [ "gaap_diluted", "adjusted", null ] }, "currency": { "type": "string", "enum": [ "USD" ] }, "unit": { "type": "string", "enum": [ "USD", "USD_PER_SHARE" ] }, "actual": { "type": "object", "properties": { "value": { "type": "number" }, "text": { "type": [ "string", "null" ] }, "source": { "type": "object", "properties": { "kind": { "type": "string" }, "doc": { "type": "string" }, "id": { "type": "string" }, "filed_on": { "type": "string", "format": "date" }, "url": { "type": [ "string", "null" ], "format": "uri" } } } } }, "consensus": { "type": "object", "properties": { "value": { "type": "number" }, "text": { "type": [ "string", "null" ] }, "label": { "type": "string", "enum": [ "시장 컨센서스(증권사 추정 종합)", "시장 예상치" ] }, "observed_on": { "type": [ "string", "null" ], "format": "date" }, "as_of_basis": { "type": "string", "enum": [ "observed", "captured", "provider" ] }, "estimate_date": { "type": [ "string", "null" ], "format": "date" } }, "description": "Last consensus observed before the release — label (시장 컨센서스 market consensus · 시장 예상치 market estimate), observed_on (observation date), as_of_basis (observed · captured · provider). No provider names" }, "surprise_pct": { "type": "number" } } }, "UsEarningsGuidanceComparison": { "type": "object", "properties": { "metric": { "type": "string", "example": "eps_adjusted" }, "name": { "type": "string", "example": "조정 EPS" }, "period": { "type": "string", "example": "FY2026 연간" }, "period_type": { "type": "string", "enum": [ "quarterly", "annual" ] }, "fiscal_year": { "type": "integer" }, "fiscal_quarter": { "type": [ "integer", "null" ] }, "period_end": { "type": [ "string", "null" ], "format": "date" }, "unit": { "type": "string", "enum": [ "USD", "USD_PER_SHARE", "PERCENT" ] }, "basis": { "type": [ "string", "null" ], "example": "adjusted" }, "low": { "type": [ "number", "null" ] }, "high": { "type": [ "number", "null" ] }, "bound": { "type": "string", "enum": [ "range", "point", "approx", "at_least", "at_most" ] }, "text": { "type": [ "string", "null" ] }, "issued_on": { "type": "string", "format": "date" }, "change": { "type": "object", "properties": { "action": { "type": [ "string", "null" ], "enum": [ "raised", "lowered", "narrowed", "reaffirmed", "initiated", "updated", null ] }, "basis": { "type": [ "string", "null" ], "enum": [ "stated", "vs_prior", null ] }, "prior": { "type": [ "object", "null" ], "properties": { "low": { "type": [ "number", "null" ] }, "high": { "type": [ "number", "null" ] }, "bound": { "type": "string" }, "issued_on": { "type": "string", "format": "date" } } }, "ref_change_pct": { "type": [ "number", "null" ] } } }, "consensus": { "type": [ "object", "null" ], "properties": { "value": { "type": "number" }, "text": { "type": [ "string", "null" ] }, "label": { "type": "string", "enum": [ "시장 컨센서스(증권사 추정 종합)", "시장 예상치" ] }, "observed_on": { "type": [ "string", "null" ], "format": "date" }, "estimates": { "type": [ "integer", "null" ] }, "as_of_basis": { "type": "string", "enum": [ "observed" ] } } }, "guidance_ref": { "type": [ "number", "null" ] }, "guidance_vs_consensus_pct": { "type": [ "number", "null" ] }, "consensus_position": { "type": [ "string", "null" ], "enum": [ "below", "within", "above", null ] }, "consensus_reason": { "type": [ "string", "null" ] }, "period_as_written": { "type": [ "string", "null" ], "example": "full-year 2026" }, "label": { "type": [ "string", "null" ], "example": "연간 조정 EPS" }, "quote": { "type": [ "string", "null" ] } }, "description": "Outlook statements of this release from the guidance ledger (normalized by measure, fiscal period and basis) with comparisons — change (vs the previous statement for the same period: action raised · lowered · narrowed · reaffirmed; basis stated = said by the company · vs_prior = compared by code with the previous statement; ref_change_pct = change of the reference value) · consensus (the market consensus for the same period, measure and basis last observed before the day of the release, observed within two weeks; values observed after the release are never used) · guidance_ref (range midpoint, single value or open bound) · guidance_vs_consensus_pct = (guidance_ref − consensus) ÷ |consensus| × 100 · consensus_position (the consensus below, within or above the outlook range). Revenue is compared on the reported basis and EPS only when the adjusted/GAAP basis matches; otherwise consensus_reason. Only statements two readings agree on (the outlook sentence rules and the release extraction: same bounds, period kind and measure) are included; period_as_written, label and quote are as the release wrote them. Computed on the detail endpoint and in webhooks only (null in the list)" }, "UsEarningsRelease": { "type": "object", "properties": { "id": { "type": "string", "example": "WSO:0000105016-26-000123", "description": "Ticker:SEC accession number" }, "market": { "type": "string", "enum": [ "US" ] }, "symbol": { "type": "string", "example": "WSO" }, "cik": { "type": [ "string", "null" ], "description": "SEC CIK (10 digits)" }, "accession": { "type": "string" }, "company": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "description": "Korean company name (English name when there is none)" }, "name_en": { "type": [ "string", "null" ] } } }, "form": { "type": "string", "example": "8-K" }, "items": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "2.02" }, "label": { "type": [ "string", "null" ] }, "label_en": { "type": [ "string", "null" ] } } } }, "filed_date": { "type": "string", "format": "date" }, "report_date": { "type": [ "string", "null" ], "format": "date" }, "period": { "type": "object", "properties": { "label_ko": { "type": [ "string", "null" ], "example": "2026년 3분기" }, "end": { "type": [ "string", "null" ], "format": "date" }, "header": { "type": [ "string", "null" ] }, "duration": { "type": "string", "enum": [ "quarter" ] } }, "description": "label_ko = Korean period name read from the company's wording (only when it agrees with the income-statement period end; otherwise the end date) · end = period end of the three-month column · header = that column header" }, "currency": { "type": "string", "enum": [ "USD" ] }, "figures": { "type": "array", "items": { "$ref": "#/components/schemas/UsEarningsFigure" }, "description": "Verified figures (standard measure order). A measure that is not reported has no row (never filled with 0)" }, "margins": { "type": "object", "properties": { "gross_margin_pct": { "type": [ "object", "null" ], "properties": { "value": { "type": "number" }, "prior_value": { "type": [ "number", "null" ] } } }, "operating_margin_pct": { "type": [ "object", "null" ], "properties": { "value": { "type": "number" }, "prior_value": { "type": [ "number", "null" ] } } } }, "description": "Margins (%) — divided by revenue of the same release (the prior year the same way)" }, "kpis": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "unit": { "type": "string", "enum": [ "USD", "USD_PER_SHARE", "PERCENT", "COUNT" ] }, "value": { "type": "number" }, "text": { "type": "string" }, "quote": { "type": "string" } } }, "description": "Operating KPIs stated by the company — the exact sentence (quote) and the number in it (text). name is the label assigned while locating it" }, "segments": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "Performance Coatings" }, "name_ko": { "type": "string", "example": "퍼포먼스 코팅" }, "kind": { "type": "string", "enum": [ "segment", "reconciling" ] }, "revenue": { "type": [ "object", "null" ], "properties": { "value": { "type": "number" }, "prior_value": { "type": [ "number", "null" ] }, "yoy_pct": { "type": [ "number", "null" ] }, "source": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "table_cell" ] }, "ref": { "type": "string" }, "row_label": { "type": "string" }, "column": { "type": [ "string", "null" ] } } }, "prior_source": { "type": [ "object", "null" ], "properties": { "kind": { "type": "string" }, "ref": { "type": "string" }, "row_label": { "type": "string" }, "column": { "type": [ "string", "null" ] } } } } }, "profit": { "type": [ "object", "null" ], "properties": { "label": { "type": "string", "example": "Segment income" }, "value": { "type": "number" }, "prior_value": { "type": [ "number", "null" ] }, "yoy_pct": { "type": [ "number", "null" ] }, "margin_pct": { "type": [ "number", "null" ] }, "prior_margin_pct": { "type": [ "number", "null" ] }, "source": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "table_cell" ] }, "ref": { "type": "string" }, "row_label": { "type": "string" }, "column": { "type": [ "string", "null" ] } } }, "prior_source": { "type": [ "object", "null" ], "properties": { "kind": { "type": "string" }, "ref": { "type": "string" }, "row_label": { "type": "string" }, "column": { "type": [ "string", "null" ] } } } } } } }, "description": "Business segments (the release's segment table) — per segment revenue (value, prior_value, yoy_pct) and segment profit (label as written, margin_pct = segment profit ÷ segment revenue) with table-cell provenance. kind reconciling = rows the table uses to reach the consolidated total (corporate, eliminations; no growth or margin). Included only when segment revenue (with reconciling rows) adds up to revenue within the rounding of the cells, otherwise an empty array. From extraction v3 on (earlier readings: empty)" }, "segment_check": { "type": [ "object", "null" ], "properties": { "revenue_sum": { "type": "number" }, "revenue_total": { "type": "number" }, "prior_sum": { "type": [ "number", "null" ] }, "prior_total": { "type": [ "number", "null" ] } }, "description": "Segment sum check — revenue_sum (segments and reconciling rows) and revenue_total (consolidated revenue); prior_sum and prior_total when the prior-year quarter also adds up (otherwise null, and segment prior values and growth are null too)" }, "outlook": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "period": { "type": "string" }, "unit": { "type": "string", "enum": [ "USD", "USD_PER_SHARE", "PERCENT", "COUNT" ] }, "low": { "type": [ "number", "null" ] }, "high": { "type": [ "number", "null" ] }, "low_text": { "type": [ "string", "null" ] }, "high_text": { "type": [ "string", "null" ] }, "qualifier": { "type": [ "string", "null" ] }, "basis": { "type": [ "string", "null" ], "enum": [ "gaap", "non_gaap", null ] }, "action": { "type": [ "string", "null" ], "enum": [ "raised", "lowered", "narrowed", "reaffirmed", "initiated", "updated", null ] }, "quote": { "type": "string" } } }, "description": "Outlook stated in this release — low and high (base units), the bounds as written, and the quote. name is the label assigned while locating it" }, "surprise": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/UsEarningsSurprise" }, "description": "Comparison with the pre-release consensus — computed on the detail endpoint and in webhooks only (null in the list); an empty array when no comparison holds" }, "guidance_comparison": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/UsEarningsGuidanceComparison" }, "description": "Outlook statements of this release from the guidance ledger (normalized by measure, fiscal period and basis) with comparisons — change (vs the previous statement for the same period: action raised · lowered · narrowed · reaffirmed; basis stated = said by the company · vs_prior = compared by code with the previous statement; ref_change_pct = change of the reference value) · consensus (the market consensus for the same period, measure and basis last observed before the day of the release, observed within two weeks; values observed after the release are never used) · guidance_ref (range midpoint, single value or open bound) · guidance_vs_consensus_pct = (guidance_ref − consensus) ÷ |consensus| × 100 · consensus_position (the consensus below, within or above the outlook range). Revenue is compared on the reported basis and EPS only when the adjusted/GAAP basis matches; otherwise consensus_reason. Only statements two readings agree on (the outlook sentence rules and the release extraction: same bounds, period kind and measure) are included; period_as_written, label and quote are as the release wrote them. Computed on the detail endpoint and in webhooks only (null in the list)" }, "reaction": { "type": [ "object", "null" ], "properties": { "status": { "type": "string", "enum": [ "measured", "pending", "unavailable" ] }, "reason": { "type": [ "string", "null" ], "enum": [ "announce_time_unknown", "price_series_unverified", "price_cross_check_failed", "price_gap", "awaiting_close", null ] }, "announced_at": { "type": [ "string", "null" ], "format": "date-time" }, "announced_basis": { "type": [ "string", "null" ], "enum": [ "sec_acceptance", "press_release", null ] }, "session": { "type": [ "string", "null" ], "enum": [ "pre_market", "regular", "after_hours", "market_closed", null ] }, "prior_close": { "type": [ "object", "null" ], "properties": { "date": { "type": "string", "format": "date" }, "close": { "type": "number" } } }, "reaction_close": { "type": [ "object", "null" ], "properties": { "date": { "type": "string", "format": "date" }, "close": { "type": "number" } } }, "change_pct": { "type": [ "number", "null" ] } }, "description": "Price reaction — change (change_pct, %, two decimals) from the last regular-session close before the announcement (SEC acceptance, or an earlier company press release on the same day — announced_basis; prior_close) to the first regular-session close after it (reaction_close). session = US Eastern session of the announcement (pre_market before 09:30 · regular during the session · after_hours from 16:00 · market_closed on weekends and NYSE holidays); an in-session announcement mixes in trading before it. status = measured · pending (the first session after it has not closed yet) · unavailable (reason: announce_time_unknown no acceptance time · price_series_unverified split adjustment not confirmed and no independent daily change to check against · price_cross_check_failed differs from an independent daily change for that day by more than 0.05 pp · price_gap one of the two closes is missing). null when not computed" }, "flash": { "type": [ "object", "null" ], "properties": { "headline": { "type": "string" }, "text": { "type": "string" }, "lines": { "type": "array", "items": { "type": "string" } } }, "description": "Earnings flash — Korean headline and one or two lines built by code from these figures (not AI-written). null without figures" }, "revision": { "type": "object", "properties": { "fingerprint": { "type": "string", "description": "Fingerprint of figure and outlook values — equal values give the same fingerprint" }, "number": { "type": "integer", "description": "Webhooks only — the nth figures notice for this filing (from 1). It grows only when a new reading changes values" }, "previous_event_id": { "type": [ "string", "null" ] }, "changed": { "type": "array", "items": { "type": "string" } } }, "description": "Figures version — fingerprint (of figure and outlook values). Webhooks add number (nth figures notice for this filing, from 1), previous_event_id (the previous notice) and changed (measures that changed)" }, "timestamps": { "type": "object", "properties": { "accepted_at": { "type": [ "string", "null" ], "format": "date-time" }, "release_fetched_at": { "type": [ "string", "null" ], "format": "date-time" }, "extracted_at": { "type": [ "string", "null" ], "format": "date-time" }, "latency_seconds": { "type": [ "integer", "null" ] } }, "description": "accepted_at = SEC acceptance time · release_fetched_at = when the release was fetched and its income statement read · extracted_at = when the extraction finished · latency_seconds = acceptance → first figures (seconds)" }, "extraction": { "type": "object", "properties": { "version": { "type": [ "string", "null" ] }, "method": { "type": "string", "enum": [ "table_parser", "model_located_code_verified", "both" ], "description": "How the figures were read — table_parser (income-statement parser) · model_located_code_verified (a model located them, code checked them against the release) · both" } } }, "source_url": { "type": [ "string", "null" ], "format": "uri", "description": "SEC EDGAR original document" }, "exhibit_url": { "type": [ "string", "null" ], "format": "uri" }, "page_url": { "type": [ "string", "null" ], "format": "uri" } } }, "WebhookFilters": { "type": "object", "properties": { "symbols": { "type": [ "array", "null" ], "items": { "type": "string", "example": "AAPL" }, "maxItems": 100 }, "forms": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "8-K", "6-K", "10-Q", "10-K", "20-F", "40-F" ] } }, "items": { "type": [ "array", "null" ], "items": { "type": "string", "example": "2.02" }, "maxItems": 20 } }, "description": "Filters — an empty field receives everything" }, "WebhookRequest": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2000, "description": "Destination (https, port 443, public internet)" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "us_filing.detected", "us_filing.analysis_published", "us_filing.analysis_revoked", "us_earnings.figures" ] }, "description": "Events to receive (all when omitted)" }, "filters": { "$ref": "#/components/schemas/WebhookFilters" }, "status": { "type": "string", "enum": [ "active", "disabled" ], "description": "`PATCH` only — active (enable; resets the failure streak) · disabled (disable)" } }, "additionalProperties": false }, "Webhook": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "us_filing.detected", "us_filing.analysis_published", "us_filing.analysis_revoked", "us_earnings.figures" ] } }, "filters": { "$ref": "#/components/schemas/WebhookFilters" }, "status": { "type": "string", "enum": [ "active", "disabled" ] }, "disabled_reason": { "type": [ "string", "null" ], "enum": [ "consecutive_failures", "disabled_by_customer", null ], "description": "Why it is disabled — consecutive_failures · disabled_by_customer" }, "consecutive_failures": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "WebhookDelivery": { "type": "object", "properties": { "id": { "type": "string", "example": "msg_6f1c…", "description": "Value of the webhook-id header" }, "event_id": { "type": "string", "example": "evt_1042" }, "type": { "type": "string", "enum": [ "us_filing.detected", "us_filing.analysis_published", "us_filing.analysis_revoked", "us_earnings.figures" ] }, "filing_id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "delivered", "dead" ], "description": "pending (due or waiting to retry) · delivered (2xx answer) · dead (retries exhausted or webhook disabled)" }, "attempts": { "type": "integer" }, "last_status": { "type": [ "integer", "null" ] }, "last_error": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time" }, "next_attempt_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "WebhookEvent": { "type": "object", "properties": { "id": { "type": "string", "example": "evt_1042" }, "type": { "type": "string", "enum": [ "us_filing.detected", "us_filing.analysis_published" ] }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "id": { "type": "string", "example": "CMS:0001104659-26-118972", "description": "Ticker:SEC accession number" }, "market": { "type": "string", "enum": [ "US" ] }, "symbol": { "type": "string", "example": "CMS" }, "cik": { "type": [ "string", "null" ], "example": "0000811156", "description": "SEC CIK (10 digits)" }, "accession": { "type": "string", "example": "0001104659-26-118972" }, "company": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "description": "Korean company name (English name when there is none)" }, "name_en": { "type": [ "string", "null" ] } } }, "form": { "type": "string", "enum": [ "8-K", "8-K/A", "6-K", "6-K/A", "10-Q", "10-Q/A", "10-K", "10-K/A", "20-F", "20-F/A", "40-F", "40-F/A" ] }, "amended": { "type": "boolean" }, "items": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "2.02", "description": "SEC 8-K item code — the event classification defined by the SEC" }, "label": { "type": [ "string", "null" ], "example": "실적 발표" }, "label_en": { "type": [ "string", "null" ], "example": "Results of Operations and Financial Condition" } } } }, "category": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "filed_date": { "type": "string", "format": "date" }, "report_date": { "type": [ "string", "null" ], "format": "date" }, "accepted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "SEC acceptance time (EDGAR acceptance). Null for older filings without a recorded time" }, "detected_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When Phoenix AI detected the filing and queued it for analysis. Null for filings outside live collection" }, "source_url": { "type": [ "string", "null" ], "format": "uri", "description": "SEC EDGAR original document" }, "analysis": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "published", "pending", "withheld", "unreadable_source", "not_analyzed" ], "description": "published · pending (queued or being analysed) · withheld (analysed but not published because verification failed; an automatic retry may still publish it) · unreadable_source (materials submitted only as images, or in an exhibit format not read yet such as PDF) · not_analyzed (outside the analysis scope). A point-in-time state that can change" }, "headline": { "type": [ "string", "null" ], "description": "Published one-line headline (Korean, AI-written and verified against the filing). Bodies are a PRO API feature" }, "headline_en": { "type": [ "string", "null" ], "description": "Headline of the published English translation, when there is one" }, "published_at": { "type": [ "string", "null" ], "format": "date-time" }, "latency_seconds": { "type": [ "integer", "null" ], "description": "SEC acceptance → analysis publication (seconds)" }, "page_url": { "type": [ "string", "null" ], "format": "uri" } } }, "publication": { "type": "object", "properties": { "id": { "type": "string", "example": "pub_9f2c41d07a6b13e8" }, "revision": { "type": "integer" }, "replaces": { "type": [ "string", "null" ] } }, "description": "Published version — id (version identifier) · revision (nth publication of this filing, from 1) · replaces (the previous version it replaced; null for the first). Webhooks only" } } } }, "description": "Event body — Standard Webhooks envelope (`id`, `type`, `timestamp`, `data`)", "required": [ "id", "type", "timestamp", "data" ] }, "WebhookRevokedEvent": { "type": "object", "properties": { "id": { "type": "string", "example": "evt_2077" }, "type": { "type": "string", "enum": [ "us_filing.analysis_revoked" ] }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "id": { "type": "string", "example": "CMS:0001104659-26-118972", "description": "Ticker:SEC accession number" }, "market": { "type": "string", "enum": [ "US" ] }, "symbol": { "type": "string", "example": "CMS" }, "cik": { "type": [ "string", "null" ], "example": "0000811156", "description": "SEC CIK (10 digits)" }, "accession": { "type": "string", "example": "0001104659-26-118972" }, "company": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "description": "Korean company name (English name when there is none)" }, "name_en": { "type": [ "string", "null" ] } } }, "form": { "type": "string", "enum": [ "8-K", "8-K/A", "6-K", "6-K/A", "10-Q", "10-Q/A", "10-K", "10-K/A", "20-F", "20-F/A", "40-F", "40-F/A" ] }, "amended": { "type": "boolean" }, "items": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "2.02", "description": "SEC 8-K item code — the event classification defined by the SEC" }, "label": { "type": [ "string", "null" ], "example": "실적 발표" }, "label_en": { "type": [ "string", "null" ], "example": "Results of Operations and Financial Condition" } } } }, "category": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "filed_date": { "type": "string", "format": "date" }, "report_date": { "type": [ "string", "null" ], "format": "date" }, "accepted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "SEC acceptance time (EDGAR acceptance). Null for older filings without a recorded time" }, "detected_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When Phoenix AI detected the filing and queued it for analysis. Null for filings outside live collection" }, "source_url": { "type": [ "string", "null" ], "format": "uri", "description": "SEC EDGAR original document" }, "analysis": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "published", "pending", "withheld", "unreadable_source", "not_analyzed" ], "description": "published · pending (queued or being analysed) · withheld (analysed but not published because verification failed; an automatic retry may still publish it) · unreadable_source (materials submitted only as images, or in an exhibit format not read yet such as PDF) · not_analyzed (outside the analysis scope). A point-in-time state that can change" }, "headline": { "type": [ "string", "null" ], "description": "Published one-line headline (Korean, AI-written and verified against the filing). Bodies are a PRO API feature" }, "headline_en": { "type": [ "string", "null" ], "description": "Headline of the published English translation, when there is one" }, "published_at": { "type": [ "string", "null" ], "format": "date-time" }, "latency_seconds": { "type": [ "integer", "null" ], "description": "SEC acceptance → analysis publication (seconds)" }, "page_url": { "type": [ "string", "null" ], "format": "uri" } } }, "revocation": { "type": "object", "properties": { "publication_id": { "type": "string" }, "published_at": { "type": "string", "format": "date-time" }, "revoked_at": { "type": "string", "format": "date-time" }, "replacement": { "type": [ "object", "null" ], "properties": { "publication_id": { "type": "string" }, "published_at": { "type": "string", "format": "date-time" } } } }, "description": "Withdrawal — publication_id (the withdrawn version) · published_at · revoked_at · replacement (a new version already public at send time, or null — a new version arrives separately as us_filing.analysis_published)" } } } }, "description": "Event body — Standard Webhooks envelope (`id`, `type`, `timestamp`, `data`)", "required": [ "id", "type", "timestamp", "data" ] }, "WebhookEarningsEvent": { "type": "object", "properties": { "id": { "type": "string", "example": "evt_2051" }, "type": { "type": "string", "enum": [ "us_earnings.figures" ] }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/UsEarningsRelease" } }, "description": "Event body — Standard Webhooks envelope (`id`, `type`, `timestamp`, `data`)", "required": [ "id", "type", "timestamp", "data" ] }, "ConsensusMetricAsOf": { "type": "object", "properties": { "metric": { "type": "string", "enum": [ "revenue", "operating_income" ], "description": "Korea: revenue, operating_income; US: revenue only" }, "name": { "type": "string" }, "currency": { "type": [ "string", "null" ], "enum": [ "KRW", "USD", null ] }, "unit": { "type": [ "string", "null" ], "enum": [ "KRW", "USD", "KRW_EOK", "KRW_MIL", "USD_MIL", null ], "description": "Unit of the amount fields (consensus, revisions.from, actual, consensus_at_report) — set by the unit parameter (default raw = KRW/USD as-is)" }, "unit_scale": { "type": "number", "description": "Size of 1 unit (raw 1, eok 1e8, million 1e6). Original amount = value × unit_scale" }, "consensus": { "type": "number", "description": "Market consensus (in unit)" }, "as_of": { "type": "string", "format": "date" }, "estimate_date": { "type": [ "string", "null" ], "format": "date" }, "revisions": { "type": "object", "properties": { "1w": { "type": [ "object", "null" ], "properties": { "from": { "type": [ "number", "null" ] }, "from_date": { "type": "string", "format": "date" }, "change_pct": { "type": [ "number", "null" ] } } }, "4w": { "type": [ "object", "null" ] }, "12w": { "type": [ "object", "null" ] } } }, "actual": { "type": [ "number", "null" ], "description": "Reported actual value (reported periods, in unit) — the official filing's value when one exists (actual_source)" }, "reported_on": { "type": [ "string", "null" ], "format": "date", "description": "Date the results were first made public (the US Eastern date of the 8-K acceptance time, the Korean preliminary-results filing date, etc.). Null if the source does not provide the report time (some US periods)" }, "actual_source": { "type": [ "object", "null" ], "description": "Official filing (DART, SEC) behind the actual value — null if none", "properties": { "kind": { "type": "string", "enum": [ "dart", "sec" ] }, "doc": { "type": "string" }, "id": { "type": "string", "description": "Receipt number" }, "url": { "type": [ "string", "null" ], "format": "uri" } } }, "consensus_at_report": { "type": [ "number", "null" ], "description": "Consensus just before the report (in unit; its basis is consensus_at_report_basis). Null if none" }, "consensus_at_report_date": { "type": [ "string", "null" ], "format": "date", "description": "Dated basis of the pre-report estimate; for reconstructed values this is the historical estimate date, not the later capture date." }, "consensus_at_report_basis": { "type": [ "string", "null" ], "enum": [ "observed", "captured", "provider", null ], "description": "Legacy date-evidence classification, preserved: observed = historical estimate with a dated basis before release; captured = captured before release; provider = identified as a pre-report estimate without a dated basis. observed does not assert when this service captured the value. Reconstruction is a separate dimension, given by consensus_at_report_reconstructed." }, "consensus_at_report_as_of": { "type": [ "string", "null" ], "format": "date", "description": "Optional report-comparison cutoff (day before release), including in latest responses. Does not change the latest consensus or its as_of; absent when no comparison cutoff is established." }, "consensus_at_report_source": { "type": [ "string", "null" ], "enum": [ "market_consensus", null ], "description": "Optional report-comparison source; null when no historical estimate is available." }, "consensus_at_report_reconstructed": { "type": [ "boolean", "null" ], "description": "Optional report-comparison provenance: true for reconstruction from dated estimates, false for a recorded observation, null when no historical estimate is available. This describes the acquisition/calculation method; basis describes date evidence, so observed and true can coexist without claiming a same-day capture." }, "vs_consensus_pct": { "type": [ "number", "null" ], "description": "(actual − consensus_at_report) ÷ |consensus_at_report| × 100. Null if consensus_at_report is absent" }, "comparison_status": { "type": "string", "enum": [ "compared", "basis_unconfirmed", "no_pre_report_estimate", "no_actual", "upcoming" ], "description": "compared = calculated; basis_unconfirmed = could not confirm that the estimate and the reported value share the same basis; no_pre_report_estimate = no consensus before the report date, or the report date (reported_on) is unknown; no_actual = reported period, but no actual value on the same basis; upcoming = not yet reported" }, "comparison_note": { "type": [ "string", "null" ], "description": "Reason vs_consensus_pct is null (human-readable sentence)" }, "observed_on": { "type": "string", "format": "date", "description": "Day this value was first observed (Korea-time calendar day, snapshot) — on or before as_of" }, "coverage_start": { "type": [ "string", "null" ], "format": "date", "description": "First observation of this item (same period, metric and aggregation) in the record. For a value recomputed before the record starts it can be later than as_of; null if never recorded" }, "reconstructed": { "type": "boolean", "description": "true = not a recorded value but a median recomputed from Korean broker reports published by as_of (dates before the record starts)" } }, "required": [ "observed_on", "coverage_start", "reconstructed" ] } } }, "paths": { "/": { "get": { "operationId": "getService", "tags": [ "Service" ], "summary": "Service descriptor", "x-summary-en": "Service descriptor", "x-markets": [], "description": "Name, version, documentation and spec URLs, and the endpoint list for this API.\n\n> 🔓 No API key required.", "security": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceDescriptor" }, "example": { "name": "Phoenix AI Data API", "version": "1.16.0", "description": "Global securities data API — company financials, ratios and growth, revenue segments, dividends, consensus, guidance and regulatory filings (DART, SEC) for companies listed in Korea and the US, with the source of every value.", "docs": "https://openapi.chickstockfi.com/docs", "openapi": "https://api.chickstockfi.com/openapi/v1/openapi.json", "servers": [ "https://api.chickstockfi.com/openapi/v1", "https://www.chickstockfi.com/openapi/v1" ], "auth": "Authorization: Bearer ck_live_… or X-API-Key: ck_live_…", "key_info": "GET /v1/key", "endpoints": [ "GET /v1/companies/{symbol}/financials" ], "mcp": { "url": "https://www.chickstockfi.com/openapi/pro/v1/mcp", "auth": "Authorization: Bearer ck_live_… (this Data API key)", "docs": "https://openapi.chickstockfi.com/docs/mcp", "note": "Remote MCP server (Streamable HTTP, JSON-RPC over POST) for Claude, ChatGPT, Cursor and other AI tools. Tools map 1:1 to these endpoints; each tool call counts as one Data API request (same quota, per-minute limit, PoC AI-call quota, plan and market checks)." } } } } }, "429": { "$ref": "#/components/responses/EdgeRateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/key": { "get": { "operationId": "getKeyInfo", "tags": [ "Service" ], "summary": "Plan, term and today's usage for this key", "x-summary-en": "Plan, term and today's usage for this key", "x-markets": [], "description": "Returns the plan of the API key used in the request (Free, PoC (Launch/Business/Scale), Launch, Business, Scale, Enterprise), its term (start, end, days remaining D-n), today's (KST) usage and remaining quota, the PoC AI call quota (`ai_quota`), and the per-minute rate limit. Checked with the API key alone, without logging in anywhere. Does not count toward the daily quota. Keys whose PoC has ended can still call this endpoint (`status: poc_ended`). On this endpoint, `X-RateLimit-Limit: 30` denotes a separate 60-second window per key. The body field `data.rate_limit.per_minute` is the plan limit for ordinary data endpoints.\n\n> 🔑 Works with a key of any plan (Free, PoC (Launch/Business/Scale), Launch, Business, Scale, Enterprise) and does not count toward the daily quota (30 calls per minute per key).", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Quota-Period": { "$ref": "#/components/headers/X-Quota-Period" }, "X-Quota-Reset": { "$ref": "#/components/headers/X-Quota-Reset" }, "X-Markets": { "$ref": "#/components/headers/X-Markets" }, "X-Plan": { "$ref": "#/components/headers/X-Plan" }, "X-Plan-Tier": { "$ref": "#/components/headers/X-Plan-Tier" }, "X-Plan-Expires": { "$ref": "#/components/headers/X-Plan-Expires" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyInfo" }, "example": { "data": { "key": { "id": 42, "prefix": "ck_live_ab12cd…", "name": "운영 서버", "created_at": "2026-10-21T01:00:00.000Z", "last_used_at": "2026-10-21T06:20:00.000Z", "kind": "standard", "expires_at": null }, "plan": "poc", "plan_tier": "launch", "plan_label": "PoC", "starts_at": "2026-10-21T01:00:00.000Z", "expires_at": "2026-11-04T01:00:00.000Z", "days_left": 14, "ended": null, "status": "active", "status_label": "PoC", "quota": { "limit": 2000, "used": 1234, "remaining": 766, "period": "2026-10-21", "reset_at": "2026-10-21T15:00:00.000Z" }, "ai_quota": { "limit": 20, "used": 12, "remaining": 8, "reset_at": "2026-10-21T15:00:00.000Z" }, "rate_limit": { "per_minute": 60 } }, "meta": { "as_of": "2026-10-21T06:30:00.000Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/openapi.json": { "get": { "operationId": "getOpenApiSpec", "tags": [ "Service" ], "summary": "This OpenAPI document", "x-summary-en": "This OpenAPI document", "x-markets": [], "description": "Returns this document as JSON. Developer portals and code generators load this URL.\n\n> 🔓 No API key required.", "security": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true }, "example": { "openapi": "3.1.0", "info": { "title": "Phoenix AI Data API", "version": "1.16.0" } } } } }, "429": { "$ref": "#/components/responses/EdgeRateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/companies/{symbol}/financials": { "get": { "operationId": "getCompanyFinancials", "tags": [ "Financial statements" ], "summary": "Financial statement line items (annual & quarterly)", "x-summary-en": "Financial statement line items (annual & quarterly)", "x-markets": [ "KR", "US" ], "x-market-scoped": true, "x-paginated": "cursor", "description": "Returns financial statement accounts by period for Korea (DART) and the US (SEC) — income statement (revenue, operating income, net income, EPS, etc.), balance sheet (assets, liabilities, equity), and cash flow.\n\nFor Korea, `discontinued_operations_income` is the total after-tax profit or loss, excluding owner/non-controlling attribution and per-share amounts. When reported, reconciliation uses pretax income minus income tax plus discontinued operations equals net income. A reported line with no confirmed amount withholds the affected derived quarters; it is never replaced with zero.\n\n- **Sort order**: fiscal year and quarter, newest first (within a year: annual, then Q4 down to Q1; cumulative rows come after the same quarter) → account (financial statement order; see the \"Account codes\" table) → consolidated (CFS) first → filing ledger first. Filing-ledger values and values filled from company IR materials are interleaved by the same rules regardless of source.\n- **Pagination**: `limit` (default 100, max 200) + `cursor`. If account and period are omitted, the entire ledger (every account, every period) is returned starting from the latest period, and the rest is fetched via `next_cursor` (`meta.total` = total number of rows). Rows are in `data.rows`.\n- **Account**: `account` accepts English codes (`revenue`, `operating_income`, `net_income` …; comma-separated for multiple) or Korean account names. English codes match exactly that account; Korean names match partially (e.g. `순이익` (net income) → 당기순이익 (net income) and 지배주주순이익 (net income attributable to owners of the parent)). Unknown English words return 400 `BAD_REQUEST`.\n- **Period**: Accepted: fiscal year FY2025 or 2025; quarter 2026Q2, FY2026 Q2 or Q2 2026; Korea-only year-to-date 2025H1 (= 2025YTDQ2) or 2025YTDQ3; latest_quarter, annual, quarterly. Korean forms (2025 연간 (annual), 2026 2분기 (Q2), 2025 반기 누적 (H1 year-to-date)) are also accepted. Any other value returns 400 `BAD_PERIOD`. The `period_code` from a response can be passed as-is.\n- **Periods filled from company IR materials**: filing-ledger values take precedence; only periods with no filing-ledger row at all (matched by period end date) are filled from company IR materials, for revenue, operating income, net income, total liabilities, total equity, current assets, and current liabilities (`source` = 기업 IR 자료 (company IR materials); `report`, `report_code`, `filed_date`, and `source_url` are null — these are not filings, so there is no link or filing date; `period_end` is the period end date when the fiscal year-end month is known). As a result, periods filled from IR materials may contain **only some of these accounts** (`meta.partner_filled_periods`, `partner_filled_accounts`). IR rows are not included with `fs=OFS` (they are consolidated figures).\n- **Fiscal calendar**: `fiscal_year` is the year in which the fiscal year ends, and `fiscal_quarter` is the quarter within that fiscal year (for a March year-end company, April–June 2026 = `2027Q1`). Every row carries `period_start`, `period_end`, and `fiscal_year_end_month`. For companies whose fiscal year does not end in December, DART rows and company IR rows are placed on the same fiscal calendar by period end date, so each quarter appears once. The fiscal year-end month and its evidence are in `meta.fiscal_calendar` (fy_end_month, source, unplaced_rows).\n- **Consolidated vs. separate**: if `fs` is omitted, each company and period uses consolidated statements first and separate statements for periods without consolidated statements (`fs_code` on every row, `meta.fs_codes`). `fs=CFS` returns consolidated only; `fs=OFS` returns separate statements only (including the separate statements of companies that also file consolidated statements, such as holding companies — only companies and periods that have been loaded).\n- Korean quarterly values cover the 3 months of that quarter (income statement) or the quarter-end balance (balance sheet). Q2, Q3, and Q4 income statement values are differences between cumulative filed values of the same fiscal year (`derivation`).\n- US quarters follow the company's fiscal calendar (including January/February fiscal year-ends and 52/53-week years; see `period_end`). Q4 income statement and cash flow values = annual (10-K) minus the Q1–Q3 cumulative (10-Q); `derivation` carries the formula and the accession numbers of the filings used. Q4 balance sheet values are the fiscal year-end balances.\n- **Withheld quarters**: when a quarter derived from two cumulative filings fails a check (only one of the two filings restated its prior-year comparatives, a cumulative total that cannot shrink went down, a definition breaks only in the derived quarter, there is no evidence that the two filings belong to the same fiscal year, or the two cumulative periods do not end three months apart), that quarter has no row and is listed in `meta.unconfirmed_quarters` (account_code, period_code, fs_code, reason) with an English `meta.unconfirmed_note`.\n- **Delisted companies**: delisted Korean companies are returned when a filing ledger is stored, with `meta.listing_status` (listed, suspended, delisting, inactive, delisted, unknown — the same values as the `/symbols` master; delisted needs filing evidence) and `meta.delisted_on` (confirmed delisting date, otherwise null) and `meta.listing_evidence` (last exchange filing within a bounded scan window; not a delisting date). Without a stored ledger the response is 404 `NOT_FOUND` with the reason.\n- For Korean symbols, querying net income or EPS-related accounts, or omitting the account, also returns `net_income_split` (owners of the parent, consolidated total, non-controlling interests).\n- **Units and precision**: `value` is in the display unit (`unit` — KRW 100 million or USD millions) rounded to an integer, so small amounts (a small cap's finance costs or operating income) can be 0. Compute with `value_raw` (the unrounded value in the original unit — KRW, USD or shares; see `raw_unit`). Original amount = `value` × `unit_scale`.\n- **Preferred shares**: a preferred-share code (e.g. 005935) returns the financials of the issuer's common share (005930) — `data.issuer_symbol`, `meta.issuer_symbol`.\n- URL-encode Korean values: `curl -G \"$BASE/companies/005930/financials\" --data-urlencode \"account=매출액\" --data-urlencode \"period=2025 연간\"`.\n- **Missing accounts**: already stored full filings supply missing summary-ledger accounts from their current cumulative columns, without external refetches. Missing values are listed in meta.unconfirmed_quarters: current_account_missing (account absent in this period), missing_cumulative (current cumulative amount absent), missing_prior_cumulative (previous cumulative amount absent), or cumulative_basis_unconfirmed (cumulative basis not proven). An account-only request returns HTTP 200, empty data.rows and an English meta.unconfirmed_note when it has an unconfirmed quarter.\n\n> Markets: KR · US · Pagination: cursor + limit\n\n> 🔒 **Paid tiers only** (Launch, Business, Scale, Enterprise; PoC included) — Free keys and accounts whose paid-tier term has ended receive 403 `PLAN_REQUIRED`; accounts whose PoC has ended receive 403 `POC_ENDED`.\n\n> 🌐 **Data coverage** — the account receives data only for the markets it has contracted. A market outside the contract (symbol or `market`) returns 403 `MARKET_NOT_ENTITLED` before any limit is counted; Japan (`JP`) and China (`CN`) return 400 `MARKET_NOT_AVAILABLE` (coming soon). For POST /query, authentication applies first; if every line is outside the contract, it returns 403 with zero per-minute, ordinary daily and AI calls. A storage failure or timeout during key, plan, company or market resolution returns HTTP 503 `UNAVAILABLE` with zero per-minute, ordinary daily and AI calls, without falling back to Free. Otherwise it returns HTTP 200 with per-line errors and counts as one ordinary call.", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "symbol", "in": "path", "required": true, "description": "Korean 6-digit symbol code (005930) or US ticker (AAPL)", "schema": { "type": "string", "example": "005930" } }, { "name": "market", "in": "query", "required": false, "description": "Optional — the market is determined by the symbol code (Korean 6-digit code or US ticker). If given, verifies that the symbol belongs to that market (otherwise 400 BAD_SYMBOL).", "schema": { "type": "string", "enum": [ "KR", "US" ] } }, { "name": "account", "in": "query", "required": false, "description": "Account — English code (revenue, operating_income, net_income, etc.; see the \"Account codes\" table) or Korean account name; comma-separated for multiple. All accounts if omitted", "schema": { "type": "string", "maxLength": 200, "example": "revenue,operating_income" } }, { "name": "period", "in": "query", "required": false, "description": "Period — FY2025 or 2025 (annual); 2026Q2 or FY2026 Q2 (quarterly); 2025H1 or 2025YTDQ3 (Korea year-to-date); latest_quarter, annual, quarterly. Korean forms (2025 연간, 2026 2분기) are also accepted. Anything else returns 400 BAD_PERIOD", "schema": { "type": "string", "maxLength": 20, "example": "FY2025" } }, { "name": "fs", "in": "query", "required": false, "description": "Statement type — CFS (consolidated only, including rows from company IR materials) or OFS (separate only, Korea — including the separate statements of companies that also file consolidated statements, such as holding companies; no IR rows). If omitted, consolidated first for each company and period, separate for periods without consolidated statements", "schema": { "type": "string", "enum": [ "CFS", "OFS" ] } }, { "name": "cursor", "in": "query", "required": false, "description": "Next page — pass the previous response's next_cursor as-is, with the same filters. Omit for the first page", "schema": { "type": "string", "maxLength": 2100, "example": "c1.eyJrIjpbIjIwMjYtMTAtMjAiLCIyMDI2MTAyMDAwMDEyMyJdLCJmIjoiQWJDZEVmR2hJaksifQ" } }, { "name": "limit", "in": "query", "required": false, "description": "Items per page (1–200, default 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Quota-Period": { "$ref": "#/components/headers/X-Quota-Period" }, "X-Quota-Reset": { "$ref": "#/components/headers/X-Quota-Reset" }, "X-Markets": { "$ref": "#/components/headers/X-Markets" }, "X-Plan": { "$ref": "#/components/headers/X-Plan" }, "X-Plan-Tier": { "$ref": "#/components/headers/X-Plan-Tier" }, "X-Plan-Expires": { "$ref": "#/components/headers/X-Plan-Expires" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "symbol": { "type": "string", "description": "Requested symbol" }, "issuer_symbol": { "type": "string", "description": "Issuer whose financials were read (for a preferred share, the common share — 005935 → 005930)" }, "name": { "type": [ "string", "null" ] }, "market": { "type": "string", "enum": [ "KR", "US" ] }, "currency": { "type": "string", "enum": [ "KRW", "USD" ] }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/FinancialRow" } }, "net_income_split": { "type": "array", "items": { "$ref": "#/components/schemas/NetIncomeSplitRow" } } } }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page — null if there are no more pages" }, "has_more": { "type": "boolean", "description": "Whether there is a next page" }, "meta": { "type": "object", "properties": { "trade_evidence_reason": { "type": "string", "enum": [ "trade_evidence_unavailable" ] }, "symbol": { "type": "string" }, "market": { "type": "string", "enum": [ "KR", "US" ] }, "as_of": { "type": "string", "format": "date-time" }, "page_url": { "type": "string", "format": "uri" }, "disclaimer": { "type": "string" }, "unit_note": { "type": "string" }, "note": { "type": "string" }, "count": { "type": "integer" }, "fs_requested": { "type": [ "string", "null" ], "enum": [ "CFS", "OFS", null ], "description": "The requested fs (null if omitted)" }, "fs_codes": { "type": "array", "items": { "type": "string", "enum": [ "CFS", "OFS" ] }, "description": "Statement types present in the returned rows" }, "fiscal_year_end_month": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 12, "description": "Fiscal year-end month (1–12; null if unknown)" }, "fiscal_calendar": { "type": "object", "properties": { "fy_end_month": { "type": [ "integer", "null" ], "description": "Fiscal year-end month" }, "source": { "type": "string", "enum": [ "filings", "listing", "reports", "unknown", "sec" ], "description": "filings = month of the latest annual report in the filing ledger; listing = fiscal year-end month in the listed-company directory; reports = report titles of the rows; sec = SEC fiscal calendar; unknown = not known (labels as filed, dates null)" }, "label_convention": { "type": "string", "enum": [ "fiscal_year_end", "filing_year" ], "description": "fiscal_year_end = periods are named by the year in which the fiscal year ends; filing_year = the fiscal year-end month is unknown, so the year in the filing label is kept" }, "unplaced_rows": { "type": "integer", "description": "Number of ledger rows left out because their evidence conflicts (filed before the period ended, or the report month does not match the fiscal year-end month)" } } }, "fiscal_note": { "type": "string", "description": "Explanation of the fiscal calendar rules (English)" }, "unconfirmed_quarters": { "type": "array", "items": { "type": "object", "properties": { "account": { "type": "string" }, "account_code": { "type": [ "string", "null" ] }, "period": { "type": "string" }, "period_code": { "type": [ "string", "null" ] }, "fs_code": { "type": [ "string", "null" ] }, "reason": { "type": "string", "enum": [ "negative_balance", "invalid_amount", "basis_mismatch", "cumulative_decrease", "relationship_violation", "tax_identity_violation", "quarter_inconsistent", "quarter_basis_inconsistent", "fiscal_period_unresolved", "fiscal_year_mismatch", "current_account_missing", "prior_cumulative_missing", "missing_cumulative", "missing_prior_cumulative", "cumulative_basis_unconfirmed" ] } } } }, "unconfirmed_note": { "type": "string", "description": "Reasons for withheld accounts, including empty account-only responses: negative_balance (nonnegative balance reported below zero), invalid_amount (non-finite value). unconfirmed_quarters also includes annual/cumulative periods for compatibility." }, "preliminary_enrichment": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "unavailable" ] }, "reason": { "type": "string", "enum": [ "preliminary_data_unavailable" ] }, "note": { "type": "string" } }, "description": "Present only when preliminary earnings enrichment fails. Base financial statement data is preserved." }, "preliminary_releases": { "type": "array", "items": { "type": "object", "properties": { "rcept_no": { "type": "string" }, "filed_date": { "type": "string", "format": "date" }, "period": { "type": [ "string", "null" ], "example": "2026년 3분기" }, "period_code": { "type": "string", "example": "2026Q3" }, "period_type": { "type": "string", "enum": [ "quarter", "annual" ] }, "fs_code": { "type": [ "string", "null" ], "enum": [ "CFS", "OFS", null ] }, "amended": { "type": "boolean" }, "precision_won": { "type": [ "number", "null" ] }, "values": { "type": "array", "items": { "type": "object", "properties": { "account_code": { "type": "string", "enum": [ "revenue", "operating_income", "net_income" ] }, "value_raw": { "type": "number" }, "yoy_pct": { "type": [ "number", "null" ] }, "turnaround": { "type": [ "string", "null" ], "enum": [ "흑자전환", "적자전환", "적자지속", null ] } } } }, "surprise": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "metric": { "type": "string" }, "name": { "type": "string" }, "basis": { "type": "string" }, "actual": { "type": "object", "properties": { "value": { "type": "number" }, "text": { "type": [ "string", "null" ] } } }, "consensus": { "type": "object", "properties": { "value": { "type": "number" }, "text": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "observed_on": { "type": [ "string", "null" ], "format": "date" }, "as_of_basis": { "type": "string" } } }, "surprise_pct": { "type": "number" } } } }, "flash": { "type": [ "object", "null" ], "properties": { "headline": { "type": "string" }, "text": { "type": "string" }, "lines": { "type": "array", "items": { "type": "string" } } } }, "source_url": { "type": [ "string", "null" ], "format": "uri" } } }, "description": "Each Korean preliminary earnings release behind preliminary=true rows — value_raw (KRW as filed) · yoy_pct (the filed change checked against the amounts) · turnaround (instead of a percentage when the sign changed: 흑자전환 turned profitable · 적자전환 turned to a loss · 적자지속 loss in both periods) · surprise (vs the last pre-release consensus when the release is the actual; null when not computed) · flash (Korean summary built by code, not AI)" }, "preliminary_releases_note": { "type": "string" }, "listing_status": { "type": "string", "enum": [ "listed", "suspended", "delisting", "inactive", "delisted", "unknown" ], "description": "Korean listing status (the same values as the /symbols master) — listed (traded on the latest trading day); suspended (reported trading halt); delisting (liquidation trading before delisting); inactive (no recent trading record — delisting is not asserted); delisted (not listed now according to DART, with evidence that it was listed when it filed); unknown (no evidence)" }, "delisted_on": { "type": [ "string", "null" ], "format": "date", "description": "Confirmed delisting date only; null when unconfirmed. See listing_evidence for the bounded scan evidence." }, "listing_evidence": { "type": "object", "properties": { "source": { "type": "string" }, "date_kind": { "type": "string" }, "observed_on": { "type": [ "string", "null" ] }, "window_from": { "type": [ "string", "null" ] }, "window_to": { "type": [ "string", "null" ] }, "note": { "type": "string" } }, "description": "Bounded scan evidence, not a confirmed delisting date." }, "last_trading_day": { "type": [ "string", "null" ], "format": "date", "description": "Latest positive-volume trade date, including newer intraday observations" } }, "description": "Financial statement metadata — common fields plus fiscal calendar, consolidated/separate, and listing status (partner_filled_*, unconfirmed_quarters, and other fields may also be present).", "additionalProperties": true } }, "required": [ "data", "next_cursor", "has_more", "meta" ] }, "example": { "data": { "symbol": "005930", "issuer_symbol": "005930", "name": "삼성전자", "market": "KR", "currency": "KRW", "rows": [ { "account": "매출액", "account_code": "revenue", "fiscal_year": 2026, "fiscal_quarter": 2, "period": "2026 2분기", "period_code": "2026Q2", "period_type": "quarter", "period_start": "2026-04-01", "period_end": "2026-06-30", "fiscal_year_end_month": 12, "fs": "CFS", "fs_code": "CFS", "value": 745663, "unit": "억원", "unit_code": "KRW_EOK", "unit_scale": 100000000, "value_raw": 74566312345678, "raw_unit": "KRW", "basis": "3개월", "derivation": "반기 누적 − 1분기(누적 공시 값의 차이)", "source": "DART", "report": "반기보고서 (2026.06)", "report_code": "half_year_report", "filed_date": "2026-08-14", "source_url": "https://dart.fss.or.kr/dsaf001/main.do?rcpNo=20260814000987" }, { "account": "매출액", "account_code": "revenue", "fiscal_year": 2025, "fiscal_quarter": null, "period": "2025 연간", "period_code": "FY2025", "period_type": "annual", "period_start": "2025-01-01", "period_end": "2025-12-31", "fiscal_year_end_month": 12, "fs": "CFS", "fs_code": "CFS", "value": 3008709, "unit": "억원", "unit_code": "KRW_EOK", "unit_scale": 100000000, "value_raw": 300870904000000, "raw_unit": "KRW", "basis": null, "derivation": null, "source": "DART", "report": "사업보고서 (2025.12)", "report_code": "annual_report", "filed_date": "2026-03-11", "source_url": "https://dart.fss.or.kr/dsaf001/main.do?rcpNo=20260311001234" } ] }, "next_cursor": "c1.eyJrIjpbIjIwMjYtMTAtMjAiLCIyMDI2MTAyMDAwMDEyMyJdLCJmIjoiQWJDZEVmR2hJaksifQ", "has_more": true, "meta": { "symbol": "005930", "market": "KR", "as_of": "2026-10-21T06:30:00.000Z", "page_url": "https://www.chickstockfi.com/stocks/005930", "disclaimer": "공식 공시(DART·SEC)와 회사 IR 자료를 바탕으로 Phoenix AI가 정리·계산한 참고 자료입니다. 투자 권유가 아니며 정확성·완전성을 보장하지 않습니다.", "issuer_symbol": "005930", "share_class": "common", "count": 2, "total": 1480, "limit": 2, "unit_note": "국내 금액 억원(KRW 1e8) · 미국 금액 백만달러(USD 1e6) · 주당 값은 원·달러 · 비율·성장률은 %. value는 표시 단위로 반올림한 값 — 계산에는 value_raw", "fs_requested": null, "fs_codes": [ "CFS" ], "fiscal_year_end_month": 12, "fiscal_calendar": { "fy_end_month": 12, "source": "filings", "label_convention": "fiscal_year_end", "unplaced_rows": 0 }, "listing_status": "listed", "delisted_on": null, "last_trading_day": "2026-10-21" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequiredOrMarket" }, "404": { "description": "No financial statements — NOT_FOUND (the symbol exists but the requested data or period does not); SYMBOL_NOT_FOUND (symbol unknown to Phoenix AI); NOT_APPLICABLE (fund-type products such as ETFs and ETNs, for which company data does not apply)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "NOT_FOUND": { "value": { "error": { "code": "NOT_FOUND", "message": "No financial statements found. Check account and period.", "docs": "https://openapi.chickstockfi.com/docs" } } }, "SYMBOL_NOT_FOUND": { "value": { "error": { "code": "SYMBOL_NOT_FOUND", "message": "Unknown symbol 'ZZZZZZ'. Use a listed Korean 6-character code (e.g. 005930) or a US-listed ticker (e.g. AAPL).", "docs": "https://openapi.chickstockfi.com/docs" } } }, "NOT_APPLICABLE": { "value": { "error": { "code": "NOT_APPLICABLE", "message": "069500 is a fund-type security (ETF/ETN); company financials … do not apply.", "docs": "https://openapi.chickstockfi.com/docs" } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/companies/{symbol}/metrics": { "get": { "operationId": "getCompanyMetrics", "tags": [ "Metrics & growth" ], "summary": "Ratios, valuation and growth (CAGR, YoY, QoQ)", "x-summary-en": "Ratios, valuation and growth (CAGR, YoY, QoQ)", "x-markets": [ "KR", "US" ], "x-market-scoped": true, "description": "Returns financial ratios (growth, profitability, efficiency, stability, cash quality), valuation (market cap, PER, PBR, PSR, EPS, BPS, ROE, dividends — based on market prices), and a growth rate table.\n\n- `growth`: for each of revenue, operating income, and net income — year-over-year change by year (`annual_yoy`), N-year compound annual growth rate (`cagr`, `cagr_years`), quarterly year-over-year change (`quarterly_yoy`), and quarter-over-quarter change (`quarterly_qoq`).\n- Filing ledger first; only years or quarters missing from the ledger come from company IR materials (`source` = '기업 IR 자료' (company IR materials)). If the base is a loss or 0, `change` ('흑자전환' (turned to profit), '적자전환' (turned to loss), '적자지속' (loss continued)) is returned instead of `change_pct`.\n- **One valuation definition**: `valuation` is the same calculation as `data.valuation` in `/quotes/{symbol}` (including PER, PBR, EPS, BPS and DPS in the legacy `fundamentals`), the PRO API and the Phoenix AI stock page. Korean PER = market cap ÷ consolidated net income attributable to **owners of the parent** over the last four quarters (TTM; the latest fiscal year if no TTM) (`eps_basis`, `eps_period`, `basis`). EPS and BPS = that net income and equity attributable to owners ÷ this stock's listed common shares (`shares_basis` = `common_listed` — treasury shares included, preferred shares excluded; derived from live market cap ÷ price, so stock splits and consolidations apply immediately; it can differ from the basic EPS in the annual report, which uses weighted-average shares outstanding excluding treasury shares, and the gap grows with the treasury share count). The price used and its date are `price` and `price_as_of`. PER is negative for loss-making companies.\n- **Dividends**: `valuation.dividend.dps` is the fiscal-year dividend per share from the annual report restated to today's share basis (`dps_basis` = `annual_current_share`, `fiscal_year`, the as-filed `dps_reported`, the restatement factor `share_factor`). Yield = dps ÷ `price`.\n- **Preferred shares** (e.g. 005935, 005385, 000815): financials, ratios and growth are the issuer's common-share values (`meta.issuer_symbol`); EPS and BPS are per issuer common share; PER and PBR = preferred price ÷ that EPS and BPS (`per_basis` = `preferred_price_over_issuer_eps`, `shares_basis` = `issuer_common_listed`); market cap and dividends are the preferred share's own. PSR is null (reason in `share_class.holds`).\n- Korean responses include `net_income_split` (owners of the parent, consolidated total, non-controlling interests).\n- For financial and real estate companies, general ratios do not apply, so `ratios.ratio_policy.applies = false` is returned along with the reason.\nWhen annual filing DPS is absent, the latest completed calendar-year payments may be used with dps_basis=annual_payments_current_share. TTM is a separate field.\n\n\n> Markets: KR · US\n\n> 🔒 **Paid tiers only** (Launch, Business, Scale, Enterprise; PoC included) — Free keys and accounts whose paid-tier term has ended receive 403 `PLAN_REQUIRED`; accounts whose PoC has ended receive 403 `POC_ENDED`.\n\n> 🌐 **Data coverage** — the account receives data only for the markets it has contracted. A market outside the contract (symbol or `market`) returns 403 `MARKET_NOT_ENTITLED` before any limit is counted; Japan (`JP`) and China (`CN`) return 400 `MARKET_NOT_AVAILABLE` (coming soon). For POST /query, authentication applies first; if every line is outside the contract, it returns 403 with zero per-minute, ordinary daily and AI calls. A storage failure or timeout during key, plan, company or market resolution returns HTTP 503 `UNAVAILABLE` with zero per-minute, ordinary daily and AI calls, without falling back to Free. Otherwise it returns HTTP 200 with per-line errors and counts as one ordinary call.", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "symbol", "in": "path", "required": true, "description": "Korean 6-digit symbol code (005930) or US ticker (AAPL)", "schema": { "type": "string", "example": "005930" } }, { "name": "market", "in": "query", "required": false, "description": "Optional — the market is determined by the symbol code (Korean 6-digit code or US ticker). If given, verifies that the symbol belongs to that market (otherwise 400 BAD_SYMBOL).", "schema": { "type": "string", "enum": [ "KR", "US" ] } }, { "name": "cagr_years", "in": "query", "required": false, "description": "Number of years for CAGR (1–10, default 3)", "schema": { "type": "integer", "minimum": 1, "maximum": 10, "default": 3 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Quota-Period": { "$ref": "#/components/headers/X-Quota-Period" }, "X-Quota-Reset": { "$ref": "#/components/headers/X-Quota-Reset" }, "X-Markets": { "$ref": "#/components/headers/X-Markets" }, "X-Plan": { "$ref": "#/components/headers/X-Plan" }, "X-Plan-Tier": { "$ref": "#/components/headers/X-Plan-Tier" }, "X-Plan-Expires": { "$ref": "#/components/headers/X-Plan-Expires" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "symbol": { "type": "string" }, "market": { "type": "string", "enum": [ "KR", "US" ] }, "ratios": { "type": [ "object", "null" ], "properties": { "symbol": { "type": "string", "description": "Symbol whose financials were read (for a preferred share, the issuer's common share)" }, "unit": { "type": "string", "enum": [ "KRW_EOK", "USD_MIL" ] }, "unit_scale": { "type": "number", "enum": [ 100000000, 1000000 ], "description": "Original amount = net_debt / op_cf × unit_scale" }, "fiscal_year": { "type": [ "integer", "null" ] }, "years": { "type": "array", "items": { "type": "integer" } }, "balance_sheet_basis": { "type": [ "object", "null" ], "description": "Reference point for balance sheet ratios", "properties": { "label": { "type": "string" }, "kind": { "type": "string" } } }, "growth": { "type": "object", "properties": { "rev_cagr_3y": { "type": [ "number", "null" ] }, "op_cagr_3y": { "type": [ "number", "null" ] }, "rev_yoy": { "type": [ "number", "null" ] }, "ni_yoy": { "type": [ "number", "null" ] }, "ni_swing": { "type": [ "string", "null" ] } } }, "profitability": { "type": "object", "properties": { "op_margin": { "type": [ "number", "null" ] }, "net_margin": { "type": [ "number", "null" ] }, "gross_margin": { "type": [ "number", "null" ] }, "op_margin_delta_pp": { "type": [ "number", "null" ] } } }, "efficiency": { "type": "object", "properties": { "receivable_turnover": { "type": [ "number", "null" ] }, "inventory_turnover": { "type": [ "number", "null" ] } } }, "stability": { "type": "object", "properties": { "debt_ratio": { "type": [ "number", "null" ] }, "current_ratio": { "type": [ "number", "null" ] }, "net_debt": { "type": [ "number", "null" ] }, "interest_coverage": { "type": [ "number", "null" ] }, "short_debt_yoy": { "type": [ "number", "null" ] } } }, "cash_quality": { "type": "object", "properties": { "op_cf_to_ni": { "type": [ "number", "null" ] }, "op_cf": { "type": [ "number", "null" ], "description": "Cash flow from operating activities (in unit — integer KRW 100 million or USD millions)" }, "op_cf_raw": { "type": [ "number", "null" ], "description": "Cash flow from operating activities, unrounded, in the original unit (KRW or USD)" } } }, "ratio_policy": { "type": "object", "properties": { "applies": { "type": [ "boolean", "null" ] }, "reason": { "type": [ "string", "null" ] }, "sector": { "type": [ "string", "null" ] } } }, "signals": { "type": "array", "items": { "type": "object", "properties": { "tone": { "type": "string" }, "text": { "type": "string" } } } } } }, "valuation": { "oneOf": [ { "$ref": "#/components/schemas/Valuation" }, { "type": "null" } ] }, "growth": { "type": "array", "items": { "$ref": "#/components/schemas/GrowthTable" } }, "net_income_split": { "type": [ "object", "null" ], "properties": { "annual": { "type": "array", "items": { "$ref": "#/components/schemas/NetIncomeSplitRow" } }, "quarterly": { "type": "array", "items": { "$ref": "#/components/schemas/NetIncomeSplitRow" } } } } } }, "meta": { "type": "object", "properties": { "symbol": { "type": "string" }, "market": { "type": "string", "enum": [ "KR", "US" ] }, "as_of": { "type": "string", "format": "date-time" }, "page_url": { "type": "string", "format": "uri" }, "disclaimer": { "type": "string" }, "unit_note": { "type": "string" }, "note": { "type": "string" }, "count": { "type": "integer" }, "issuer_symbol": { "type": "string", "example": "005930", "description": "Symbol whose company-level data (filings, ownership, insiders, treasury stock, financials, consensus …) was read — for Korean preferred shares (e.g. 005935, 005385, 000815) the issuer's common share (005930, 005380, 000810); otherwise the requested symbol" }, "share_class": { "type": [ "string", "null" ], "enum": [ "common", "preferred", null ], "description": "Korean share class — common or preferred. Null for US symbols (not determined)" }, "issuer_note": { "type": "string", "description": "Preferred shares only — note that company-level data is the issuer's" }, "trade_evidence_reason": { "type": "string", "enum": [ "trade_evidence_unavailable" ] }, "listing_status": { "type": "string", "enum": [ "listed", "suspended", "delisting", "inactive", "delisted", "unknown" ], "description": "Listing and trading status of a Korean symbol (the same decision as data.status.status of /quotes/{symbol}). Absent for US symbols" } }, "description": "Common metadata for company endpoints (each endpoint adds more fields, such as note and unit_note).", "additionalProperties": true } }, "required": [ "data", "meta" ] }, "example": { "data": { "symbol": "005930", "market": "KR", "ratios": { "symbol": "005930", "unit": "KRW_EOK", "unit_scale": 100000000, "fiscal_year": 2025, "years": [ 2022, 2023, 2024, 2025 ], "balance_sheet_basis": null, "growth": { "rev_cagr_3y": 3.1, "op_cagr_3y": -12.4, "rev_yoy": 0.4, "ni_yoy": 6.2, "ni_swing": null }, "profitability": { "op_margin": 10.9, "net_margin": 11.4, "gross_margin": 38.2, "op_margin_delta_pp": -0.2 }, "efficiency": { "receivable_turnover": 6.7, "inventory_turnover": 4.2 }, "stability": { "debt_ratio": 27.1, "current_ratio": 243.5, "net_debt": -891234, "interest_coverage": 55.2, "short_debt_yoy": -8.1 }, "cash_quality": { "op_cf_to_ni": 1.9, "op_cf": 652341, "op_cf_raw": 65234112345678 }, "ratio_policy": { "applies": true, "reason": null, "sector": null }, "signals": [ { "tone": "positive", "text": "순현금 상태입니다." } ] }, "valuation": { "market_cap": 13066433, "market_cap_unit": "KRW_EOK", "market_cap_unit_scale": 100000000, "market_cap_raw": 1306643268888000, "as_of": "20261021", "price": 223500, "price_as_of": "2026-10-21T06:30:00.000Z", "price_date": "2026-10-21", "price_time": "2026-10-21T06:30:00.000Z", "period": "최근 4개 분기(2026 반기 TTM)", "basis": "ttm", "per": 8.73, "pbr": 2.76, "psr": 2.69, "eps": 25601, "bps": 81071, "roe": 31.6, "eps_basis": "controlling", "eps_shares": 5846278608, "eps_period": "최근 4개 분기(2026 반기 TTM)", "shares_basis": "common_listed", "per_basis": "market_cap_over_net_income", "share_class": null, "dividend": { "dps": 1668, "yield": 0.75, "payout": 25.1, "years": 4, "currency": "KRW", "dps_basis": "annual_current_share", "fiscal_year": 2025, "dps_reported": 1668, "share_factor": 1, "yield_basis": "annual", "ttm_dps": 1668, "ttm_yield": 0.75 } }, "growth": [ { "account": "revenue", "account_name": "매출액", "annual_yoy": [ { "period": "2025 연간", "period_code": "FY2025", "value": 3008709, "unit": "억원", "unit_code": "KRW_EOK", "unit_scale": 100000000, "source": "DART", "prior_period": "2024 연간", "prior_value": 2995300, "change_pct": 0.45, "change": null, "change_detail": null } ], "cagr": { "from": "2022 연간", "to": "2025 연간", "years": 3, "requested_years": 3, "start_value": 3022314, "end_value": 3008709, "unit": "억원", "unit_code": "KRW_EOK", "unit_scale": 100000000, "pct": -0.15, "change": null, "formula": "(3008709 ÷ 3022314)^(1/3) − 1", "note": null }, "quarterly_yoy": [], "quarterly_qoq": [], "partner_filled_periods": [] } ], "net_income_split": { "annual": [], "quarterly": [] } }, "meta": { "symbol": "005930", "market": "KR", "as_of": "2026-10-21T06:30:00.000Z", "page_url": "https://www.chickstockfi.com/stocks/005930", "disclaimer": "공식 공시(DART·SEC)와 회사 IR 자료를 바탕으로 Phoenix AI가 정리·계산한 참고 자료입니다. 투자 권유가 아니며 정확성·완전성을 보장하지 않습니다.", "issuer_symbol": "005930", "share_class": "common", "cagr_years": 3, "excluded": [ "forward_per", "consensus", "target_price" ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequiredOrMarket" }, "404": { "description": "No financial data — NOT_FOUND (the symbol exists but the requested data or period does not); SYMBOL_NOT_FOUND (symbol unknown to Phoenix AI); NOT_APPLICABLE (fund-type products such as ETFs and ETNs, for which company data does not apply)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "NOT_FOUND": { "value": { "error": { "code": "NOT_FOUND", "message": "No financial statements to compute ratios from.", "docs": "https://openapi.chickstockfi.com/docs" } } }, "SYMBOL_NOT_FOUND": { "value": { "error": { "code": "SYMBOL_NOT_FOUND", "message": "Unknown symbol 'ZZZZZZ'. Use a listed Korean 6-character code (e.g. 005930) or a US-listed ticker (e.g. AAPL).", "docs": "https://openapi.chickstockfi.com/docs" } } }, "NOT_APPLICABLE": { "value": { "error": { "code": "NOT_APPLICABLE", "message": "069500 is a fund-type security (ETF/ETN); company financials … do not apply.", "docs": "https://openapi.chickstockfi.com/docs" } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/companies/{symbol}/segments": { "get": { "operationId": "getCompanySegments", "tags": [ "Revenue mix" ], "summary": "Revenue mix by segment, product and geography", "x-summary-en": "Revenue mix by segment, product and geography", "x-markets": [ "KR", "US" ], "x-market-scoped": true, "description": "Revenue mix — for each axis (business segment, product, service, major product, region): item, share (%), and amount.\n\n- Korea: DART annual reports (XBRL notes, major products table). For listed companies that have not yet filed an annual report, registration statements and prospectuses (`prospectus=true`). If official filings have no breakdown, only the shares from company IR materials (`source` = 기업 IR 자료 (company IR materials), no amounts).\n- US: revenue by segment, product, and region from SEC 10-K XBRL (only axes that reconcile to the total). If the latest 10-Q is newer, `quarter` (3 months) is returned separately.\n- Do not add values across axes. `adjustments` (consolidation adjustments) are not share items, and `excluded_subtotals` are higher-level totals that overlap with their sub-items.\n\n> Markets: KR · US\n\n> 🔒 **Paid tiers only** (Launch, Business, Scale, Enterprise; PoC included) — Free keys and accounts whose paid-tier term has ended receive 403 `PLAN_REQUIRED`; accounts whose PoC has ended receive 403 `POC_ENDED`.\n\n> 🌐 **Data coverage** — the account receives data only for the markets it has contracted. A market outside the contract (symbol or `market`) returns 403 `MARKET_NOT_ENTITLED` before any limit is counted; Japan (`JP`) and China (`CN`) return 400 `MARKET_NOT_AVAILABLE` (coming soon). For POST /query, authentication applies first; if every line is outside the contract, it returns 403 with zero per-minute, ordinary daily and AI calls. A storage failure or timeout during key, plan, company or market resolution returns HTTP 503 `UNAVAILABLE` with zero per-minute, ordinary daily and AI calls, without falling back to Free. Otherwise it returns HTTP 200 with per-line errors and counts as one ordinary call.", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "symbol", "in": "path", "required": true, "description": "Korean 6-digit symbol code (005930) or US ticker (AAPL)", "schema": { "type": "string", "example": "005930" } }, { "name": "market", "in": "query", "required": false, "description": "Optional — the market is determined by the symbol code (Korean 6-digit code or US ticker). If given, verifies that the symbol belongs to that market (otherwise 400 BAD_SYMBOL).", "schema": { "type": "string", "enum": [ "KR", "US" ] } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Quota-Period": { "$ref": "#/components/headers/X-Quota-Period" }, "X-Quota-Reset": { "$ref": "#/components/headers/X-Quota-Reset" }, "X-Markets": { "$ref": "#/components/headers/X-Markets" }, "X-Plan": { "$ref": "#/components/headers/X-Plan" }, "X-Plan-Tier": { "$ref": "#/components/headers/X-Plan-Tier" }, "X-Plan-Expires": { "$ref": "#/components/headers/X-Plan-Expires" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "symbol": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "market": { "type": "string", "enum": [ "KR", "US" ] }, "source": { "type": "string", "enum": [ "DART", "SEC", "기업 IR 자료", "PheonixAI" ], "description": "Row source — 'DART' or 'SEC' (filing ledger); '기업 IR 자료' (company IR materials: values filled from company IR materials for periods missing from the ledger); 'PheonixAI' (derived values calculated or aggregated by Phoenix AI)" }, "method": { "type": [ "string", "null" ] }, "period_label": { "type": [ "string", "null" ] }, "period_start": { "type": [ "string", "null" ] }, "period_end": { "type": [ "string", "null" ] }, "filed_date": { "type": [ "string", "null" ] }, "report_name": { "type": [ "string", "null" ] }, "accession": { "type": [ "string", "null" ] }, "source_url": { "type": [ "string", "null" ], "format": "uri" }, "prospectus": { "type": "boolean" }, "legacy": { "type": "boolean" }, "axes": { "type": "array", "items": { "$ref": "#/components/schemas/MixAxis" } }, "quarter": { "type": [ "object", "null" ], "properties": { "period_label": { "type": [ "string", "null" ] }, "period_start": { "type": [ "string", "null" ] }, "period_end": { "type": [ "string", "null" ] }, "form": { "type": [ "string", "null" ] }, "filed_date": { "type": [ "string", "null" ] }, "accession": { "type": [ "string", "null" ] }, "source_url": { "type": [ "string", "null" ] }, "axes": { "type": "array", "items": { "$ref": "#/components/schemas/MixAxis" } } } }, "unavailable_axes": { "type": "array", "items": { "type": "object", "properties": { "group": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "reason": { "type": [ "string", "null" ] } } } }, "legacy_segments": { "type": "array", "items": { "type": "object", "properties": { "group": { "type": [ "string", "null" ] }, "label": { "type": [ "string", "null" ] }, "metric": { "type": [ "string", "null" ] }, "value": { "type": [ "number", "null" ] }, "unit": { "type": [ "string", "null" ] } } }, "description": "Legacy extraction without axis information (US)" } } }, "meta": { "type": "object", "properties": { "symbol": { "type": "string" }, "market": { "type": "string", "enum": [ "KR", "US" ] }, "as_of": { "type": "string", "format": "date-time" }, "page_url": { "type": "string", "format": "uri" }, "disclaimer": { "type": "string" }, "unit_note": { "type": "string" }, "note": { "type": "string" }, "count": { "type": "integer" }, "issuer_symbol": { "type": "string", "example": "005930", "description": "Symbol whose company-level data (filings, ownership, insiders, treasury stock, financials, consensus …) was read — for Korean preferred shares (e.g. 005935, 005385, 000815) the issuer's common share (005930, 005380, 000810); otherwise the requested symbol" }, "share_class": { "type": [ "string", "null" ], "enum": [ "common", "preferred", null ], "description": "Korean share class — common or preferred. Null for US symbols (not determined)" }, "issuer_note": { "type": "string", "description": "Preferred shares only — note that company-level data is the issuer's" }, "trade_evidence_reason": { "type": "string", "enum": [ "trade_evidence_unavailable" ] }, "listing_status": { "type": "string", "enum": [ "listed", "suspended", "delisting", "inactive", "delisted", "unknown" ], "description": "Listing and trading status of a Korean symbol (the same decision as data.status.status of /quotes/{symbol}). Absent for US symbols" } }, "description": "Common metadata for company endpoints (each endpoint adds more fields, such as note and unit_note).", "additionalProperties": true } }, "required": [ "data", "meta" ] }, "example": { "data": { "symbol": "AAPL", "name": "애플", "market": "US", "source": "SEC", "method": "sec_10k_xbrl", "period_label": "FY2025", "period_start": "2024-09-29", "period_end": "2025-09-27", "filed_date": "2025-10-31", "report_name": "10-K", "accession": "0000320193-25-000079", "source_url": "https://www.sec.gov/Archives/edgar/data/320193/000032019325000079/0000320193-25-000079-index.htm", "prospectus": false, "legacy": false, "axes": [ { "axis": "product", "group": "제품·서비스", "share_base": "total", "basis_note": "연결 매출 대비", "unit": "백만달러", "total": 416161, "base": 416161, "unallocated": 0, "items": [ { "label": "iPhone", "pct": 50.4, "amount": 209586 }, { "label": "Services", "pct": 26.2, "amount": 109158 } ], "adjustments": [], "excluded_subtotals": [] } ], "quarter": null, "unavailable_axes": [] }, "meta": { "symbol": "AAPL", "market": "US", "as_of": "2026-10-21T06:30:00.000Z", "page_url": "https://www.chickstockfi.com/stocks/AAPL", "disclaimer": "공식 공시(DART·SEC)와 회사 IR 자료를 바탕으로 Phoenix AI가 정리·계산한 참고 자료입니다. 투자 권유가 아니며 정확성·완전성을 보장하지 않습니다.", "unit_note": "비중 pct는 %, 금액 amount는 국내 억원·미국 백만달러(없으면 null)" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequiredOrMarket" }, "404": { "description": "No revenue mix — NOT_FOUND (the symbol exists but the requested data or period does not); SYMBOL_NOT_FOUND (symbol unknown to Phoenix AI); NOT_APPLICABLE (fund-type products such as ETFs and ETNs, for which company data does not apply)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "NOT_FOUND": { "value": { "error": { "code": "NOT_FOUND", "message": "No revenue breakdown is available for this company (no segment table, or not supported for financial companies).", "docs": "https://openapi.chickstockfi.com/docs" } } }, "SYMBOL_NOT_FOUND": { "value": { "error": { "code": "SYMBOL_NOT_FOUND", "message": "Unknown symbol 'ZZZZZZ'. Use a listed Korean 6-character code (e.g. 005930) or a US-listed ticker (e.g. AAPL).", "docs": "https://openapi.chickstockfi.com/docs" } } }, "NOT_APPLICABLE": { "value": { "error": { "code": "NOT_APPLICABLE", "message": "069500 is a fund-type security (ETF/ETN); company financials … do not apply.", "docs": "https://openapi.chickstockfi.com/docs" } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/companies/{symbol}/dividends": { "get": { "operationId": "getCompanyDividends", "tags": [ "Dividends" ], "summary": "Dividend summary and payment history", "x-summary-en": "Dividend summary and payment history", "x-markets": [ "KR", "US" ], "x-market-scoped": true, "description": "Dividend summary (dividend per share, dividend yield, payout ratio, consecutive years paid), per-payment dividend history (ex-dividend date, record date, payment date, amount per share, yield per payment), annual totals with year-over-year change, and trailing twelve months (TTM).\n\n- Amounts and record dates come from the filing ledger (DART dividend filings, SEC) first; payments and dates (ex-dividend date, payment date) missing from the ledger come from company IR materials (`source` on each row).\n- Yields are calculated by Phoenix AI from our closing prices (`yield_source` = 'PheonixAI').\n- Korean payout ratio and EPS are based on consolidated net income attributable to **owners of the parent** from the annual report.\n- For the raw annual-report table for Korea (current, prior, and two-years-prior period strings), use `GET /dividends/{symbol}`.\n- **Preferred shares**: the annual summary reads the requested preferred-class line in the stored issuer filing and adjusts it to current shares. DPS and yield use the same cache as /metrics. Common-share DPS and TTM totals are never substituted. Missing class, per-share or share-basis evidence returns null with dps_reason and yield_reason. Payment history and TTM belong to the preferred security itself.\n\n> Markets: KR · US\n\n> 🔒 **Paid tiers only** (Launch, Business, Scale, Enterprise; PoC included) — Free keys and accounts whose paid-tier term has ended receive 403 `PLAN_REQUIRED`; accounts whose PoC has ended receive 403 `POC_ENDED`.\n\n> 🌐 **Data coverage** — the account receives data only for the markets it has contracted. A market outside the contract (symbol or `market`) returns 403 `MARKET_NOT_ENTITLED` before any limit is counted; Japan (`JP`) and China (`CN`) return 400 `MARKET_NOT_AVAILABLE` (coming soon). For POST /query, authentication applies first; if every line is outside the contract, it returns 403 with zero per-minute, ordinary daily and AI calls. A storage failure or timeout during key, plan, company or market resolution returns HTTP 503 `UNAVAILABLE` with zero per-minute, ordinary daily and AI calls, without falling back to Free. Otherwise it returns HTTP 200 with per-line errors and counts as one ordinary call.", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "symbol", "in": "path", "required": true, "description": "Korean 6-digit symbol code (005930) or US ticker (AAPL)", "schema": { "type": "string", "example": "005930" } }, { "name": "market", "in": "query", "required": false, "description": "Optional — the market is determined by the symbol code (Korean 6-digit code or US ticker). If given, verifies that the symbol belongs to that market (otherwise 400 BAD_SYMBOL).", "schema": { "type": "string", "enum": [ "KR", "US" ] } }, { "name": "years", "in": "query", "required": false, "description": "Years of history (1–20, default 10)", "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 10 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Quota-Period": { "$ref": "#/components/headers/X-Quota-Period" }, "X-Quota-Reset": { "$ref": "#/components/headers/X-Quota-Reset" }, "X-Markets": { "$ref": "#/components/headers/X-Markets" }, "X-Plan": { "$ref": "#/components/headers/X-Plan" }, "X-Plan-Tier": { "$ref": "#/components/headers/X-Plan-Tier" }, "X-Plan-Expires": { "$ref": "#/components/headers/X-Plan-Expires" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "symbol": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "market": { "type": "string", "enum": [ "KR", "US" ] }, "currency": { "type": "string", "enum": [ "KRW", "USD" ] }, "summary": { "type": "object", "properties": { "price": { "type": [ "number", "null" ] }, "yield_basis": { "type": "string", "enum": [ "annual_dps_over_current_price" ] }, "payout_reason": { "type": [ "string", "null" ] }, "consecutive_years_reason": { "type": [ "string", "null" ] }, "dps_reason": { "type": [ "string", "null" ] }, "yield_reason": { "type": [ "string", "null" ] }, "price_as_of": { "type": [ "string", "null" ], "description": "Legacy valuation price basis, date or ISO instant; preserved unchanged." }, "price_date": { "type": [ "string", "null" ], "format": "date" }, "price_time": { "type": [ "string", "null" ], "format": "date-time" }, "share_factor": { "type": [ "number", "null" ] }, "dps": { "type": [ "number", "null" ] }, "dps_base_year": { "type": [ "integer", "null" ] }, "dps_reported": { "type": [ "number", "null" ] }, "dps_note": { "type": [ "string", "null" ] }, "dps_basis": { "type": [ "string", "null" ], "enum": [ "annual_current_share", "annual_payments_current_share", null ], "description": "Same basis as /metrics valuation.dividend: annual_current_share for filed fiscal-year DPS, annual_payments_current_share for completed calendar-year payments when filing DPS is absent." }, "dividend_yield_pct": { "type": [ "number", "null" ], "description": "Annual DPS divided by the shared valuation price (%); see price_as_of." }, "dividend_yield_note": { "type": [ "string", "null" ] }, "payout_pct": { "type": [ "number", "null" ] }, "consecutive_years": { "type": [ "integer", "null" ], "description": "Korea: Consecutive positive-payment years counted backwards from the latest completed year in the stored annual payment ledger (up to 20 years, independent of the display window). In-progress years are excluded; missing, zero or unconfirmed years stop the count. Only stored coverage is counted; the actual history may be longer. US retains its payment-ledger basis." }, "consecutive_years_through": { "type": [ "integer", "null" ] }, "consecutive_years_note": { "type": [ "string", "null" ] }, "total_dividends_paid": { "type": [ "number", "null" ] } } }, "frequency": { "type": [ "string", "null" ] }, "ttm": { "type": [ "object", "null" ], "properties": { "dps_current_share": { "type": [ "number", "null" ] }, "payments": { "type": [ "integer", "null" ] }, "yield_pct": { "type": [ "number", "null" ] }, "price": { "type": [ "number", "null" ] }, "price_date": { "type": [ "string", "null" ] } } }, "history": { "type": "array", "items": { "type": "object", "properties": { "ex_date": { "type": [ "string", "null" ] }, "record_date": { "type": [ "string", "null" ] }, "fiscal_period_end": { "type": [ "string", "null" ] }, "pay_date": { "type": [ "string", "null" ] }, "cash_per_share": { "type": [ "number", "null" ] }, "cash_per_share_current": { "type": [ "number", "null" ] }, "yield_pct": { "type": [ "number", "null" ] }, "yield_source": { "type": [ "string", "null" ] }, "source": { "type": "string", "description": "'DART', 'SEC', '기업 IR 자료' (company IR materials), 'DART+기업 IR 자료' (DART + company IR materials)" } } } }, "annual": { "type": "array", "items": { "type": "object", "properties": { "year": { "type": "integer" }, "payments": { "type": "integer" }, "dps_current_share": { "type": [ "number", "null" ] }, "yoy_pct": { "type": [ "number", "null" ] }, "in_progress": { "type": "boolean" } } } }, "payout_ratio": { "type": "array", "items": { "type": "object", "properties": { "fiscal_year": { "type": "integer" }, "pct": { "type": [ "number", "null" ] }, "basis": { "type": [ "string", "null" ] } } } } } }, "meta": { "type": "object", "properties": { "symbol": { "type": "string" }, "market": { "type": "string", "enum": [ "KR", "US" ] }, "as_of": { "type": "string", "format": "date-time" }, "page_url": { "type": "string", "format": "uri" }, "disclaimer": { "type": "string" }, "unit_note": { "type": "string" }, "note": { "type": "string" }, "count": { "type": "integer" }, "issuer_symbol": { "type": "string", "example": "005930", "description": "Symbol whose company-level data (filings, ownership, insiders, treasury stock, financials, consensus …) was read — for Korean preferred shares (e.g. 005935, 005385, 000815) the issuer's common share (005930, 005380, 000810); otherwise the requested symbol" }, "share_class": { "type": [ "string", "null" ], "enum": [ "common", "preferred", null ], "description": "Korean share class — common or preferred. Null for US symbols (not determined)" }, "issuer_note": { "type": "string", "description": "Preferred shares only — note that company-level data is the issuer's" }, "trade_evidence_reason": { "type": "string", "enum": [ "trade_evidence_unavailable" ] }, "listing_status": { "type": "string", "enum": [ "listed", "suspended", "delisting", "inactive", "delisted", "unknown" ], "description": "Listing and trading status of a Korean symbol (the same decision as data.status.status of /quotes/{symbol}). Absent for US symbols" } }, "description": "Common metadata for company endpoints (each endpoint adds more fields, such as note and unit_note).", "additionalProperties": true } }, "required": [ "data", "meta" ] }, "example": { "data": { "symbol": "005930", "name": "삼성전자", "market": "KR", "currency": "KRW", "summary": { "dps": 1446, "dps_base_year": 2025, "dps_reported": null, "dps_note": null, "dps_basis": "annual_current_share", "dividend_yield_pct": 1.9, "dividend_yield_note": null, "payout_pct": 25.1, "consecutive_years": 4, "consecutive_years_note": "데이터 범위(최근 4년) 내 연속", "total_dividends_paid": null }, "frequency": "분기(연 4회)", "ttm": { "dps_current_share": 1446, "payments": 4, "yield_pct": 1.9, "price": 75400, "price_date": "2026-10-20" }, "history": [ { "ex_date": "2026-06-27", "record_date": "2026-06-30", "fiscal_period_end": null, "pay_date": "2026-08-20", "cash_per_share": 361, "cash_per_share_current": 361, "yield_pct": 0.5, "yield_source": "PheonixAI", "source": "DART+기업 IR 자료" } ], "annual": [ { "year": 2025, "payments": 4, "dps_current_share": 1446, "yoy_pct": 0, "in_progress": false } ], "payout_ratio": [ { "fiscal_year": 2025, "pct": 25.1, "basis": "사업보고서 현금배당성향(DART)" } ] }, "meta": { "symbol": "005930", "market": "KR", "as_of": "2026-10-21T06:30:00.000Z", "page_url": "https://www.chickstockfi.com/stocks/005930", "disclaimer": "공식 공시(DART·SEC)와 회사 IR 자료를 바탕으로 Phoenix AI가 정리·계산한 참고 자료입니다. 투자 권유가 아니며 정확성·완전성을 보장하지 않습니다.", "unit_note": "주당 금액 원 · 수익률·성향 %" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequiredOrMarket" }, "404": { "description": "No dividend data — NOT_FOUND (the symbol exists but the requested data or period does not); SYMBOL_NOT_FOUND (symbol unknown to Phoenix AI); NOT_APPLICABLE (fund-type products such as ETFs and ETNs, for which company data does not apply)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "NOT_FOUND": { "value": { "error": { "code": "NOT_FOUND", "message": "No dividend data, or the company pays no dividend.", "docs": "https://openapi.chickstockfi.com/docs" } } }, "SYMBOL_NOT_FOUND": { "value": { "error": { "code": "SYMBOL_NOT_FOUND", "message": "Unknown symbol 'ZZZZZZ'. Use a listed Korean 6-character code (e.g. 005930) or a US-listed ticker (e.g. AAPL).", "docs": "https://openapi.chickstockfi.com/docs" } } }, "NOT_APPLICABLE": { "value": { "error": { "code": "NOT_APPLICABLE", "message": "069500 is a fund-type security (ETF/ETN); company financials … do not apply.", "docs": "https://openapi.chickstockfi.com/docs" } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/dividends/{symbol}": { "get": { "operationId": "getDividendTable", "tags": [ "Dividends" ], "summary": "Dividend table as filed (Korea)", "x-summary-en": "Dividend table as filed (Korea)", "x-markets": [ "KR" ], "x-market-scoped": true, "x-paginated": "cursor", "description": "Returns the \"Dividend matters\" table from the annual report in its original order (current, prior, and two-years-prior periods). **Values are strings exactly as written in the filing**, and the unit is included in the `item` name (KRW, %, KRW million). Includes the settlement date (`settle_date`) and receipt number (`rcept_no`). For the normalized dividend summary and history, use `/companies/{symbol}/dividends`.\n\n> Markets: KR · Pagination: cursor + limit\n\n> 🔒 **Paid tiers only** (Launch, Business, Scale, Enterprise; PoC included) — Free keys and accounts whose paid-tier term has ended receive 403 `PLAN_REQUIRED`; accounts whose PoC has ended receive 403 `POC_ENDED`.\n\n> 🌐 **Data coverage** — the account receives data only for the markets it has contracted. A market outside the contract (symbol or `market`) returns 403 `MARKET_NOT_ENTITLED` before any limit is counted; Japan (`JP`) and China (`CN`) return 400 `MARKET_NOT_AVAILABLE` (coming soon). For POST /query, authentication applies first; if every line is outside the contract, it returns 403 with zero per-minute, ordinary daily and AI calls. A storage failure or timeout during key, plan, company or market resolution returns HTTP 503 `UNAVAILABLE` with zero per-minute, ordinary daily and AI calls, without falling back to Free. Otherwise it returns HTTP 200 with per-line errors and counts as one ordinary call.", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "symbol", "in": "path", "required": true, "description": "Korean 6-digit symbol code (e.g. 005930; a leading A is ignored)", "schema": { "type": "string", "pattern": "^A?\\d[0-9A-Z]{5}$", "example": "005930" } }, { "name": "market", "in": "query", "required": false, "description": "Optional — the market is determined by the symbol code (Korean 6-digit code or US ticker). If given, verifies that the symbol belongs to that market (otherwise 400 BAD_SYMBOL). Only KR symbols are supported (others return 400 UNSUPPORTED_MARKET).", "schema": { "type": "string", "enum": [ "KR", "US" ] } }, { "name": "year", "in": "query", "required": false, "description": "Fiscal year YYYY (if omitted, the previous year; if that is not yet filed, automatically the year before)", "schema": { "type": "string", "pattern": "^\\d{4}$", "example": "2025" } }, { "name": "report", "in": "query", "required": false, "description": "11011 annual report; 11012 half-year report; 11013 Q1 report; 11014 Q3 report", "schema": { "type": "string", "enum": [ "11011", "11012", "11013", "11014" ] } }, { "name": "cursor", "in": "query", "required": false, "description": "Next page — pass the previous response's next_cursor as-is, with the same filters. Omit for the first page", "schema": { "type": "string", "maxLength": 2100, "example": "c1.eyJrIjpbIjIwMjYtMTAtMjAiLCIyMDI2MTAyMDAwMDEyMyJdLCJmIjoiQWJDZEVmR2hJaksifQ" } }, { "name": "limit", "in": "query", "required": false, "description": "Items per page (1–200, default 50)", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Quota-Period": { "$ref": "#/components/headers/X-Quota-Period" }, "X-Quota-Reset": { "$ref": "#/components/headers/X-Quota-Reset" }, "X-Markets": { "$ref": "#/components/headers/X-Markets" }, "X-Plan": { "$ref": "#/components/headers/X-Plan" }, "X-Plan-Tier": { "$ref": "#/components/headers/X-Plan-Tier" }, "X-Plan-Expires": { "$ref": "#/components/headers/X-Plan-Expires" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DividendItem" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page — null if there are no more pages" }, "has_more": { "type": "boolean", "description": "Whether there is a next page" }, "meta": { "type": "object", "properties": { "count": { "type": "integer" }, "symbol": { "type": "string" }, "market": { "type": "string", "enum": [ "KR", "US" ] }, "issuer_symbol": { "type": "string", "example": "005930", "description": "Symbol whose company-level data (filings, ownership, insiders, treasury stock, financials, consensus …) was read — for Korean preferred shares (e.g. 005935, 005385, 000815) the issuer's common share (005930, 005380, 000810); otherwise the requested symbol" }, "share_class": { "type": [ "string", "null" ], "enum": [ "common", "preferred", null ], "description": "Korean share class — common or preferred. Null for US symbols (not determined)" }, "issuer_note": { "type": "string", "description": "Preferred shares only — note that company-level data is the issuer's" }, "year": { "type": "string" }, "report": { "type": "string" }, "as_of": { "type": "string", "format": "date-time" } } } }, "required": [ "data", "next_cursor", "has_more", "meta" ] }, "example": { "data": [ { "item": "주당 현금배당금(원)", "stock_kind": "보통주", "this_term": "1,446", "prev_term": "1,446", "prev2_term": "1,444", "settle_date": "2025-12-31", "rcept_no": "20260311001234", "market": "KR" } ], "next_cursor": null, "has_more": false, "meta": { "count": 1, "symbol": "005930", "market": "KR", "year": "2025", "report": "11011", "as_of": "2026-10-21T06:30:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequiredOrMarket" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/companies/{symbol}/net-income-split": { "get": { "operationId": "getCompanyNetIncomeSplit", "tags": [ "Net income split" ], "summary": "Net income attributable to owners vs. non-controlling interests (Korea)", "x-summary-en": "Net income attributable to owners vs. non-controlling interests (Korea)", "x-markets": [ "KR" ], "x-market-scoped": true, "description": "Splits net income from Korean consolidated financial statements, by period, into the share attributable to owners of the parent, the consolidated total, and the non-controlling interests share (annual and quarterly for the last 4 fiscal years; only rows that pass reconciliation checks).\n\n- EPS, PER, and ROE are based on net income attributable to owners of the parent.\n- Quarterly values cover the 3 months of that quarter; Q2, Q3, and Q4 are differences between cumulative values (`basis` = derived).\n- Only Korean symbols are supported (US tickers return 400 UNSUPPORTED_MARKET).\n\n> Markets: KR\n\n> 🔒 **Paid tiers only** (Launch, Business, Scale, Enterprise; PoC included) — Free keys and accounts whose paid-tier term has ended receive 403 `PLAN_REQUIRED`; accounts whose PoC has ended receive 403 `POC_ENDED`.\n\n> 🌐 **Data coverage** — the account receives data only for the markets it has contracted. A market outside the contract (symbol or `market`) returns 403 `MARKET_NOT_ENTITLED` before any limit is counted; Japan (`JP`) and China (`CN`) return 400 `MARKET_NOT_AVAILABLE` (coming soon). For POST /query, authentication applies first; if every line is outside the contract, it returns 403 with zero per-minute, ordinary daily and AI calls. A storage failure or timeout during key, plan, company or market resolution returns HTTP 503 `UNAVAILABLE` with zero per-minute, ordinary daily and AI calls, without falling back to Free. Otherwise it returns HTTP 200 with per-line errors and counts as one ordinary call.", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "symbol", "in": "path", "required": true, "description": "Korean 6-digit symbol code (e.g. 005930; a leading A is ignored)", "schema": { "type": "string", "pattern": "^A?\\d[0-9A-Z]{5}$", "example": "005930" } }, { "name": "market", "in": "query", "required": false, "description": "Optional — the market is determined by the symbol code (Korean 6-digit code or US ticker). If given, verifies that the symbol belongs to that market (otherwise 400 BAD_SYMBOL). Only KR symbols are supported (others return 400 UNSUPPORTED_MARKET).", "schema": { "type": "string", "enum": [ "KR", "US" ] } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Quota-Period": { "$ref": "#/components/headers/X-Quota-Period" }, "X-Quota-Reset": { "$ref": "#/components/headers/X-Quota-Reset" }, "X-Markets": { "$ref": "#/components/headers/X-Markets" }, "X-Plan": { "$ref": "#/components/headers/X-Plan" }, "X-Plan-Tier": { "$ref": "#/components/headers/X-Plan-Tier" }, "X-Plan-Expires": { "$ref": "#/components/headers/X-Plan-Expires" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "symbol": { "type": "string" }, "market": { "type": "string", "enum": [ "KR" ] }, "annual": { "type": "array", "items": { "$ref": "#/components/schemas/NetIncomeSplitRow" } }, "quarterly": { "type": "array", "items": { "$ref": "#/components/schemas/NetIncomeSplitRow" } } } }, "meta": { "type": "object", "properties": { "symbol": { "type": "string" }, "market": { "type": "string", "enum": [ "KR", "US" ] }, "as_of": { "type": "string", "format": "date-time" }, "page_url": { "type": "string", "format": "uri" }, "disclaimer": { "type": "string" }, "unit_note": { "type": "string" }, "note": { "type": "string" }, "count": { "type": "integer" }, "issuer_symbol": { "type": "string", "example": "005930", "description": "Symbol whose company-level data (filings, ownership, insiders, treasury stock, financials, consensus …) was read — for Korean preferred shares (e.g. 005935, 005385, 000815) the issuer's common share (005930, 005380, 000810); otherwise the requested symbol" }, "share_class": { "type": [ "string", "null" ], "enum": [ "common", "preferred", null ], "description": "Korean share class — common or preferred. Null for US symbols (not determined)" }, "issuer_note": { "type": "string", "description": "Preferred shares only — note that company-level data is the issuer's" }, "trade_evidence_reason": { "type": "string", "enum": [ "trade_evidence_unavailable" ] }, "listing_status": { "type": "string", "enum": [ "listed", "suspended", "delisting", "inactive", "delisted", "unknown" ], "description": "Listing and trading status of a Korean symbol (the same decision as data.status.status of /quotes/{symbol}). Absent for US symbols" } }, "description": "Common metadata for company endpoints (each endpoint adds more fields, such as note and unit_note).", "additionalProperties": true } }, "required": [ "data", "meta" ] }, "example": { "data": { "symbol": "005380", "market": "KR", "annual": [ { "period": "2025 연간", "period_code": "FY2025", "period_type": "annual", "fiscal_year": 2025, "fiscal_quarter": null, "fs": "CFS", "unit": "억원", "unit_code": "KRW_EOK", "unit_scale": 100000000, "controlling_net_income": 125812, "total_net_income": 131023, "nci_net_income": 5211, "nci_share_pct": 3.98, "controlling_net_income_raw": 12581200000000, "total_net_income_raw": 13102300000000, "nci_net_income_raw": 521100000000, "raw_unit": "KRW", "sign_case": "profit", "basis": "reported", "material": true, "source": "DART", "report": "사업보고서 (2025.12)", "filed_date": "2026-03-12", "source_url": "https://dart.fss.or.kr/dsaf001/main.do?rcpNo=20260312000777" } ], "quarterly": [] }, "meta": { "symbol": "005380", "market": "KR", "as_of": "2026-10-21T06:30:00.000Z", "page_url": "https://www.chickstockfi.com/stocks/005380", "disclaimer": "공식 공시(DART·SEC)와 회사 IR 자료를 바탕으로 Phoenix AI가 정리·계산한 참고 자료입니다. 투자 권유가 아니며 정확성·완전성을 보장하지 않습니다.", "unit_note": "억원(연결재무제표)" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequiredOrMarket" }, "404": { "description": "No data — NOT_FOUND (the symbol exists but the requested data or period does not); SYMBOL_NOT_FOUND (symbol unknown to Phoenix AI); NOT_APPLICABLE (fund-type products such as ETFs and ETNs, for which company data does not apply)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "NOT_FOUND": { "value": { "error": { "code": "NOT_FOUND", "message": "No period has both net income attributable to owners of the parent and total consolidated net income.", "docs": "https://openapi.chickstockfi.com/docs" } } }, "SYMBOL_NOT_FOUND": { "value": { "error": { "code": "SYMBOL_NOT_FOUND", "message": "Unknown symbol 'ZZZZZZ'. Use a listed Korean 6-character code (e.g. 005930) or a US-listed ticker (e.g. AAPL).", "docs": "https://openapi.chickstockfi.com/docs" } } }, "NOT_APPLICABLE": { "value": { "error": { "code": "NOT_APPLICABLE", "message": "069500 is a fund-type security (ETF/ETN); company financials … do not apply.", "docs": "https://openapi.chickstockfi.com/docs" } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/query": { "post": { "operationId": "runQuery", "tags": [ "Financial statements" ], "summary": "Run a multi-dataset data query", "x-summary-en": "Run a multi-dataset data query", "x-markets": [ "KR", "US" ], "x-market-scoped": true, "description": "Takes the \"data query\" JSON of a Phoenix AI PRO answer and runs it again with the same calculation code (deterministic, no model). 1–20 lines per request. The market of each line follows from its `company` (Korean code or US ticker) or `market`.\n\n**Limits**: no model is called, so this **does not count toward the PoC AI-call quota** — each HTTP 200 request counts as one ordinary data call. If every line is outside the contract, HTTP 403 consumes zero per-minute, ordinary daily and AI calls. If key, plan, company or market resolution encounters a storage failure or timeout, the whole request returns HTTP 503 `UNAVAILABLE` without falling back to Free or executing any line, with zero per-minute, ordinary daily and AI calls. Authentication, PoC expiry and market resolution precede per-minute and daily accounting. No AI-quota headers (X-AI-Quota-*) are returned.\n\nWhile the screener cache is being prepared, the line in HTTP 200 returns the existing `not_ready` / `NOT_READY` status. The market build continues after the request ends and fills the shared cache. Retry the same line shortly.\n\nDatasets and line inputs:\n- `financials` (financial accounts) — `company` · `account` (optional) · `period` (optional)\n- `metrics` (ratios, valuation, growth) — `company` · `metric` · `period` (optional)\n- `segments` (revenue mix) — `company`\n- `restatements` (US restatement history) — `company` · `account` · `period` (optional)\n- `sector` (industry) — `company`\n- `sector_ranking` (industry ranking) — `metric` · `market` (kr, us) · `sector` · `groupBy` (subindustry) · `subindustry` · `order` (desc, asc) · `limit`\n- `screener` (stock screener) — `market` (kr by default, us) · `preset` **or** conditions `perMax`, `pbrMax` (x), `roeMin`, `niCagrMin`, `revCagrMin`, `grossMarginMin`, `divYieldMin` (%), `marketCapMinEok` (Korea: KRW 100 million; US: USD million) · `sector` · `subindustry` · `limit` (max 30). Presets: value-growth · cheap-value · quality-growth · high-roe-cheap · cash-cow · steady-dividend · golden-cross · ma-turn · rebound · momentum. With a preset leave the other conditions empty (only the sector can be combined). Example: `{\"dataset\":\"screener\",\"market\":\"kr\",\"perMax\":10,\"roeMin\":15}`\n- `dividends` (dividends) — `company` · `years` (optional, 1–20)\n- `financial_health` (financial health summary) — `company`\n- `quote` (price and market cap) — `company`\n\nField names are accepted in camelCase and snake_case (`per_max`, `roe_min`), and conditions may be grouped in a `filters` object (fields written directly on the line win). `market` is case-insensitive. Fields a dataset does not know are dropped and listed in `results[i].ignored_fields`.\n\n**Per-line results**: `results[i]` (same order as the request lines) = `status` (ok · not_found · not_ready · invalid_input · unsupported_dataset · failed · market_not_entitled · market_not_available) · `error` (NOT_FOUND · NOT_READY · INVALID_INPUT · UNSUPPORTED_DATASET · FAILED · MARKET_NOT_ENTITLED · MARKET_NOT_AVAILABLE; null on success) · `message` (English) · `issues` (input validation — which field and why) · `data` (the result of that line). The response is HTTP 200 even when only some lines fail, with `meta.partial` and `meta.failed` — check `status` per line rather than relying on `ok`. The top-level `data` (ratios, figures, segments, restatements) is the legacy summary and covers only some datasets.\n\nLines outside the contract or in unavailable markets never read data. **Only when every line is classified as MARKET_NOT_ENTITLED** does the entire request return HTTP 403 `MARKET_NOT_ENTITLED`. The envelope contains `error.code`, `message`, `docs`, `error.rejected_lines` (zero-based `index` and denied `market` per line), and `error.entitled_markets` (contract markets). With a KR-only key, an AAPL-only request returns 403; a Korean line plus an AAPL line returns HTTP 200 with `market_not_entitled` only for AAPL and counts as one ordinary call. If other failures (`NOT_FOUND`, `INVALID_INPUT`, `UNSUPPORTED_DATASET`, `MARKET_NOT_AVAILABLE`, etc.) are mixed in, HTTP 200, per-line errors and one ordinary call are preserved even with zero successful lines. Per-line precedence is unsupported dataset, then market authorization, then tool input validation; a line denied by market authorization is not separately checked for other input errors. Empty arrays, arrays outside 1–20 lines and malformed bodies retain 400 `BAD_REQUEST`. Undated ROE follows valuation.basis (TTM when available, otherwise annual). Quote price and changePercent use quote_price_as_of (percent rounded to two decimals, null when unavailable); valuation.price and price_as_of identify the calculation price. Korean list and single valuations retain stored financial snapshots (availability_basis=stored_snapshot, snapshot_as_of) and refresh price-dependent fields using the same stored price observations and calculation. Snapshots older than 36 hours or with invalid build times fall back to the existing calculation path. Legacy price_as_of remains YYYY-MM-DD for date-based paths or the original ISO instant when the Korean calculation received a time. snapshot_as_of, as_of and priceDate retain their existing representations. Prefer additive price_date (always YYYY-MM-DD), price_time and snapshot_time (ISO 8601 or null). Date-only observations keep their legacy price_as_of; only price_time is null, never invented midnight. Selection and ordering use selection_as_of.\n\nKR sector_ranking supports `영업이익`, `매출액`, `당기순이익`, `자산총계`, `부채총계`, `자본총계`, PER and PBR (aliases `매출` and `순이익`). Unsupported metrics return HTTP 400 BAD_REQUEST with an allowed list. Company PER/PBR rankings use shared current valuations; ratios are not summed (total null, total_reason=ratio_not_additive). KR screener ma is returned only when its date matches price_date. ma_reason is technical_history_unavailable, price_date_unavailable or technical_price_date_mismatch; ma_source_as_of retains the signal date. KR payment streaks share up to 20 years of stored payment history, independently of display years. \n\nFor stable fields use the `/companies/{symbol}/…` endpoints. Forward P/E (based on broker EPS estimates), target-price and consensus fields, and provider names are not included.\n\n> Markets: KR · US\n\n> 🔒 **Paid tiers only** (Launch, Business, Scale, Enterprise; PoC included) — Free keys and accounts whose paid-tier term has ended receive 403 `PLAN_REQUIRED`; accounts whose PoC has ended receive 403 `POC_ENDED`.\n\n> 🌐 **Data coverage** — the account receives data only for the markets it has contracted. A market outside the contract (symbol or `market`) returns 403 `MARKET_NOT_ENTITLED` before any limit is counted; Japan (`JP`) and China (`CN`) return 400 `MARKET_NOT_AVAILABLE` (coming soon). For POST /query, authentication applies first; if every line is outside the contract, it returns 403 with zero per-minute, ordinary daily and AI calls. A storage failure or timeout during key, plan, company or market resolution returns HTTP 503 `UNAVAILABLE` with zero per-minute, ordinary daily and AI calls, without falling back to Free. Otherwise it returns HTTP 200 with per-line errors and counts as one ordinary call.", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryRequest" }, "example": { "queries": [ { "dataset": "financials", "company": "005930", "account": "매출액", "period": "2025 연간" }, { "dataset": "metrics", "company": "AAPL", "metric": "영업이익률" }, { "dataset": "screener", "market": "kr", "filters": { "per_max": 10, "roe_min": 15 } } ] } } } }, "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Quota-Period": { "$ref": "#/components/headers/X-Quota-Period" }, "X-Quota-Reset": { "$ref": "#/components/headers/X-Quota-Reset" }, "X-Markets": { "$ref": "#/components/headers/X-Markets" }, "X-Plan": { "$ref": "#/components/headers/X-Plan" }, "X-Plan-Tier": { "$ref": "#/components/headers/X-Plan-Tier" }, "X-Plan-Expires": { "$ref": "#/components/headers/X-Plan-Expires" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryResult" }, "example": { "as_of": "2026-10-21T06:30:00.000Z", "table": null, "data": { "ratios": [ { "company": "애플", "metric": "영업이익률", "value": 31.9, "unit": "%", "period": "FY2025" } ], "figures": [ { "company": "삼성전자", "account": "매출액", "value": 3008709, "unit": "억원", "period": "2025 연간" } ], "segments": [], "restatements": [] }, "sources": [ { "n": 1, "tag": "재무", "name": "삼성전자", "title": "사업보고서 (2025.12)", "detail": null, "url": "https://dart.fss.or.kr/dsaf001/main.do?rcpNo=20260311001234", "date": "2026-03-11" } ], "results": [ { "dataset": "financials", "ok": true, "status": "ok", "error": null, "message": null, "data": { "found": true, "code": "005930", "name": "삼성전자", "rows": [ { "account": "매출액", "fiscalYear": 2025, "period": "2025 연간", "fs": "CFS", "value": 3008709, "unit": "억원" } ] } }, { "dataset": "metrics", "ok": true, "status": "ok", "error": null, "message": null, "data": { "found": true, "company": "애플", "metric": "영업이익률", "value": 31.9, "unit": "%", "period": "FY2025" } }, { "dataset": "screener", "ok": false, "status": "invalid_input", "error": "INVALID_INPUT", "message": "Invalid input: perMax: Invalid input: expected number, received string.", "issues": [ { "path": "perMax", "message": "Invalid input: expected number, received string" } ], "data": null } ], "meta": { "as_of": "2026-10-21T06:30:00.000Z", "lines": 3, "ok": 2, "failed": 1, "complete": false, "partial": true, "model_invoked": false } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/QueryPlanRequiredOrMarket" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/companies/{symbol}/consensus": { "get": { "operationId": "getCompanyConsensus", "tags": [ "Consensus" ], "summary": "Street consensus (revenue & operating income)", "x-summary-en": "Street consensus (revenue & operating income)", "x-markets": [ "KR", "US" ], "x-market-scoped": true, "description": "Market consensus (aggregate of brokerage estimates) — returns **revenue and operating income only**, by period (most recently reported period, next quarter, annual). Attribution: PheonixAI.\n\n- These are market values that Phoenix AI compiles from brokerage estimates; they are not Phoenix AI forecasts.\n- For reported periods, the actual value (`actual`) and the difference versus the consensus just before the report (`vs_consensus_pct`) are included. `vs_consensus_pct` is calculated only when a consensus observed before the report date (`reported_on`) exists (`consensus_at_report`); otherwise it is null, and `comparison_status` (reason code) and `comparison_note` are given. For periods where the source does not provide the report time (some US periods), `reported_on` is null and no pre-report value is selected. Changes versus 1, 4, and 12 weeks ago are in `revisions`.\n- **Units**: by default (`unit=raw`), amounts are in KRW or USD as-is (unlike the 억원 (KRW 100 million) and 백만달러 (USD million) used in financial statements). You can request `unit=eok` (억원, Korea only) or `unit=million` (KRW million / USD million); every value carries `unit` and `unit_scale`.\n- For the US, only revenue consensus is currently provided (`meta.metrics` = the metrics actually provided for that market). Years and quarters follow the company's fiscal year.\n- Not provided: EPS estimates, names of individual brokerages or analysts, target prices, report links.\n\n**Point-in-time lookup (`as_of=YYYY-MM-DD`)** — to check a past decision, see the values that were public on that day.\n- The ledger is change-logged: a new row is written only when a value changes. For each item it returns the last value whose observation date (snapshot) is on or before `as_of`, together with the day that value was first observed (`observed_on`) and the start of the record (`coverage_start`).\n- Date boundary: observation dates are **Korea time (Asia/Seoul) calendar days**. `as_of` means what had been recorded by the end of that day in Korea time (for US symbols this is the morning of the same day in New York — conservative, never forward-looking).\n- No look-ahead: values first observed after `as_of`, and reported results released after it (Korea: report date ≤ `as_of`; US: report date < `as_of` only), are excluded. `revisions` (1, 4 and 12 weeks) are recomputed from `as_of`. When the same-value interval continued past `as_of`, the estimate date (`estimate_date`), which later observations may have updated, is left empty.\n- Record depth: items with no record on `as_of` are never filled with later values; they are listed in `data.coverage.not_covered`. If nothing had been recorded on that day, the response is 200 with `periods: []` and `coverage.status: \"not_covered\"`. Records start on 2026-09-15 for the US, 2026-05-13 for the Korean broker-report median (annual), and in October 2026 for other Korean aggregates (`coverage_start` per symbol and item).\n- The Korean broker-report median carries report dates, so for dates before the record starts it is recomputed with the same rule (last 90 days, at least 3 brokers) and marked `reconstructed: true`.\n- For reported periods, `consensus_at_report` and surprise use the same period and metric from the `as_of` view on the day before `reported_on`. `consensus_at_report_as_of` is the cutoff, `consensus_at_report_date` the observation date, `consensus_at_report_source` is `market_consensus`, and `consensus_at_report_reconstructed` identifies reconstructed values. If the historical value or release date cannot be established, the comparison value and surprise are null with an English `comparison_note`.\n- Latest-response compatibility: without `as_of`, the symbol, periods, ordering, current `consensus`, metric `as_of`, `revisions` and actuals retain their latest-query values. Corrections affect only `consensus_at_report`, its date/basis, surprise and comparison status/reason. The three new comparison-provenance fields are optional and appear only when a comparison cutoff is established. Default responses do not add `data.as_of`, `data.coverage`, or metric `observed_on`, `coverage_start` and `reconstructed`.\n- A malformed date, a future date (after today in Korea time) or a date before 2000-01-01 returns 400 `BAD_REQUEST`. Without `as_of`, the endpoint returns the latest values as before.\n\nExample: `GET /companies/005930/consensus?as_of=2026-10-14`\n```json\n{\"data\":{\"symbol\":\"005930\",\"market\":\"KR\",\"currency\":\"KRW\",\"unit\":\"KRW\",\"unit_scale\":1,\"as_of\":\"2026-10-14\",\"coverage\":{\"as_of\":\"2026-10-14\",\"date_basis\":\"KST (Asia/Seoul) date\",\"coverage_start\":\"2026-05-13\",\"status\":\"partial\",\"not_covered\":[{\"period\":\"2027 annual\",\"period_type\":\"annual\",\"fiscal_year\":2027,\"fiscal_quarter\":null,\"metric\":\"revenue\",\"coverage_start\":\"2026-10-16\"}],\"reconstruction_unavailable\":false},\"periods\":[{\"period\":\"2026 Q3\",\"period_code\":\"2026Q3\",\"status\":\"upcoming\",\"metrics\":[{\"metric\":\"revenue\",\"consensus\":80900000000000,\"as_of\":\"2026-10-14\",\"observed_on\":\"2026-10-12\",\"coverage_start\":\"2026-10-12\",\"reconstructed\":false,\"revisions\":{\"1w\":null,\"4w\":null,\"12w\":null},\"actual\":null,\"comparison_status\":\"upcoming\"}]}]}}\n```\n\n> Markets: KR · US\n\n> 🔒 **Paid tiers only** (Launch, Business, Scale, Enterprise; PoC included) — Free keys and accounts whose paid-tier term has ended receive 403 `PLAN_REQUIRED`; accounts whose PoC has ended receive 403 `POC_ENDED`.\n\n> 🌐 **Data coverage** — the account receives data only for the markets it has contracted. A market outside the contract (symbol or `market`) returns 403 `MARKET_NOT_ENTITLED` before any limit is counted; Japan (`JP`) and China (`CN`) return 400 `MARKET_NOT_AVAILABLE` (coming soon). For POST /query, authentication applies first; if every line is outside the contract, it returns 403 with zero per-minute, ordinary daily and AI calls. A storage failure or timeout during key, plan, company or market resolution returns HTTP 503 `UNAVAILABLE` with zero per-minute, ordinary daily and AI calls, without falling back to Free. Otherwise it returns HTTP 200 with per-line errors and counts as one ordinary call.", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "symbol", "in": "path", "required": true, "description": "Korean 6-digit symbol code (005930) or US ticker (AAPL)", "schema": { "type": "string", "example": "005930" } }, { "name": "market", "in": "query", "required": false, "description": "Optional — the market is determined by the symbol code (Korean 6-digit code or US ticker). If given, verifies that the symbol belongs to that market (otherwise 400 BAD_SYMBOL).", "schema": { "type": "string", "enum": [ "KR", "US" ] } }, { "name": "period", "in": "query", "required": false, "description": "Period — 2026Q3 or FY2027Q2 (quarterly); FY2026 or 2026 (annual); last or next (previous / next quarter). If omitted, the latest and next periods. Anything else returns 400 BAD_PERIOD", "schema": { "type": "string", "maxLength": 20, "example": "FY2026" } }, { "name": "unit", "in": "query", "required": false, "description": "Amount unit — raw (KRW/USD as-is, default); eok (억원 = KRW 100 million, Korea only); million (KRW million / USD million)", "schema": { "type": "string", "enum": [ "raw", "eok", "million" ], "default": "raw" } }, { "name": "as_of", "in": "query", "required": false, "description": "Point-in-time date YYYY-MM-DD (Korea-time calendar day, 2000-01-01 to today). Only values recorded by that day — no look-ahead; items not yet recorded are listed in not_covered. Latest values if omitted", "schema": { "type": "string", "format": "date", "example": "2026-10-14" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Quota-Period": { "$ref": "#/components/headers/X-Quota-Period" }, "X-Quota-Reset": { "$ref": "#/components/headers/X-Quota-Reset" }, "X-Markets": { "$ref": "#/components/headers/X-Markets" }, "X-Plan": { "$ref": "#/components/headers/X-Plan" }, "X-Plan-Tier": { "$ref": "#/components/headers/X-Plan-Tier" }, "X-Plan-Expires": { "$ref": "#/components/headers/X-Plan-Expires" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "symbol": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "market": { "type": "string", "enum": [ "KR", "US" ] }, "currency": { "type": [ "string", "null" ], "enum": [ "KRW", "USD", null ] }, "unit": { "type": [ "string", "null" ], "enum": [ "KRW", "USD", "KRW_EOK", "KRW_MIL", "USD_MIL", null ] }, "unit_scale": { "type": "number" }, "label": { "type": "string" }, "as_of": { "type": "string", "format": "date", "description": "Only with `as_of` — the requested point-in-time date" }, "coverage": { "$ref": "#/components/schemas/ConsensusCoverage", "description": "Only with `as_of` — record depth and items with no record on that date" }, "periods": { "type": "array", "items": { "type": "object", "properties": { "period": { "type": "string" }, "period_code": { "type": "string", "example": "2026Q3" }, "period_type": { "type": "string", "enum": [ "annual", "quarterly" ] }, "fiscal_year": { "type": "integer" }, "fiscal_quarter": { "type": [ "integer", "null" ] }, "period_end": { "type": [ "string", "null" ], "format": "date" }, "status": { "type": "string", "enum": [ "reported", "upcoming" ] }, "metrics": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/ConsensusMetric" }, { "$ref": "#/components/schemas/ConsensusMetricAsOf" } ], "description": "ConsensusMetricAsOf when as_of is given (adds observation date, record start and the reconstructed flag)" } } } } } } }, "meta": { "type": "object", "properties": { "symbol": { "type": "string" }, "market": { "type": "string", "enum": [ "KR", "US" ] }, "as_of": { "type": "string", "format": "date-time" }, "page_url": { "type": "string", "format": "uri" }, "disclaimer": { "type": "string" }, "unit_note": { "type": "string" }, "note": { "type": "string" }, "count": { "type": "integer" }, "issuer_symbol": { "type": "string", "example": "005930", "description": "Symbol whose company-level data (filings, ownership, insiders, treasury stock, financials, consensus …) was read — for Korean preferred shares (e.g. 005935, 005385, 000815) the issuer's common share (005930, 005380, 000810); otherwise the requested symbol" }, "share_class": { "type": [ "string", "null" ], "enum": [ "common", "preferred", null ], "description": "Korean share class — common or preferred. Null for US symbols (not determined)" }, "issuer_note": { "type": "string", "description": "Preferred shares only — note that company-level data is the issuer's" }, "trade_evidence_reason": { "type": "string", "enum": [ "trade_evidence_unavailable" ] }, "listing_status": { "type": "string", "enum": [ "listed", "suspended", "delisting", "inactive", "delisted", "unknown" ], "description": "Listing and trading status of a Korean symbol (the same decision as data.status.status of /quotes/{symbol}). Absent for US symbols" } }, "description": "Common metadata for company endpoints (each endpoint adds more fields, such as note and unit_note).", "additionalProperties": true } }, "required": [ "data", "meta" ] }, "example": { "data": { "symbol": "005930", "name": "삼성전자", "market": "KR", "currency": "KRW", "unit": "KRW", "unit_scale": 1, "label": "시장 컨센서스(증권사 추정 종합)", "periods": [ { "period": "2026 3분기", "period_code": "2026Q3", "period_type": "quarterly", "fiscal_year": 2026, "fiscal_quarter": 3, "period_end": "2026-09-30", "status": "upcoming", "metrics": [ { "metric": "revenue", "name": "매출액", "currency": "KRW", "unit": "KRW", "unit_scale": 1, "consensus": 81250000000000, "as_of": "2026-10-20", "estimate_date": null, "revisions": { "1w": { "from": 80900000000000, "from_date": "2026-10-13", "change_pct": 0.43 }, "4w": null, "12w": null }, "actual": null, "reported_on": null, "actual_source": null, "consensus_at_report": null, "consensus_at_report_date": null, "consensus_at_report_basis": null, "vs_consensus_pct": null, "comparison_status": "upcoming", "comparison_note": null }, { "metric": "operating_income", "name": "영업이익", "currency": "KRW", "unit": "KRW", "unit_scale": 1, "consensus": 10340000000000, "as_of": "2026-10-20", "estimate_date": null, "revisions": { "1w": null, "4w": null, "12w": null }, "actual": null, "reported_on": null, "actual_source": null, "consensus_at_report": null, "consensus_at_report_date": null, "consensus_at_report_basis": null, "vs_consensus_pct": null, "comparison_status": "upcoming", "comparison_note": null } ] }, { "period": "2026 2분기", "period_code": "2026Q2", "period_type": "quarterly", "fiscal_year": 2026, "fiscal_quarter": 2, "period_end": "2026-06-30", "status": "reported", "metrics": [ { "metric": "operating_income", "name": "영업이익", "currency": "KRW", "unit": "KRW", "unit_scale": 1, "consensus": 8467387083333, "as_of": "2026-10-20", "estimate_date": null, "revisions": { "1w": null, "4w": null, "12w": null }, "actual": 8949241200000, "reported_on": "2026-07-07", "actual_source": { "kind": "dart", "doc": "반기보고서", "id": "20260814001234", "url": "https://dart.fss.or.kr/dsaf001/main.do?rcpNo=20260814001234" }, "consensus_at_report": null, "consensus_at_report_date": null, "consensus_at_report_basis": null, "consensus_at_report_as_of": "2026-07-06", "consensus_at_report_source": null, "consensus_at_report_reconstructed": null, "vs_consensus_pct": null, "comparison_status": "no_pre_report_estimate", "comparison_note": "No pre-report consensus is available for the day before the release." } ] } ] }, "meta": { "symbol": "005930", "market": "KR", "as_of": "2026-10-21T06:30:00.000Z", "page_url": "https://www.chickstockfi.com/stocks/005930", "disclaimer": "공식 공시(DART·SEC)와 회사 IR 자료를 바탕으로 Phoenix AI가 정리·계산한 참고 자료입니다. 투자 권유가 아니며 정확성·완전성을 보장하지 않습니다.", "source": "PheonixAI", "metrics": [ "revenue", "operating_income" ], "unit": "KRW", "unit_scale": 1, "excluded": [ "eps", "net_income", "target_price", "analysts", "brokers", "reports" ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequiredOrMarket" }, "404": { "description": "No consensus — NOT_FOUND (the symbol exists but the requested data or period does not); SYMBOL_NOT_FOUND (symbol unknown to Phoenix AI); NOT_APPLICABLE (fund-type products such as ETFs and ETNs, for which company data does not apply)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "NOT_FOUND": { "value": { "error": { "code": "NOT_FOUND", "message": "No revenue or operating income consensus is available for this company or period.", "docs": "https://openapi.chickstockfi.com/docs" } } }, "SYMBOL_NOT_FOUND": { "value": { "error": { "code": "SYMBOL_NOT_FOUND", "message": "Unknown symbol 'ZZZZZZ'. Use a listed Korean 6-character code (e.g. 005930) or a US-listed ticker (e.g. AAPL).", "docs": "https://openapi.chickstockfi.com/docs" } } }, "NOT_APPLICABLE": { "value": { "error": { "code": "NOT_APPLICABLE", "message": "069500 is a fund-type security (ETF/ETN); company financials … do not apply.", "docs": "https://openapi.chickstockfi.com/docs" } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/companies/{symbol}/guidance": { "get": { "operationId": "getCompanyGuidance", "tags": [ "Guidance" ], "summary": "Reported results vs. company guidance", "x-summary-en": "Reported results vs. company guidance", "x-markets": [ "KR", "US" ], "x-market-scoped": true, "description": "Returns, by line item, the actual results for one fiscal period alongside company guidance (forecast figures the company disclosed) and the difference versus guidance (%).\n\n- Actuals: Korea — DART periodic reports and preliminary earnings filings; US — SEC 10-Q and 10-K (before the periodic report is filed, revenue and GAAP diluted EPS from the 8-K earnings release table, as preliminary values — `preliminary`). Includes receipt/accession numbers and source links.\n- Guidance: Korea — operating results forecast filings (stored parse results); US — outlook statements in 8-K earnings releases.\n- Pre-report market consensus and surprise (%) are included for revenue and operating income only (null for EPS and net income items).\n- If the basis differs (currency, quarterly vs. cumulative, consolidated vs. separate, controlling vs. total, EPS basis), no comparison is made and the reason is given in `reasons`.\n\n> Markets: KR · US\n\n> 🔒 **Paid tiers only** (Launch, Business, Scale, Enterprise; PoC included) — Free keys and accounts whose paid-tier term has ended receive 403 `PLAN_REQUIRED`; accounts whose PoC has ended receive 403 `POC_ENDED`.\n\n> 🌐 **Data coverage** — the account receives data only for the markets it has contracted. A market outside the contract (symbol or `market`) returns 403 `MARKET_NOT_ENTITLED` before any limit is counted; Japan (`JP`) and China (`CN`) return 400 `MARKET_NOT_AVAILABLE` (coming soon). For POST /query, authentication applies first; if every line is outside the contract, it returns 403 with zero per-minute, ordinary daily and AI calls. A storage failure or timeout during key, plan, company or market resolution returns HTTP 503 `UNAVAILABLE` with zero per-minute, ordinary daily and AI calls, without falling back to Free. Otherwise it returns HTTP 200 with per-line errors and counts as one ordinary call.", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "symbol", "in": "path", "required": true, "description": "Korean 6-digit symbol code (005930) or US ticker (AAPL)", "schema": { "type": "string", "example": "005930" } }, { "name": "market", "in": "query", "required": false, "description": "Optional — the market is determined by the symbol code (Korean 6-digit code or US ticker). If given, verifies that the symbol belongs to that market (otherwise 400 BAD_SYMBOL).", "schema": { "type": "string", "enum": [ "KR", "US" ] } }, { "name": "period", "in": "query", "required": false, "description": "Fiscal period — 2026Q3, FY2027Q2, or 2026 3분기 (quarterly); FY2026 or 2026 (annual); last (previous quarter). If omitted, the most recently reported period. Anything else returns 400 BAD_PERIOD", "schema": { "type": "string", "maxLength": 20, "example": "2026Q2" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Quota-Period": { "$ref": "#/components/headers/X-Quota-Period" }, "X-Quota-Reset": { "$ref": "#/components/headers/X-Quota-Reset" }, "X-Markets": { "$ref": "#/components/headers/X-Markets" }, "X-Plan": { "$ref": "#/components/headers/X-Plan" }, "X-Plan-Tier": { "$ref": "#/components/headers/X-Plan-Tier" }, "X-Plan-Expires": { "$ref": "#/components/headers/X-Plan-Expires" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "symbol": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "market": { "type": "string", "enum": [ "KR", "US" ] }, "currency": { "type": [ "string", "null" ] }, "period": { "type": [ "string", "null" ] }, "period_code": { "type": [ "string", "null" ], "example": "2026Q3", "description": "'2026Q3'; 'FY2026' for annual" }, "period_type": { "type": [ "string", "null" ] }, "fiscal_year": { "type": [ "integer", "null" ] }, "fiscal_quarter": { "type": [ "integer", "null" ] }, "period_end": { "type": [ "string", "null" ] }, "release_date": { "type": [ "string", "null" ], "format": "date" }, "release_basis": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": [ "string", "null" ] }, "what": { "type": [ "string", "null" ] }, "id": { "type": [ "string", "null" ] } } } }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/GuidanceRow" } }, "outlook": { "type": "array", "items": { "$ref": "#/components/schemas/GuidanceOutlook" }, "description": "Company outlook for periods after this one (next quarter, full year) — as of the most recent filing, with source quotes" } } }, "meta": { "type": "object", "properties": { "symbol": { "type": "string" }, "market": { "type": "string", "enum": [ "KR", "US" ] }, "as_of": { "type": "string", "format": "date-time" }, "page_url": { "type": "string", "format": "uri" }, "disclaimer": { "type": "string" }, "unit_note": { "type": "string" }, "note": { "type": "string" }, "count": { "type": "integer" }, "issuer_symbol": { "type": "string", "example": "005930", "description": "Symbol whose company-level data (filings, ownership, insiders, treasury stock, financials, consensus …) was read — for Korean preferred shares (e.g. 005935, 005385, 000815) the issuer's common share (005930, 005380, 000810); otherwise the requested symbol" }, "share_class": { "type": [ "string", "null" ], "enum": [ "common", "preferred", null ], "description": "Korean share class — common or preferred. Null for US symbols (not determined)" }, "issuer_note": { "type": "string", "description": "Preferred shares only — note that company-level data is the issuer's" }, "trade_evidence_reason": { "type": "string", "enum": [ "trade_evidence_unavailable" ] }, "listing_status": { "type": "string", "enum": [ "listed", "suspended", "delisting", "inactive", "delisted", "unknown" ], "description": "Listing and trading status of a Korean symbol (the same decision as data.status.status of /quotes/{symbol}). Absent for US symbols" } }, "description": "Common metadata for company endpoints (each endpoint adds more fields, such as note and unit_note).", "additionalProperties": true } }, "required": [ "data", "meta" ] }, "example": { "data": { "symbol": "AAPL", "name": "애플", "market": "US", "currency": "USD", "period": "FY2026 Q3", "period_code": "2026Q3", "period_type": "quarterly", "fiscal_year": 2026, "fiscal_quarter": 3, "period_end": "2026-06-27", "release_date": "2026-07-30", "release_basis": [ { "date": "2026-07-30", "what": "8-K 실적 발표", "id": "0000320193-26-000068" } ], "rows": [ { "metric": "revenue", "name": "매출액", "currency": "USD", "unit": "USD", "unit_scale": 1, "display_unit": "백만달러", "display_scale": 1000000, "basis": "연결 · 3개월", "status": "compared", "reported": { "value": 94036000000, "text": "940.4억달러", "preliminary": false, "source": { "kind": "sec", "doc": "10-Q", "id": "0000320193-26-000071", "filed_on": "2026-08-01", "url": "https://www.sec.gov/Archives/edgar/data/320193/000032019326000071/0000320193-26-000071-index.htm" }, "derived_from": [], "derivation": null }, "guidance": null, "vs_guidance_pct": null, "guidance_position": null, "consensus": { "value": 89300000000, "text": "893억달러", "label": "시장 컨센서스(증권사 추정 종합)", "observed_on": "2026-07-29", "basis": "observed", "comparable": true, "source": "PheonixAI" }, "surprise_pct": 5.3, "reasons": [] } ], "outlook": [ { "metric": "eps_adjusted", "name": "조정 EPS", "period": "FY2026 연간", "period_type": "annual", "fiscal_year": 2026, "fiscal_quarter": null, "period_end": "2026-09-26", "currency": "USD", "unit": "USD_PER_SHARE", "unit_scale": 1, "low": 7.65, "high": 7.75, "bound": "range", "text": "$7.65 ~ $7.75", "basis": "adjusted", "statement": null, "issued_on": "2026-07-30", "action": "raised", "action_basis": "stated", "prior": null, "quote": "Adjusted EPS* of $7.65 - $7.75, up from $7.10 - $7.25", "source": { "kind": "sec", "doc": "8-K 실적 발표", "id": "0000320193-26-000068", "filed_on": "2026-07-30", "url": null } } ] }, "meta": { "symbol": "AAPL", "market": "US", "as_of": "2026-10-21T06:30:00.000Z", "page_url": "https://www.chickstockfi.com/stocks/AAPL", "disclaimer": "공식 공시(DART·SEC)와 회사 IR 자료를 바탕으로 Phoenix AI가 정리·계산한 참고 자료입니다. 투자 권유가 아니며 정확성·완전성을 보장하지 않습니다.", "unit_note": "금액 value·low·high는 기본 단위(원·달러) — unit·unit_scale(1). display_unit·display_scale은 표 단위" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequiredOrMarket" }, "404": { "description": "No earnings data — NOT_FOUND (the symbol exists but the requested data or period does not); SYMBOL_NOT_FOUND (symbol unknown to Phoenix AI); NOT_APPLICABLE (fund-type products such as ETFs and ETNs, for which company data does not apply)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "NOT_FOUND": { "value": { "error": { "code": "NOT_FOUND", "message": "No reported figures for the requested period. Available periods: 2026Q3, 2026Q2.", "docs": "https://openapi.chickstockfi.com/docs" } } }, "SYMBOL_NOT_FOUND": { "value": { "error": { "code": "SYMBOL_NOT_FOUND", "message": "Unknown symbol 'ZZZZZZ'. Use a listed Korean 6-character code (e.g. 005930) or a US-listed ticker (e.g. AAPL).", "docs": "https://openapi.chickstockfi.com/docs" } } }, "NOT_APPLICABLE": { "value": { "error": { "code": "NOT_APPLICABLE", "message": "069500 is a fund-type security (ETF/ETN); company financials … do not apply.", "docs": "https://openapi.chickstockfi.com/docs" } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/companies/{symbol}/earnings-surprises": { "get": { "operationId": "getUsEarningsSurprises", "tags": [ "Consensus" ], "summary": "EPS surprises and estimates (US)", "x-summary-en": "EPS surprises and estimates (US)", "x-markets": [ "US" ], "x-market-scoped": true, "description": "US-listed companies only — quarterly earnings releases with EPS estimate, actual and surprise (%) for about the last six years, the next scheduled release with its estimate ranges, and EPS and revenue estimates for the current and next quarter and the current and next fiscal year (mean, low, high, number of analysts) with the EPS estimate 7, 30, 60 and 90 days ago and the number of upward and downward revisions.\n\n- The release history is sorted oldest first; an entry without an actual has not been reported yet.\n- `session`: bmo (before the open), amc (after the close), dmh (during market hours), null (time not given).\n- EPS is in US dollars per share and revenue in US dollars. Missing values are null, never zero.\n- Refreshed daily (every 6 hours within three days of a release). `data.as_of` is the last check.\n- Coverage: the S&P 500, US companies with a market cap of $10B or more, and widely followed US symbols. A symbol not collected yet returns 404 NOT_FOUND.\n- Korean symbols return 400 UNSUPPORTED_MARKET. Revenue and operating-income consensus: `/companies/{symbol}/consensus`.\n\n> Markets: US\n\n> 🔒 **Paid tiers only** (Launch, Business, Scale, Enterprise; PoC included) — Free keys and accounts whose paid-tier term has ended receive 403 `PLAN_REQUIRED`; accounts whose PoC has ended receive 403 `POC_ENDED`.\n\n> 🌐 **Data coverage** — the account receives data only for the markets it has contracted. A market outside the contract (symbol or `market`) returns 403 `MARKET_NOT_ENTITLED` before any limit is counted; Japan (`JP`) and China (`CN`) return 400 `MARKET_NOT_AVAILABLE` (coming soon). For POST /query, authentication applies first; if every line is outside the contract, it returns 403 with zero per-minute, ordinary daily and AI calls. A storage failure or timeout during key, plan, company or market resolution returns HTTP 503 `UNAVAILABLE` with zero per-minute, ordinary daily and AI calls, without falling back to Free. Otherwise it returns HTTP 200 with per-line errors and counts as one ordinary call.", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "symbol", "in": "path", "required": true, "description": "US ticker (e.g. AAPL, BRK.B)", "schema": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9.]{0,11}$", "example": "AAPL" } }, { "name": "market", "in": "query", "required": false, "description": "Optional — the market is determined by the symbol code (Korean 6-digit code or US ticker). If given, verifies that the symbol belongs to that market (otherwise 400 BAD_SYMBOL). Only US symbols are supported (others return 400 UNSUPPORTED_MARKET).", "schema": { "type": "string", "enum": [ "KR", "US" ] } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Quota-Period": { "$ref": "#/components/headers/X-Quota-Period" }, "X-Quota-Reset": { "$ref": "#/components/headers/X-Quota-Reset" }, "X-Markets": { "$ref": "#/components/headers/X-Markets" }, "X-Plan": { "$ref": "#/components/headers/X-Plan" }, "X-Plan-Tier": { "$ref": "#/components/headers/X-Plan-Tier" }, "X-Plan-Expires": { "$ref": "#/components/headers/X-Plan-Expires" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "symbol": { "type": "string" }, "market": { "type": "string", "enum": [ "US" ] }, "currency": { "type": "string" }, "as_of": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "history": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "at": { "type": "string", "format": "date-time" }, "session": { "type": [ "string", "null" ], "enum": [ "bmo", "amc", "dmh", null ] }, "eps_estimate": { "type": [ "number", "null" ] }, "eps_actual": { "type": [ "number", "null" ] }, "surprise_pct": { "type": [ "number", "null" ] }, "status": { "type": "string", "enum": [ "reported", "upcoming" ] } } } }, "next": { "type": [ "object", "null" ], "properties": { "at": { "type": [ "string", "null" ], "format": "date-time" }, "call_at": { "type": [ "string", "null" ], "format": "date-time" }, "is_estimate": { "type": [ "boolean", "null" ] }, "eps": { "type": "object", "properties": { "avg": { "type": [ "number", "null" ] }, "low": { "type": [ "number", "null" ] }, "high": { "type": [ "number", "null" ] } } }, "revenue": { "type": "object", "properties": { "avg": { "type": [ "number", "null" ] }, "low": { "type": [ "number", "null" ] }, "high": { "type": [ "number", "null" ] } } } } }, "estimates": { "type": "array", "items": { "type": "object", "properties": { "period": { "type": "string", "enum": [ "current_quarter", "next_quarter", "current_year", "next_year" ] }, "end_date": { "type": [ "string", "null" ], "format": "date" }, "eps": { "type": "object", "properties": { "avg": { "type": [ "number", "null" ] }, "low": { "type": [ "number", "null" ] }, "high": { "type": [ "number", "null" ] }, "analysts": { "type": [ "integer", "null" ] }, "year_ago": { "type": [ "number", "null" ] }, "growth": { "type": [ "number", "null" ] } } }, "revenue": { "type": "object", "properties": { "avg": { "type": [ "number", "null" ] }, "low": { "type": [ "number", "null" ] }, "high": { "type": [ "number", "null" ] }, "analysts": { "type": [ "integer", "null" ] }, "year_ago": { "type": [ "number", "null" ] }, "growth": { "type": [ "number", "null" ] } } }, "eps_trend": { "type": "object", "properties": { "current": { "type": [ "number", "null" ] }, "d7": { "type": [ "number", "null" ] }, "d30": { "type": [ "number", "null" ] }, "d60": { "type": [ "number", "null" ] }, "d90": { "type": [ "number", "null" ] } } }, "eps_revisions": { "type": "object", "properties": { "up_7d": { "type": [ "integer", "null" ] }, "up_30d": { "type": [ "integer", "null" ] }, "down_7d": { "type": [ "integer", "null" ] }, "down_30d": { "type": [ "integer", "null" ] } } } } } } } }, "meta": { "type": "object", "properties": { "symbol": { "type": "string" }, "market": { "type": "string", "enum": [ "KR", "US" ] }, "as_of": { "type": "string", "format": "date-time" }, "page_url": { "type": "string", "format": "uri" }, "disclaimer": { "type": "string" }, "unit_note": { "type": "string" }, "note": { "type": "string" }, "count": { "type": "integer" }, "issuer_symbol": { "type": "string", "example": "005930", "description": "Symbol whose company-level data (filings, ownership, insiders, treasury stock, financials, consensus …) was read — for Korean preferred shares (e.g. 005935, 005385, 000815) the issuer's common share (005930, 005380, 000810); otherwise the requested symbol" }, "share_class": { "type": [ "string", "null" ], "enum": [ "common", "preferred", null ], "description": "Korean share class — common or preferred. Null for US symbols (not determined)" }, "issuer_note": { "type": "string", "description": "Preferred shares only — note that company-level data is the issuer's" }, "trade_evidence_reason": { "type": "string", "enum": [ "trade_evidence_unavailable" ] }, "listing_status": { "type": "string", "enum": [ "listed", "suspended", "delisting", "inactive", "delisted", "unknown" ], "description": "Listing and trading status of a Korean symbol (the same decision as data.status.status of /quotes/{symbol}). Absent for US symbols" } }, "description": "Common metadata for company endpoints (each endpoint adds more fields, such as note and unit_note).", "additionalProperties": true } }, "required": [ "data", "meta" ] }, "example": { "data": { "symbol": "AAPL", "market": "US", "currency": "USD", "as_of": "2026-10-26T08:40:00.000Z", "updated_at": "2026-10-26T08:40:00.000Z", "history": [ { "date": "2026-07-30", "at": "2026-07-30T20:30:28.000Z", "session": "amc", "eps_estimate": 1.89, "eps_actual": 2.02, "surprise_pct": 6.74, "status": "reported" }, { "date": "2026-11-02", "at": "2026-11-02T20:00:00.000Z", "session": "amc", "eps_estimate": 1.98, "eps_actual": null, "surprise_pct": null, "status": "upcoming" } ], "next": { "at": "2026-11-02T20:00:00.000Z", "call_at": "2026-11-02T22:00:00.000Z", "is_estimate": false, "eps": { "avg": 1.98335, "low": 1.93, "high": 2.06 }, "revenue": { "avg": 113381085200, "low": 112525022000, "high": 116186700000 } }, "estimates": [ { "period": "current_quarter", "end_date": "2026-09-30", "eps": { "avg": 1.97965, "low": 1.93, "high": 2.06, "analysts": 27, "year_ago": 1.85, "growth": 0.0701 }, "revenue": { "avg": 113381085200, "low": 112525022000, "high": 116186700000, "analysts": 25, "year_ago": 102466000000, "growth": 0.1065 }, "eps_trend": { "current": 1.97965, "d7": 1.97842, "d30": 1.97754, "d60": 1.97656, "d90": 2.00997 }, "eps_revisions": { "up_7d": 0, "up_30d": 1, "down_7d": 1, "down_30d": 1 } } ] }, "meta": { "symbol": "AAPL", "market": "US", "as_of": "2026-10-21T06:30:00.000Z", "page_url": "https://www.chickstockfi.com/stocks/AAPL", "disclaimer": "공식 공시(DART·SEC)와 회사 IR 자료를 바탕으로 Phoenix AI가 정리·계산한 참고 자료입니다. 투자 권유가 아니며 정확성·완전성을 보장하지 않습니다.", "source": "PheonixAI", "unit_note": "EPS: USD per share · revenue: USD" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequiredOrMarket" }, "404": { "description": "No collected data — NOT_FOUND (the symbol exists but nothing has been collected for it yet); SYMBOL_NOT_FOUND (symbol unknown to Phoenix AI); NOT_APPLICABLE (fund-type products such as ETFs and ETNs, for which company data does not apply)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "NOT_FOUND": { "value": { "error": { "code": "NOT_FOUND", "message": "No earnings or analyst data has been collected for this US symbol yet.", "docs": "https://openapi.chickstockfi.com/docs" } } }, "SYMBOL_NOT_FOUND": { "value": { "error": { "code": "SYMBOL_NOT_FOUND", "message": "Unknown symbol 'ZZZZZZ'. Use a listed Korean 6-character code (e.g. 005930) or a US-listed ticker (e.g. AAPL).", "docs": "https://openapi.chickstockfi.com/docs" } } }, "NOT_APPLICABLE": { "value": { "error": { "code": "NOT_APPLICABLE", "message": "069500 is a fund-type security (ETF/ETN); company financials … do not apply.", "docs": "https://openapi.chickstockfi.com/docs" } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/companies/{symbol}/analyst-ratings": { "get": { "operationId": "getUsAnalystRatings", "tags": [ "Consensus" ], "summary": "Analyst ratings and price targets (US)", "x-summary-en": "Analyst ratings and price targets (US)", "x-markets": [ "US" ], "x-market-scoped": true, "description": "US-listed companies only — broker rating and price-target changes (last two years, newest first), the monthly rating distribution (last four months) and the price-target summary (mean, median, high, low, number of analysts).\n\n- `action`: up (upgrade), down (downgrade), main (maintained), init (initiated), reit (reiterated). A change without a price target has target null.\n- Broker names only; analyst names are not included.\n- Refreshed daily (every 6 hours within three days of a release). `data.as_of` is the last check.\n- Coverage: the S&P 500, US companies with a market cap of $10B or more, and widely followed US symbols. A symbol not collected yet returns 404 NOT_FOUND.\n- Korean symbols return 400 UNSUPPORTED_MARKET.\n\n> Markets: US\n\n> 🔒 **Paid tiers only** (Launch, Business, Scale, Enterprise; PoC included) — Free keys and accounts whose paid-tier term has ended receive 403 `PLAN_REQUIRED`; accounts whose PoC has ended receive 403 `POC_ENDED`.\n\n> 🌐 **Data coverage** — the account receives data only for the markets it has contracted. A market outside the contract (symbol or `market`) returns 403 `MARKET_NOT_ENTITLED` before any limit is counted; Japan (`JP`) and China (`CN`) return 400 `MARKET_NOT_AVAILABLE` (coming soon). For POST /query, authentication applies first; if every line is outside the contract, it returns 403 with zero per-minute, ordinary daily and AI calls. A storage failure or timeout during key, plan, company or market resolution returns HTTP 503 `UNAVAILABLE` with zero per-minute, ordinary daily and AI calls, without falling back to Free. Otherwise it returns HTTP 200 with per-line errors and counts as one ordinary call.", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "symbol", "in": "path", "required": true, "description": "US ticker (e.g. AAPL, BRK.B)", "schema": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9.]{0,11}$", "example": "AAPL" } }, { "name": "market", "in": "query", "required": false, "description": "Optional — the market is determined by the symbol code (Korean 6-digit code or US ticker). If given, verifies that the symbol belongs to that market (otherwise 400 BAD_SYMBOL). Only US symbols are supported (others return 400 UNSUPPORTED_MARKET).", "schema": { "type": "string", "enum": [ "KR", "US" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Number of rating changes (1–200, default 50, newest first)", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Quota-Period": { "$ref": "#/components/headers/X-Quota-Period" }, "X-Quota-Reset": { "$ref": "#/components/headers/X-Quota-Reset" }, "X-Markets": { "$ref": "#/components/headers/X-Markets" }, "X-Plan": { "$ref": "#/components/headers/X-Plan" }, "X-Plan-Tier": { "$ref": "#/components/headers/X-Plan-Tier" }, "X-Plan-Expires": { "$ref": "#/components/headers/X-Plan-Expires" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "symbol": { "type": "string" }, "market": { "type": "string", "enum": [ "US" ] }, "currency": { "type": "string" }, "as_of": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "targets": { "type": [ "object", "null" ], "properties": { "mean": { "type": [ "number", "null" ] }, "median": { "type": [ "number", "null" ] }, "high": { "type": [ "number", "null" ] }, "low": { "type": [ "number", "null" ] }, "analysts": { "type": [ "integer", "null" ] } } }, "recommendation_trend": { "type": "array", "items": { "type": "object", "properties": { "month_offset": { "type": "integer", "minimum": -3, "maximum": 0 }, "strong_buy": { "type": "integer" }, "buy": { "type": "integer" }, "hold": { "type": "integer" }, "sell": { "type": "integer" }, "strong_sell": { "type": "integer" } } } }, "rating_changes": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "at": { "type": "string", "format": "date-time" }, "firm": { "type": "string" }, "action": { "type": [ "string", "null" ], "enum": [ "up", "down", "main", "init", "reit", null ] }, "from_grade": { "type": [ "string", "null" ] }, "to_grade": { "type": [ "string", "null" ] }, "target_action": { "type": [ "string", "null" ] }, "target": { "type": [ "number", "null" ] }, "prior_target": { "type": [ "number", "null" ] } } } }, "total_changes": { "type": "integer" } } }, "meta": { "type": "object", "properties": { "symbol": { "type": "string" }, "market": { "type": "string", "enum": [ "KR", "US" ] }, "as_of": { "type": "string", "format": "date-time" }, "page_url": { "type": "string", "format": "uri" }, "disclaimer": { "type": "string" }, "unit_note": { "type": "string" }, "note": { "type": "string" }, "count": { "type": "integer" }, "issuer_symbol": { "type": "string", "example": "005930", "description": "Symbol whose company-level data (filings, ownership, insiders, treasury stock, financials, consensus …) was read — for Korean preferred shares (e.g. 005935, 005385, 000815) the issuer's common share (005930, 005380, 000810); otherwise the requested symbol" }, "share_class": { "type": [ "string", "null" ], "enum": [ "common", "preferred", null ], "description": "Korean share class — common or preferred. Null for US symbols (not determined)" }, "issuer_note": { "type": "string", "description": "Preferred shares only — note that company-level data is the issuer's" }, "trade_evidence_reason": { "type": "string", "enum": [ "trade_evidence_unavailable" ] }, "listing_status": { "type": "string", "enum": [ "listed", "suspended", "delisting", "inactive", "delisted", "unknown" ], "description": "Listing and trading status of a Korean symbol (the same decision as data.status.status of /quotes/{symbol}). Absent for US symbols" } }, "description": "Common metadata for company endpoints (each endpoint adds more fields, such as note and unit_note).", "additionalProperties": true } }, "required": [ "data", "meta" ] }, "example": { "data": { "symbol": "AAPL", "market": "US", "currency": "USD", "as_of": "2026-10-26T08:40:00.000Z", "updated_at": "2026-10-26T08:40:00.000Z", "targets": { "mean": 329.24768, "median": 335, "high": 405, "low": 240, "analysts": 39 }, "recommendation_trend": [ { "month_offset": 0, "strong_buy": 6, "buy": 18, "hold": 14, "sell": 3, "strong_sell": 3 } ], "rating_changes": [ { "at": "2026-10-20T18:00:28.000Z", "date": "2026-10-20", "firm": "MoffettNathanson", "action": "main", "from_grade": "Neutral", "to_grade": "Neutral", "target_action": "Lowers", "target": 283, "prior_target": 304 }, { "at": "2026-10-20T09:46:57.000Z", "date": "2026-10-20", "firm": "Loop Capital", "action": "down", "from_grade": "Buy", "to_grade": "Hold", "target_action": "Lowers", "target": 330, "prior_target": 370 } ], "total_changes": 40 }, "meta": { "symbol": "AAPL", "market": "US", "as_of": "2026-10-21T06:30:00.000Z", "page_url": "https://www.chickstockfi.com/stocks/AAPL", "disclaimer": "공식 공시(DART·SEC)와 회사 IR 자료를 바탕으로 Phoenix AI가 정리·계산한 참고 자료입니다. 투자 권유가 아니며 정확성·완전성을 보장하지 않습니다.", "source": "PheonixAI", "unit_note": "Price targets in USD" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequiredOrMarket" }, "404": { "description": "No collected data — NOT_FOUND (the symbol exists but nothing has been collected for it yet); SYMBOL_NOT_FOUND (symbol unknown to Phoenix AI); NOT_APPLICABLE (fund-type products such as ETFs and ETNs, for which company data does not apply)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "NOT_FOUND": { "value": { "error": { "code": "NOT_FOUND", "message": "No earnings or analyst data has been collected for this US symbol yet.", "docs": "https://openapi.chickstockfi.com/docs" } } }, "SYMBOL_NOT_FOUND": { "value": { "error": { "code": "SYMBOL_NOT_FOUND", "message": "Unknown symbol 'ZZZZZZ'. Use a listed Korean 6-character code (e.g. 005930) or a US-listed ticker (e.g. AAPL).", "docs": "https://openapi.chickstockfi.com/docs" } } }, "NOT_APPLICABLE": { "value": { "error": { "code": "NOT_APPLICABLE", "message": "069500 is a fund-type security (ETF/ETN); company financials … do not apply.", "docs": "https://openapi.chickstockfi.com/docs" } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/companies/{symbol}/disclosures": { "get": { "operationId": "getCompanyDisclosures", "tags": [ "Filing list" ], "summary": "Company filings (Korea DART, US SEC)", "x-summary-en": "Company filings (Korea DART, US SEC)", "x-markets": [ "KR", "US" ], "x-market-scoped": true, "x-paginated": "cursor", "description": "All stored Korean filings, newest filing date and receipt number first. Coverage varies by issuer and is not limited to one year. from and to are inclusive filing dates (YYYY-MM-DD). form matches literal filing-title fragments (up to 10 comma-separated types), including corrections. Example: `symbol=005930&from=2026-01-01&to=2026-09-30&form=사업보고서`. total counts matches before cursor pagination. Send the same filters with next_cursor on the next page.\n\nFor Korea, include_summary=true attaches stored summaries only (null when absent); exclude_forms excludes the same literal title fragments. US results contain up to 200 recent filings, with form/exclude_forms filtering SEC forms such as 10-K,10-Q,8-K. US date filters are not yet supported. analysis contains the title, publication time and page URL of a reviewed, published analysis.\n\n> Markets: KR · US · Pagination: cursor + limit\n\n> 🔒 **Paid tiers only** (Launch, Business, Scale, Enterprise; PoC included) — Free keys and accounts whose paid-tier term has ended receive 403 `PLAN_REQUIRED`; accounts whose PoC has ended receive 403 `POC_ENDED`.\n\n> 🌐 **Data coverage** — the account receives data only for the markets it has contracted. A market outside the contract (symbol or `market`) returns 403 `MARKET_NOT_ENTITLED` before any limit is counted; Japan (`JP`) and China (`CN`) return 400 `MARKET_NOT_AVAILABLE` (coming soon). For POST /query, authentication applies first; if every line is outside the contract, it returns 403 with zero per-minute, ordinary daily and AI calls. A storage failure or timeout during key, plan, company or market resolution returns HTTP 503 `UNAVAILABLE` with zero per-minute, ordinary daily and AI calls, without falling back to Free. Otherwise it returns HTTP 200 with per-line errors and counts as one ordinary call.", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "symbol", "in": "path", "required": true, "description": "Korean 6-digit symbol code (005930) or US ticker (AAPL)", "schema": { "type": "string", "example": "005930" } }, { "name": "market", "in": "query", "required": false, "description": "Optional — the market is determined by the symbol code (Korean 6-digit code or US ticker). If given, verifies that the symbol belongs to that market (otherwise 400 BAD_SYMBOL).", "schema": { "type": "string", "enum": [ "KR", "US" ] } }, { "name": "cursor", "in": "query", "required": false, "description": "Next page — pass the previous response's next_cursor as-is, with the same filters. Omit for the first page", "schema": { "type": "string", "maxLength": 2100, "example": "c1.eyJrIjpbIjIwMjYtMTAtMjAiLCIyMDI2MTAyMDAwMDEyMyJdLCJmIjoiQWJDZEVmR2hJaksifQ" } }, { "name": "limit", "in": "query", "required": false, "description": "Items per page (1–200, default 50)", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "page", "in": "query", "required": false, "description": "Legacy compatibility (deprecated) — use cursor. Only sets the starting position when no cursor is given", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "deprecated": true }, { "name": "include_summary", "in": "query", "required": false, "description": "Korea — include stored filing summaries", "schema": { "type": "string", "enum": [ "true", "false", "1", "0" ], "default": "false" } }, { "name": "from", "in": "query", "required": false, "description": "Korean filing start date (inclusive)", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "Korean filing end date (inclusive)", "schema": { "type": "string", "format": "date" } }, { "name": "form", "in": "query", "required": false, "description": "Korean title fragments or US SEC forms (comma-separated)", "schema": { "type": "string", "maxLength": 200, "example": "사업보고서" } }, { "name": "exclude_forms", "in": "query", "required": false, "description": "Korean title fragments or US SEC forms to exclude (comma-separated)", "schema": { "type": "string", "maxLength": 200, "example": "424B2,SC 13G" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Quota-Period": { "$ref": "#/components/headers/X-Quota-Period" }, "X-Quota-Reset": { "$ref": "#/components/headers/X-Quota-Reset" }, "X-Markets": { "$ref": "#/components/headers/X-Markets" }, "X-Plan": { "$ref": "#/components/headers/X-Plan" }, "X-Plan-Tier": { "$ref": "#/components/headers/X-Plan-Tier" }, "X-Plan-Expires": { "$ref": "#/components/headers/X-Plan-Expires" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/KrFiling" } }, { "type": "array", "items": { "$ref": "#/components/schemas/UsFiling" } } ], "description": "KrFiling array for Korea, UsFiling array for the US" }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page — null if there are no more pages" }, "has_more": { "type": "boolean", "description": "Whether there is a next page" }, "meta": { "type": "object", "properties": { "symbol": { "type": "string" }, "market": { "type": "string", "enum": [ "KR", "US" ] }, "as_of": { "type": "string", "format": "date-time" }, "page_url": { "type": "string", "format": "uri" }, "disclaimer": { "type": "string" }, "unit_note": { "type": "string" }, "note": { "type": "string" }, "count": { "type": "integer" }, "issuer_symbol": { "type": "string", "example": "005930", "description": "Symbol whose company-level data (filings, ownership, insiders, treasury stock, financials, consensus …) was read — for Korean preferred shares (e.g. 005935, 005385, 000815) the issuer's common share (005930, 005380, 000810); otherwise the requested symbol" }, "share_class": { "type": [ "string", "null" ], "enum": [ "common", "preferred", null ], "description": "Korean share class — common or preferred. Null for US symbols (not determined)" }, "issuer_note": { "type": "string", "description": "Preferred shares only — note that company-level data is the issuer's" }, "trade_evidence_reason": { "type": "string", "enum": [ "trade_evidence_unavailable" ] }, "listing_status": { "type": "string", "enum": [ "listed", "suspended", "delisting", "inactive", "delisted", "unknown" ], "description": "Listing and trading status of a Korean symbol (the same decision as data.status.status of /quotes/{symbol}). Absent for US symbols" } }, "description": "Common metadata for company endpoints (each endpoint adds more fields, such as note and unit_note).", "additionalProperties": true } }, "required": [ "data", "next_cursor", "has_more", "meta" ] }, "example": { "data": [ { "id": "AAPL:0000320193-26-000071", "market": "US", "accession": "0000320193-26-000071", "form": "10-Q", "report_code": "10-Q", "filed_date": "2026-08-01", "report_date": "2026-06-27", "category": "분기보고서", "items": [], "title": "10-Q 분기보고서", "amended": false, "url": "https://www.sec.gov/Archives/edgar/data/320193/000032019326000071/0000320193-26-000071-index.htm", "analysis": { "headline": "서비스 매출이 분기 최대를 다시 썼다", "published_at": "2026-08-01T22:10:00.000Z", "page_url": "https://www.chickstockfi.com/disclosures/AAPL:0000320193-26-000071" } } ], "next_cursor": "c1.eyJrIjpbIjIwMjYtMTAtMjAiLCIyMDI2MTAyMDAwMDEyMyJdLCJmIjoiQWJDZEVmR2hJaksifQ", "has_more": true, "meta": { "count": 1, "symbol": "AAPL", "market": "US", "as_of": "2026-10-21T06:30:00.000Z", "page_url": "https://www.chickstockfi.com/stocks/AAPL", "disclaimer": "공식 공시(DART·SEC)와 회사 IR 자료를 바탕으로 Phoenix AI가 정리·계산한 참고 자료입니다. 투자 권유가 아니며 정확성·완전성을 보장하지 않습니다.", "source": "SEC", "limit": 20 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequiredOrMarket" }, "404": { "description": "No data — NOT_FOUND (the symbol exists but the requested data or period does not); SYMBOL_NOT_FOUND (symbol unknown to Phoenix AI)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "NOT_FOUND": { "value": { "error": { "code": "NOT_FOUND", "message": "No data found for this company.", "docs": "https://openapi.chickstockfi.com/docs" } } }, "SYMBOL_NOT_FOUND": { "value": { "error": { "code": "SYMBOL_NOT_FOUND", "message": "Unknown symbol 'ZZZZZZ'. Use a listed Korean 6-character code (e.g. 005930) or a US-listed ticker (e.g. AAPL).", "docs": "https://openapi.chickstockfi.com/docs" } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/disclosures": { "get": { "operationId": "listDisclosures", "tags": [ "Filing list" ], "summary": "Filings by symbol (Korea DART)", "x-summary-en": "Filings by symbol (Korea DART)", "x-markets": [ "KR" ], "x-market-scoped": true, "x-paginated": "cursor", "description": "All stored Korean filings, newest filing date and receipt number first. Coverage varies by issuer and is not limited to one year. from and to are inclusive filing dates (YYYY-MM-DD). form matches literal filing-title fragments (up to 10 comma-separated types), including corrections. Example: `symbol=005930&from=2026-01-01&to=2026-09-30&form=사업보고서`. total counts matches before cursor pagination. Send the same filters with next_cursor on the next page.\n\n> Markets: KR · Pagination: cursor + limit\n\n> 🔒 **Paid tiers only** (Launch, Business, Scale, Enterprise; PoC included) — Free keys and accounts whose paid-tier term has ended receive 403 `PLAN_REQUIRED`; accounts whose PoC has ended receive 403 `POC_ENDED`.\n\n> 🌐 **Data coverage** — the account receives data only for the markets it has contracted. A market outside the contract (symbol or `market`) returns 403 `MARKET_NOT_ENTITLED` before any limit is counted; Japan (`JP`) and China (`CN`) return 400 `MARKET_NOT_AVAILABLE` (coming soon). For POST /query, authentication applies first; if every line is outside the contract, it returns 403 with zero per-minute, ordinary daily and AI calls. A storage failure or timeout during key, plan, company or market resolution returns HTTP 503 `UNAVAILABLE` with zero per-minute, ordinary daily and AI calls, without falling back to Free. Otherwise it returns HTTP 200 with per-line errors and counts as one ordinary call.", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "symbol", "in": "query", "required": true, "description": "Korean 6-digit code", "schema": { "type": "string", "pattern": "^[A-Za-z0-9.]{1,12}$", "example": "005930" } }, { "name": "market", "in": "query", "required": false, "description": "Market — only KR is supported (KR if omitted; other values return 400 UNSUPPORTED_MARKET)", "schema": { "type": "string", "enum": [ "KR", "US" ], "default": "KR" } }, { "name": "from", "in": "query", "required": false, "description": "Korean filing start date (inclusive)", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "Korean filing end date (inclusive)", "schema": { "type": "string", "format": "date" } }, { "name": "form", "in": "query", "required": false, "description": "Korean filing-title fragments (e.g. 사업보고서,반기보고서)", "schema": { "type": "string", "maxLength": 200, "example": "사업보고서" } }, { "name": "cursor", "in": "query", "required": false, "description": "Next page — pass the previous response's next_cursor as-is, with the same filters. Omit for the first page", "schema": { "type": "string", "maxLength": 2100, "example": "c1.eyJrIjpbIjIwMjYtMTAtMjAiLCIyMDI2MTAyMDAwMDEyMyJdLCJmIjoiQWJDZEVmR2hJaksifQ" } }, { "name": "limit", "in": "query", "required": false, "description": "Items per page (1–200, default 50)", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "page", "in": "query", "required": false, "description": "Legacy compatibility (deprecated) — use cursor. Only sets the starting position when no cursor is given", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "deprecated": true } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Quota-Period": { "$ref": "#/components/headers/X-Quota-Period" }, "X-Quota-Reset": { "$ref": "#/components/headers/X-Quota-Reset" }, "X-Markets": { "$ref": "#/components/headers/X-Markets" }, "X-Plan": { "$ref": "#/components/headers/X-Plan" }, "X-Plan-Tier": { "$ref": "#/components/headers/X-Plan-Tier" }, "X-Plan-Expires": { "$ref": "#/components/headers/X-Plan-Expires" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Disclosure" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page — null if there are no more pages" }, "has_more": { "type": "boolean", "description": "Whether there is a next page" }, "meta": { "type": "object", "properties": { "count": { "type": "integer" }, "total": { "type": "integer" }, "page": { "type": "integer" }, "from": { "type": [ "string", "null" ] }, "to": { "type": [ "string", "null" ] }, "form": { "type": "array", "items": { "type": "string" } }, "note": { "type": "string" }, "symbol": { "type": "string" }, "market": { "type": "string", "enum": [ "KR", "US" ] }, "issuer_symbol": { "type": "string", "example": "005930", "description": "Symbol whose company-level data (filings, ownership, insiders, treasury stock, financials, consensus …) was read — for Korean preferred shares (e.g. 005935, 005385, 000815) the issuer's common share (005930, 005380, 000810); otherwise the requested symbol" }, "share_class": { "type": [ "string", "null" ], "enum": [ "common", "preferred", null ], "description": "Korean share class — common or preferred. Null for US symbols (not determined)" }, "issuer_note": { "type": "string", "description": "Preferred shares only — note that company-level data is the issuer's" }, "as_of": { "type": "string", "format": "date-time" } } } }, "required": [ "data", "next_cursor", "has_more", "meta" ] }, "example": { "data": [ { "id": "20261020000123", "symbol": "005930", "title": "임원ㆍ주요주주특정증권등소유상황보고서", "filer": "삼성전자", "published_at": "2026-10-20", "rcept_no": "20261020000123", "filed_date": "2026-10-20", "url": "https://dart.fss.or.kr/dsaf001/main.do?rcpNo=20261020000123", "market": "KR" } ], "next_cursor": "c1.eyJrIjpbIjIwMjYtMTAtMjAiLCIyMDI2MTAyMDAwMDEyMyJdLCJmIjoiQWJDZEVmR2hJaksifQ", "has_more": true, "meta": { "count": 1, "total": 1, "from": "2026-10-01", "to": "2026-10-22", "form": [ "소유상황보고서" ], "symbol": "005930", "market": "KR", "as_of": "2026-10-21T06:30:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequiredOrMarket" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/disclosures/{id}": { "get": { "operationId": "getDisclosureText", "tags": [ "Filing documents & summaries" ], "summary": "Filing full text (Korea DART)", "x-summary-en": "Filing full text (Korea DART)", "x-markets": [ "KR" ], "x-market-scoped": true, "description": "Filing source document — `format=text` (default) returns the extracted plain text as JSON; `format=raw` returns the original (HTML or DART XML, with content-type set automatically).\n\n- text is at most 50,000 characters (`data.truncated`, `data.full_length`). A stored copy is returned immediately.\n- A well-formed receipt number that does not exist (a filing date in the future, or found neither at DART nor in the Phoenix AI filing ledger) returns 404 `NOT_FOUND` (`reason: not_found`). A filing in the ledger that has no extractable text returns 200 with `data.text_available = false`.\n- If the source cannot be read right now (key, quota, network or viewer failure), both text and raw return 503 `UNAVAILABLE` without storing an empty document. A confirmed empty raw body returns an empty 200 response only when the filing is in the ledger.\n\n> Markets: KR\n\n> 🔒 **Paid tiers only** (Launch, Business, Scale, Enterprise; PoC included) — Free keys and accounts whose paid-tier term has ended receive 403 `PLAN_REQUIRED`; accounts whose PoC has ended receive 403 `POC_ENDED`.\n\n> 🌐 **Data coverage** — the account receives data only for the markets it has contracted. A market outside the contract (symbol or `market`) returns 403 `MARKET_NOT_ENTITLED` before any limit is counted; Japan (`JP`) and China (`CN`) return 400 `MARKET_NOT_AVAILABLE` (coming soon). For POST /query, authentication applies first; if every line is outside the contract, it returns 403 with zero per-minute, ordinary daily and AI calls. A storage failure or timeout during key, plan, company or market resolution returns HTTP 503 `UNAVAILABLE` with zero per-minute, ordinary daily and AI calls, without falling back to Free. Otherwise it returns HTTP 200 with per-line errors and counts as one ordinary call.", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "DART receipt number (14 digits)", "schema": { "type": "string", "pattern": "^\\d{14}$", "example": "20261020000123" } }, { "name": "format", "in": "query", "required": false, "description": "text = plain-text JSON; raw = original document", "schema": { "type": "string", "enum": [ "text", "raw" ], "default": "text" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Quota-Period": { "$ref": "#/components/headers/X-Quota-Period" }, "X-Quota-Reset": { "$ref": "#/components/headers/X-Quota-Reset" }, "X-Markets": { "$ref": "#/components/headers/X-Markets" }, "X-Plan": { "$ref": "#/components/headers/X-Plan" }, "X-Plan-Tier": { "$ref": "#/components/headers/X-Plan-Tier" }, "X-Plan-Expires": { "$ref": "#/components/headers/X-Plan-Expires" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisclosureDetail" }, "example": { "id": "20261020000123", "market": "KR", "text": "임원ㆍ주요주주특정증권등소유상황보고서 …", "length": 4821, "url": "https://dart.fss.or.kr/dsaf001/main.do?rcpNo=20261020000123", "data": { "id": "20261020000123", "market": "KR", "text": "임원ㆍ주요주주특정증권등소유상황보고서 …", "length": 4821, "truncated": false, "full_length": 4821, "text_available": true, "url": "https://dart.fss.or.kr/dsaf001/main.do?rcpNo=20261020000123" }, "meta": { "source": "DART", "as_of": "2026-10-21T06:30:00.000Z" } } }, "text/html": { "schema": { "type": "string" }, "example": "…" }, "application/xml": { "schema": { "type": "string" }, "example": "…" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequiredOrMarket" }, "404": { "description": "No source document · unknown receipt number (reason: not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "No filing with receipt number 20991231000001 was found. Check the 14-digit DART receipt number (rcept_no).", "docs": "https://openapi.chickstockfi.com/docs" } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/disclosures/{id}/summary": { "get": { "operationId": "getDisclosureSummary", "tags": [ "Filing documents & summaries" ], "summary": "AI summary of a filing (Korea DART)", "x-summary-en": "AI summary of a filing (Korea DART)", "x-markets": [ "KR" ], "x-market-scoped": true, "description": "Plain-language summary of a single filing — one-line summary, type, key figures, key facts, and a plain explanation. Once generated, the summary is stored and returned immediately. For documents that are hard to summarize, a link to the source document is returned instead (`summary_available=false`). The query fields are optional metadata taken from the list and do not affect the result.\n\n> Markets: KR\n\n> 🔒 **Paid tiers only** (Launch, Business, Scale, Enterprise; PoC included) — Free keys and accounts whose paid-tier term has ended receive 403 `PLAN_REQUIRED`; accounts whose PoC has ended receive 403 `POC_ENDED`.\n\n> 🌐 **Data coverage** — the account receives data only for the markets it has contracted. A market outside the contract (symbol or `market`) returns 403 `MARKET_NOT_ENTITLED` before any limit is counted; Japan (`JP`) and China (`CN`) return 400 `MARKET_NOT_AVAILABLE` (coming soon). For POST /query, authentication applies first; if every line is outside the contract, it returns 403 with zero per-minute, ordinary daily and AI calls. A storage failure or timeout during key, plan, company or market resolution returns HTTP 503 `UNAVAILABLE` with zero per-minute, ordinary daily and AI calls, without falling back to Free. Otherwise it returns HTTP 200 with per-line errors and counts as one ordinary call.\n\n> 🤖 **AI call** — for PoC, Launch, Business and Scale accounts this counts toward the daily AI-call quota (PoC-Launch default 20, KST; see Plans for other tiers) only when no stored copy exists and one is generated. Stored copies are not counted. Over the quota: 429 `AI_QUOTA_EXCEEDED`. Enterprise has no daily cap. A configured monthly cap returns 429 `AI_MONTHLY_QUOTA_EXCEEDED`.", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "DART receipt number", "schema": { "type": "string", "pattern": "^\\d{14}$", "example": "20261020000123" } }, { "name": "symbol", "in": "query", "required": false, "description": "Symbol code (optional)", "schema": { "type": "string" } }, { "name": "title", "in": "query", "required": false, "description": "Report name (optional)", "schema": { "type": "string" } }, { "name": "filer", "in": "query", "required": false, "description": "Filer (optional)", "schema": { "type": "string" } }, { "name": "published_at", "in": "query", "required": false, "description": "Filing date (optional)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Quota-Period": { "$ref": "#/components/headers/X-Quota-Period" }, "X-Quota-Reset": { "$ref": "#/components/headers/X-Quota-Reset" }, "X-Markets": { "$ref": "#/components/headers/X-Markets" }, "X-Plan": { "$ref": "#/components/headers/X-Plan" }, "X-Plan-Tier": { "$ref": "#/components/headers/X-Plan-Tier" }, "X-Plan-Expires": { "$ref": "#/components/headers/X-Plan-Expires" }, "X-AI-Quota-Limit": { "$ref": "#/components/headers/X-AI-Quota-Limit" }, "X-AI-Quota-Remaining": { "$ref": "#/components/headers/X-AI-Quota-Remaining" }, "X-AI-Quota-Reset": { "$ref": "#/components/headers/X-AI-Quota-Reset" }, "X-AI-Quota-Monthly-Limit": { "$ref": "#/components/headers/X-AI-Quota-Monthly-Limit" }, "X-AI-Quota-Monthly-Remaining": { "$ref": "#/components/headers/X-AI-Quota-Monthly-Remaining" }, "X-AI-Quota-Monthly-Reset": { "$ref": "#/components/headers/X-AI-Quota-Monthly-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DisclosureSummary" }, "meta": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "cache", "fresh", "fallback" ] }, "summary_available": { "type": "boolean" }, "as_of": { "type": "string", "format": "date-time" } } } } }, "example": { "data": { "id": "20261020000456", "market": "KR", "symbol": "005930", "title": "단일판매ㆍ공급계약체결", "filer": "삼성전자", "published_at": "2026-10-20", "headline": "삼성전자가 1.2조원 규모 반도체 공급계약을 맺었다는 공시입니다.", "category": "공급계약", "figures": [ { "label": "계약금액", "value": "1조 2,000억원" } ], "key_facts": [ "계약 기간은 2027년 12월까지입니다." ], "plain": "삼성전자가 해외 고객사와 1조 2,000억원 규모 공급계약을 맺었습니다.", "source": { "url": "https://dart.fss.or.kr/dsaf001/main.do?rcpNo=20261020000456" }, "summary_available": true, "generated_at": "2026-10-20T08:00:00.000Z" }, "meta": { "source": "cache", "summary_available": true, "as_of": "2026-10-21T06:30:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequiredOrMarket" }, "404": { "description": "No source document", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "Filing text not found.", "docs": "https://openapi.chickstockfi.com/docs" } } } } }, "429": { "$ref": "#/components/responses/RateLimitedOrAiQuota" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/symbols": { "get": { "operationId": "listSymbols", "tags": [ "Symbol master" ], "summary": "Korean symbol master and lookup", "x-summary-en": "Korean symbol master and lookup", "x-markets": [ "KR" ], "x-market-scoped": true, "x-paginated": "cursor", "description": "Search the Korean symbol master. q matches code prefixes (optional leading A), Korean names ignoring spaces, and English names ignoring case and punctuation. Rank: exact code, exact name, code prefix, name prefix, name substring, then code. Without q, order by code. Continue with limit and cursor.\n\nThe default is the existing KOSPI/KOSDAQ master. include_delisted=true or status=delisted adds historical securities with verified delisting evidence and stored financial filings. status=all alone does not widen coverage. listing_status equals status. delisted_on is the confirmed delisting date or null, never the last filing date. Historical exchange can be null and then does not match an exchange filter.\n\ntype retains stock/etf/etn/other and uses only official stored attributes. security_subtype is common, preferred, reit, spac, etf, etn, fund, depositary_receipt, other or null. REITs, SPACs and preferred shares remain under stock. Missing or unsupported attributes produce other and type_reason. Names, brands and code shapes are never inferred. A stock without detailed attributes has a null subtype.\n\nIPO and search share current-master code/name and company-information listing date priority. The reference-date fallback displayed in /symbols is not proof of an IPO event. IPO separately verifies ownership, homonyms, transfers and duplicates, so a searchable code can still be null in IPO. English names use registered company names or null. Masters refresh periodically.\n\nBase search remains available when optional reference tables/columns are absent. delisted_on_reason=reference_schema_unavailable means delisting status/date columns are unavailable; delisting_date_unconfirmed means the delisting date is absent or invalid. An unconfirmed security_subtype returns null with security_subtype_reason=master_subtype_unavailable. Reasons are null for confirmed values or inapplicable delisting dates.\n\n> Markets: KR · Pagination: cursor + limit\n\n> 🔒 **Paid tiers only** (Launch, Business, Scale, Enterprise; PoC included) — Free keys and accounts whose paid-tier term has ended receive 403 `PLAN_REQUIRED`; accounts whose PoC has ended receive 403 `POC_ENDED`.\n\n> 🌐 **Data coverage** — the account receives data only for the markets it has contracted. A market outside the contract (symbol or `market`) returns 403 `MARKET_NOT_ENTITLED` before any limit is counted; Japan (`JP`) and China (`CN`) return 400 `MARKET_NOT_AVAILABLE` (coming soon). For POST /query, authentication applies first; if every line is outside the contract, it returns 403 with zero per-minute, ordinary daily and AI calls. A storage failure or timeout during key, plan, company or market resolution returns HTTP 503 `UNAVAILABLE` with zero per-minute, ordinary daily and AI calls, without falling back to Free. Otherwise it returns HTTP 200 with per-line errors and counts as one ordinary call.", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Search text — code prefix, Korean name or English name (full list if omitted)", "schema": { "type": "string", "minLength": 1, "maxLength": 40, "example": "삼성" } }, { "name": "market", "in": "query", "required": false, "description": "Market — only KR is supported (KR if omitted; other values return 400 UNSUPPORTED_MARKET)", "schema": { "type": "string", "enum": [ "KR", "US" ] } }, { "name": "type", "in": "query", "required": false, "description": "Security type — stock · etf · etn · other · all", "schema": { "type": "string", "enum": [ "stock", "etf", "etn", "other", "all" ], "default": "all" } }, { "name": "status", "in": "query", "required": false, "description": "Listing status. delisted has verified delisting evidence; inactive only lacks recent trades.", "schema": { "type": "string", "enum": [ "listed", "suspended", "delisting", "inactive", "delisted", "all" ], "default": "all" } }, { "name": "include_delisted", "in": "query", "required": false, "description": "Include historical securities with delisting evidence and stored financial filings. Default false.", "schema": { "type": "string", "enum": [ "true", "false" ], "default": "false" } }, { "name": "exchange", "in": "query", "required": false, "description": "Listing market (all if omitted)", "schema": { "type": "string", "enum": [ "KOSPI", "KOSDAQ" ] } }, { "name": "cursor", "in": "query", "required": false, "description": "Next page — pass the previous response's next_cursor as-is, with the same filters. Omit for the first page", "schema": { "type": "string", "maxLength": 2100, "example": "c1.eyJrIjpbIjIwMjYtMTAtMjAiLCIyMDI2MTAyMDAwMDEyMyJdLCJmIjoiQWJDZEVmR2hJaksifQ" } }, { "name": "limit", "in": "query", "required": false, "description": "Items per page (1–200, default 50)", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Quota-Period": { "$ref": "#/components/headers/X-Quota-Period" }, "X-Quota-Reset": { "$ref": "#/components/headers/X-Quota-Reset" }, "X-Markets": { "$ref": "#/components/headers/X-Markets" }, "X-Plan": { "$ref": "#/components/headers/X-Plan" }, "X-Plan-Tier": { "$ref": "#/components/headers/X-Plan-Tier" }, "X-Plan-Expires": { "$ref": "#/components/headers/X-Plan-Expires" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/KrSymbol" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page — null if there are no more pages" }, "has_more": { "type": "boolean", "description": "Whether there is a next page" }, "meta": { "type": "object", "properties": { "count": { "type": "integer" }, "market": { "type": "string", "enum": [ "KR" ] }, "q": { "type": [ "string", "null" ] }, "type": { "type": "string" }, "status": { "type": "string" }, "include_delisted": { "type": "boolean" }, "type_note": { "type": "string" }, "listing_note": { "type": "string" }, "reference_note": { "type": "string", "description": "Explains reference-data availability and reasons for null supplemental fields." }, "exchange": { "type": [ "string", "null" ] }, "as_of": { "type": "string", "format": "date-time" }, "trade_date_note": { "type": "string" }, "trade_evidence_reason": { "type": "string", "enum": [ "trade_evidence_unavailable" ] }, "coverage": { "type": "string", "description": "Which instruments this list covers" }, "status_note": { "type": "string", "description": "Meaning of the listing status values" } } } }, "required": [ "data", "next_cursor", "has_more", "meta" ] }, "example": { "data": [ { "symbol": "005930", "market": "KR", "exchange": "KOSPI", "name_ko": "삼성전자", "name_en": "Samsung Electronics", "type": "stock", "security_subtype": "common", "security_subtype_reason": null, "type_reason": null, "listing_status": "listed", "delisted_on": null, "delisted_on_reason": null, "sector": "반도체와반도체장비", "sector_en": "Semiconductors & Semiconductor Equipment", "status": "listed", "listed_date": "1975-06-11", "last_trade_date": "2026-10-21" }, { "symbol": "005935", "market": "KR", "exchange": "KOSPI", "name_ko": "삼성전자우", "name_en": null, "type": "stock", "security_subtype": "preferred", "security_subtype_reason": null, "type_reason": null, "listing_status": "listed", "delisted_on": null, "delisted_on_reason": null, "sector": "반도체와반도체장비", "sector_en": "Semiconductors & Semiconductor Equipment", "status": "listed", "listed_date": null, "last_trade_date": "2026-10-21" } ], "next_cursor": "c1.eyJrIjpbIjIwMjYtMTAtMjAiLCIyMDI2MTAyMDAwMDEyMyJdLCJmIjoiQWJDZEVmR2hJaksifQ", "has_more": true, "meta": { "count": 2, "market": "KR", "q": "삼성전자", "type": "all", "status": "all", "include_delisted": false, "type_note": "공식 마스터 속성으로 분류합니다.", "listing_note": "기본 목록은 현행 마스터 범위입니다.", "reference_note": "참조정보의 표·열이 없어도 기본 검색은 유지됩니다. delisted_on_reason의 reference_schema_unavailable은 폐지 상태·날짜 열을 사용할 수 없음을, delisting_date_unconfirmed는 폐지일 근거가 없거나 유효하지 않음을 뜻합니다. security_subtype이 미확인이면 null과 security_subtype_reason=master_subtype_unavailable을 반환합니다. 확인된 값 또는 해당하지 않는 폐지일에는 사유가 null입니다.", "exchange": null, "as_of": "2026-10-21T06:30:00.000Z", "coverage": "코스피·코스닥 상장 종목 마스터(주식·ETF·ETN, 신형 영숫자 코드 포함).", "status_note": "listed = 최근 7일 안에 거래 기록이 있음 …" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequiredOrMarket" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/quotes/{symbol}": { "get": { "operationId": "getQuote", "tags": [ "Quotes" ], "summary": "Quote and key financials (Korea)", "x-summary-en": "Quote and key financials (Korea)", "x-markets": [ "KR" ], "x-market-scoped": true, "description": "Quote and key financials for a Korean symbol — current price, change, 52-week high/low, valuation.\n\n- **Standard shape `{ data, meta }`**: `data.valuation` is **the same value** as `valuation` in `/companies/{symbol}/metrics` (same function, same cache — basis fields `price`, `price_as_of`, `eps_basis`, `eps_period`, `shares_basis`, `per_basis`; Korean EPS and PER are based on TTM net income attributable to owners of the parent). Not-applicable values that arrive as 0 are returned as null.\n- **Legacy top-level fields (deprecated)**: `symbol`, `price`, `fundamentals`… are kept for legacy clients. From 2026-10-21, `per`, `pbr`, `eps`, `bps` and `dps` in `fundamentals` are the same values as `data.valuation` (null when absent) and `market_cap` is in KRW — previously they were a latest-fiscal-year snapshot, so the same names carried different numbers. `sales`, `operating_profit` and `net_income` are the latest single quarter (KRW, no period label — use `/companies/{symbol}/financials` for financials), and `debt_ratio` is a ratio (0.311 = 31.1%). New code should read `data`. The top-level fields may be removed in the next major version, with prior notice in the changelog.\n- For a preferred share (e.g. 005935), `data.valuation.per_basis` = `preferred_price_over_issuer_eps` (preferred price ÷ issuer common-share EPS) and `meta.issuer_symbol` is the issuer (005930).\n- **Listing and trading status `data.status`**: `status` (listed, suspended, delisting, inactive, delisted, unknown — the same decision as the company `meta.listing_status`), `delisted_on`, `last_trading_day`, `trading_halted`, `halt_reason` (title of the latest trading-halt notice), `designations` (administrative issue, investment caution / warning / risk, short-term overheating, investment caution reminder) and `as_of`. Decided only from stored exchange flags, reference data and filings (cached up to one minute); without evidence it does not assert a state.\n- **`error.reason` of the 404 `NOT_FOUND` when there is no quote**: `delisted`, `delisting` (liquidation trading), `suspended` (trading halt), `inactive` (no recent trades, reason unknown). Without evidence the 404 has no `reason`.\n\n> Markets: KR\n\n> 🔒 **Paid tiers only** (Launch, Business, Scale, Enterprise; PoC included) — Free keys and accounts whose paid-tier term has ended receive 403 `PLAN_REQUIRED`; accounts whose PoC has ended receive 403 `POC_ENDED`.\n\n> 🌐 **Data coverage** — the account receives data only for the markets it has contracted. A market outside the contract (symbol or `market`) returns 403 `MARKET_NOT_ENTITLED` before any limit is counted; Japan (`JP`) and China (`CN`) return 400 `MARKET_NOT_AVAILABLE` (coming soon). For POST /query, authentication applies first; if every line is outside the contract, it returns 403 with zero per-minute, ordinary daily and AI calls. A storage failure or timeout during key, plan, company or market resolution returns HTTP 503 `UNAVAILABLE` with zero per-minute, ordinary daily and AI calls, without falling back to Free. Otherwise it returns HTTP 200 with per-line errors and counts as one ordinary call.", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "symbol", "in": "path", "required": true, "description": "Korean 6-digit symbol code (e.g. 005930; a leading A is ignored)", "schema": { "type": "string", "pattern": "^A?\\d[0-9A-Z]{5}$", "example": "005930" } }, { "name": "market", "in": "query", "required": false, "description": "Optional — the market is determined by the symbol code (Korean 6-digit code or US ticker). If given, verifies that the symbol belongs to that market (otherwise 400 BAD_SYMBOL). Only KR symbols are supported (others return 400 UNSUPPORTED_MARKET).", "schema": { "type": "string", "enum": [ "KR", "US" ] } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Quota-Period": { "$ref": "#/components/headers/X-Quota-Period" }, "X-Quota-Reset": { "$ref": "#/components/headers/X-Quota-Reset" }, "X-Markets": { "$ref": "#/components/headers/X-Markets" }, "X-Plan": { "$ref": "#/components/headers/X-Plan" }, "X-Plan-Tier": { "$ref": "#/components/headers/X-Plan-Tier" }, "X-Plan-Expires": { "$ref": "#/components/headers/X-Plan-Expires" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" }, "example": { "symbol": "005930", "name": "삼성전자", "market": "KOSPI", "currency": "KRW", "price": { "current": 223500, "open": 217000, "high": 228000, "low": 208000, "prev_close": 211500, "change": 12000, "change_rate": 0.0567, "upper_limit": 274500, "lower_limit": 148500 }, "volume": { "trade_value": 1234567890000, "shares": 16391234 }, "range_52w": { "high": 288000, "high_date": "2026-09-08", "low": 98000, "low_date": "2025-11-14" }, "fundamentals": { "market_cap": 1306643268888000, "market_cap_rank": 1, "per": 8.73, "pbr": 2.76, "eps": 25601, "bps": 81071, "dps": 1668, "foreign_ratio": 0.4608, "debt_ratio": 0.311, "sales": 171499470000000, "operating_profit": 89492412000000, "net_income": 71624461000000, "listed_shares": 5846278608 }, "sector": "반도체와반도체장비", "company_summary": null, "market_status": "장중", "as_of": "2026-10-21T06:30:00.000Z", "data": { "symbol": "005930", "name": "삼성전자", "market": "KR", "exchange": "KOSPI", "currency": "KRW", "price": { "current": 223500, "open": 217000, "high": 228000, "low": 208000, "prev_close": 211500, "change": 12000, "change_rate": 0.0567, "upper_limit": 274500, "lower_limit": 148500 }, "volume": { "trade_value": 1234567890000, "shares": 16391234 }, "range_52w": { "high": 288000, "high_date": "2026-09-08", "low": 98000, "low_date": "2025-11-14" }, "valuation": { "market_cap": 13066433, "market_cap_unit": "KRW_EOK", "market_cap_unit_scale": 100000000, "market_cap_raw": 1306643268888000, "as_of": "20261021", "price": 223500, "price_as_of": "2026-10-21T06:30:00.000Z", "price_date": "2026-10-21", "price_time": "2026-10-21T06:30:00.000Z", "period": "최근 4개 분기(2026 반기 TTM)", "basis": "ttm", "per": 8.73, "pbr": 2.76, "psr": 2.69, "eps": 25601, "bps": 81071, "roe": 31.6, "eps_basis": "controlling", "eps_shares": 5846278608, "eps_period": "최근 4개 분기(2026 반기 TTM)", "shares_basis": "common_listed", "per_basis": "market_cap_over_net_income", "share_class": null, "dividend": { "dps": 1668, "yield": 0.75, "payout": 25.1, "years": 4, "currency": "KRW", "dps_basis": "annual_current_share", "fiscal_year": 2025, "dps_reported": 1668, "share_factor": 1, "yield_basis": "annual", "ttm_dps": 1668, "ttm_yield": 0.75 } }, "fundamentals": { "foreign_ratio_pct": 46.08, "listed_shares": 5846278608, "market_cap_rank": 1 }, "sector": "반도체와반도체장비", "market_status": "장중", "status": { "status": "listed", "delisted_on": null, "last_trading_day": "2026-10-20", "trading_halted": false, "halt_reason": null, "halt_notice_date": null, "designations": [], "as_of": "2026-10-20T20:10:00.000Z" }, "as_of": "2026-10-21T06:30:00.000Z" }, "meta": { "symbol": "005930", "market": "KR", "as_of": "2026-10-21T06:30:00.000Z", "legacy_top_level": true, "issuer_symbol": "005930", "share_class": "common", "valuation_note": "data.valuation은 /companies/{symbol}/metrics의 valuation과 같은 값입니다(같은 함수·같은 캐시).", "legacy_note": "최상위 칸은 예전 호환용입니다(deprecated). fundamentals의 per·pbr·eps·bps·dps는 data.valuation과 같은 값, market_cap은 원입니다." } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequiredOrMarket" }, "404": { "description": "No quote — error.reason: delisted · delisting · suspended · inactive (only with evidence)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "115390 is delisted (last exchange filing on 2024-03-28), so there is no current quote. Filing, ownership and event endpoints still return its history.", "docs": "https://openapi.chickstockfi.com/docs" } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/quotes/{symbol}/daily": { "get": { "operationId": "listDailyCloses", "tags": [ "Quotes" ], "summary": "Daily close history (Korea)", "x-summary-en": "Daily close history (Korea)", "x-markets": [ "KR" ], "x-market-scoped": true, "x-paginated": "cursor", "description": "Daily close history for a Korean symbol — close, change, volume, trading value, market capitalisation and listed shares. Only values Phoenix AI has already stored are returned (nothing is fetched at request time).\n\n- **Price basis** (`meta.basis` = `regular_session_official_close`): the **official regular-session closing price** of the Korea Exchange (KRX), set by the closing auction. Not Nextrade (NXT) prices and not pre-market or after-market prices. Only sessions that have ended are included; a session appears the morning after the trading day.\n- **Not adjusted**: values are as published on each date. History is not re-divided after a split or consolidation, so the price level changes on that day — see `meta.splits` (detected events). `change_pct` is the exchange's official change against that day's base price (which reflects ex-rights and splits), so it stays meaningful on split days. Exception: rows with `price_adjustment=adjusted` (market cap null) are fund-type products (ETFs etc.) missing from the exchange's stock batch, filled from a secondary daily series; those values are split-adjusted and their change is computed from consecutive closes.\n- **No open, high or low** (values we do not store are never made up).\n- **History depth**: data starts on 2025-03-31, but before `meta.daily_complete_from` (the first day of the unbroken all-symbol daily series) it is sparse (quarter-end snapshots of all symbols plus some symbols on other days). Per-symbol range: `meta.coverage_start`, `coverage_end`, `stored_days`; days stored inside the requested range: `meta.range_stored_days`.\n- **Range**: `from` and `to` (YYYY-MM-DD, Korea dates). `to` defaults to today, `from` to the beginning. A date that is not on the calendar, a future date, or `from` after `to` returns 400 `BAD_DATE`.\n- **Order and pages**: `order`=desc (newest first, default) or asc + `limit` (default 100, max 500) + `cursor`.\n- An unknown symbol returns 404 `SYMBOL_NOT_FOUND` (find codes with `GET /symbols`). A known symbol with no values in the range returns an empty list.\n\n> Markets: KR · Pagination: cursor + limit\n\n> 🔒 **Paid tiers only** (Launch, Business, Scale, Enterprise; PoC included) — Free keys and accounts whose paid-tier term has ended receive 403 `PLAN_REQUIRED`; accounts whose PoC has ended receive 403 `POC_ENDED`.\n\n> 🌐 **Data coverage** — the account receives data only for the markets it has contracted. A market outside the contract (symbol or `market`) returns 403 `MARKET_NOT_ENTITLED` before any limit is counted; Japan (`JP`) and China (`CN`) return 400 `MARKET_NOT_AVAILABLE` (coming soon). For POST /query, authentication applies first; if every line is outside the contract, it returns 403 with zero per-minute, ordinary daily and AI calls. A storage failure or timeout during key, plan, company or market resolution returns HTTP 503 `UNAVAILABLE` with zero per-minute, ordinary daily and AI calls, without falling back to Free. Otherwise it returns HTTP 200 with per-line errors and counts as one ordinary call.", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "symbol", "in": "path", "required": true, "description": "Korean 6-digit symbol code (e.g. 005930; a leading A is ignored)", "schema": { "type": "string", "pattern": "^A?\\d[0-9A-Z]{5}$", "example": "005930" } }, { "name": "market", "in": "query", "required": false, "description": "Optional — the market is determined by the symbol code (Korean 6-digit code or US ticker). If given, verifies that the symbol belongs to that market (otherwise 400 BAD_SYMBOL). Only KR symbols are supported (others return 400 UNSUPPORTED_MARKET).", "schema": { "type": "string", "enum": [ "KR", "US" ] } }, { "name": "from", "in": "query", "required": false, "description": "Start date YYYY-MM-DD (from the beginning if omitted)", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "End date YYYY-MM-DD (today in Korea if omitted)", "schema": { "type": "string", "format": "date" } }, { "name": "order", "in": "query", "required": false, "description": "desc = newest first (default) · asc = oldest first", "schema": { "type": "string", "enum": [ "desc", "asc" ], "default": "desc" } }, { "name": "cursor", "in": "query", "required": false, "description": "Next page — pass the previous response's next_cursor as-is, with the same filters. Omit for the first page", "schema": { "type": "string", "maxLength": 2100, "example": "c1.eyJrIjpbIjIwMjYtMTAtMjAiLCIyMDI2MTAyMDAwMDEyMyJdLCJmIjoiQWJDZEVmR2hJaksifQ" } }, { "name": "limit", "in": "query", "required": false, "description": "Items per page (1–500, default 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Quota-Period": { "$ref": "#/components/headers/X-Quota-Period" }, "X-Quota-Reset": { "$ref": "#/components/headers/X-Quota-Reset" }, "X-Markets": { "$ref": "#/components/headers/X-Markets" }, "X-Plan": { "$ref": "#/components/headers/X-Plan" }, "X-Plan-Tier": { "$ref": "#/components/headers/X-Plan-Tier" }, "X-Plan-Expires": { "$ref": "#/components/headers/X-Plan-Expires" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/KrDailyClose" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page — null if there are no more pages" }, "has_more": { "type": "boolean", "description": "Whether there is a next page" }, "meta": { "type": "object", "properties": { "count": { "type": "integer" }, "symbol": { "type": "string" }, "market": { "type": "string", "enum": [ "KR" ] }, "name": { "type": [ "string", "null" ] }, "currency": { "type": "string", "enum": [ "KRW" ] }, "order": { "type": "string", "enum": [ "desc", "asc" ] }, "from": { "type": [ "string", "null" ], "format": "date" }, "to": { "type": "string", "format": "date" }, "last_trading_day": { "type": [ "string", "null" ], "format": "date" }, "halt_notice_date": { "type": [ "string", "null" ], "format": "date" }, "halted_on": { "type": [ "string", "null" ], "format": "date" }, "trading_halted": { "type": [ "boolean", "null" ] }, "status_as_of": { "type": [ "string", "null" ], "format": "date-time" }, "trade_date_note": { "type": "string" }, "trade_evidence_reason": { "type": "string", "enum": [ "trade_evidence_unavailable" ] }, "basis": { "type": "string", "enum": [ "regular_session_official_close" ], "description": "Price basis — official regular-session close" }, "basis_note": { "type": "string" }, "price_adjustment": { "type": "string", "enum": [ "none" ], "description": "Adjustment policy of this endpoint — none (no retroactive adjustment; per-row exceptions are in price_adjustment)" }, "adjustment_note": { "type": "string" }, "ohlc_note": { "type": "string" }, "units": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Unit of each field" }, "coverage_start": { "type": [ "string", "null" ], "format": "date", "description": "First stored date for this symbol" }, "coverage_end": { "type": [ "string", "null" ], "format": "date", "description": "Last stored date for this symbol" }, "stored_days": { "type": "integer", "description": "Number of stored days for this symbol (all time)" }, "range_stored_days": { "type": "integer", "description": "Number of stored days inside the requested range (from–to)" }, "daily_complete_from": { "type": [ "string", "null" ], "format": "date", "description": "First day of the unbroken all-symbol daily series (market-wide)" }, "coverage_note": { "type": "string" }, "splits": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/KrSplitEvent" }, "description": "Detected splits and consolidations (oldest first). null if they could not be read" }, "splits_note": { "type": "string" }, "as_of": { "type": "string", "format": "date-time" } } } }, "required": [ "data", "next_cursor", "has_more", "meta" ] }, "example": { "data": [ { "date": "2026-10-20", "close": 75400, "change_pct": 1.07, "volume": 16391234, "trade_value": 1234567890000, "market_cap": 446341701318800, "listed_shares": 5919637922, "price_adjustment": "none" }, { "date": "2026-10-17", "close": 74600, "change_pct": -0.4, "volume": 13820110, "trade_value": 1031234560000, "market_cap": 441605991281200, "listed_shares": 5919637922, "price_adjustment": "none" } ], "next_cursor": "c1.eyJrIjpbIjIwMjYtMTAtMjAiLCIyMDI2MTAyMDAwMDEyMyJdLCJmIjoiQWJDZEVmR2hJaksifQ", "has_more": true, "meta": { "count": 2, "symbol": "005930", "market": "KR", "name": "삼성전자", "currency": "KRW", "order": "desc", "from": null, "to": "2026-10-21", "basis": "regular_session_official_close", "basis_note": "한국거래소(KRX) 정규장 공식 종가(장 마감 단일가)입니다. 대체거래소(NXT)·시간외 가격이 아닙니다.", "price_adjustment": "none", "adjustment_note": "수정주가가 아닙니다 — 그날 공표된 값 그대로입니다.", "ohlc_note": "시가·고가·저가는 이 엔드포인트에 없습니다.", "units": { "close": "KRW", "trade_value": "KRW", "market_cap": "KRW", "volume": "shares", "listed_shares": "shares", "change_pct": "percent" }, "coverage_start": "2025-03-31", "coverage_end": "2026-10-20", "stored_days": 118, "range_stored_days": 118, "daily_complete_from": "2026-06-01", "coverage_note": "이력은 2025-03-31부터 있지만 daily_complete_from 앞은 듬성듬성합니다.", "splits": [], "splits_note": "상장주식수 변화와 거래소 기준가 조정이 함께 나타난 날(분할·병합).", "as_of": "2026-10-21T06:30:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequiredOrMarket" }, "404": { "description": "Unknown symbol (SYMBOL_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "SYMBOL_NOT_FOUND", "message": "Unknown symbol '999999'. Use a listed Korean 6-character code (e.g. 005930); GET /symbols looks codes up by name.", "docs": "https://openapi.chickstockfi.com/docs" } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/major-holders/{symbol}": { "get": { "operationId": "listMajorHolders", "tags": [ "Major shareholders" ], "summary": "5% major shareholder reports (Korea)", "x-summary-en": "5% major shareholder reports (Korea)", "x-markets": [ "KR" ], "x-market-scoped": true, "x-paginated": "cursor", "description": "5% major shareholding reports — reporter, ownership ratio, change, and reason for the report (DART, newest report date first).\n\n> Markets: KR · Pagination: cursor + limit\n\n> 🔒 **Paid tiers only** (Launch, Business, Scale, Enterprise; PoC included) — Free keys and accounts whose paid-tier term has ended receive 403 `PLAN_REQUIRED`; accounts whose PoC has ended receive 403 `POC_ENDED`.\n\n> 🌐 **Data coverage** — the account receives data only for the markets it has contracted. A market outside the contract (symbol or `market`) returns 403 `MARKET_NOT_ENTITLED` before any limit is counted; Japan (`JP`) and China (`CN`) return 400 `MARKET_NOT_AVAILABLE` (coming soon). For POST /query, authentication applies first; if every line is outside the contract, it returns 403 with zero per-minute, ordinary daily and AI calls. A storage failure or timeout during key, plan, company or market resolution returns HTTP 503 `UNAVAILABLE` with zero per-minute, ordinary daily and AI calls, without falling back to Free. Otherwise it returns HTTP 200 with per-line errors and counts as one ordinary call.", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "symbol", "in": "path", "required": true, "description": "Korean 6-digit symbol code (e.g. 005930; a leading A is ignored)", "schema": { "type": "string", "pattern": "^A?\\d[0-9A-Z]{5}$", "example": "005930" } }, { "name": "market", "in": "query", "required": false, "description": "Optional — the market is determined by the symbol code (Korean 6-digit code or US ticker). If given, verifies that the symbol belongs to that market (otherwise 400 BAD_SYMBOL). Only KR symbols are supported (others return 400 UNSUPPORTED_MARKET).", "schema": { "type": "string", "enum": [ "KR", "US" ] } }, { "name": "cursor", "in": "query", "required": false, "description": "Next page — pass the previous response's next_cursor as-is, with the same filters. Omit for the first page", "schema": { "type": "string", "maxLength": 2100, "example": "c1.eyJrIjpbIjIwMjYtMTAtMjAiLCIyMDI2MTAyMDAwMDEyMyJdLCJmIjoiQWJDZEVmR2hJaksifQ" } }, { "name": "limit", "in": "query", "required": false, "description": "Items per page (1–200, default 50)", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Quota-Period": { "$ref": "#/components/headers/X-Quota-Period" }, "X-Quota-Reset": { "$ref": "#/components/headers/X-Quota-Reset" }, "X-Markets": { "$ref": "#/components/headers/X-Markets" }, "X-Plan": { "$ref": "#/components/headers/X-Plan" }, "X-Plan-Tier": { "$ref": "#/components/headers/X-Plan-Tier" }, "X-Plan-Expires": { "$ref": "#/components/headers/X-Plan-Expires" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MajorHolder" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page — null if there are no more pages" }, "has_more": { "type": "boolean", "description": "Whether there is a next page" }, "meta": { "type": "object", "properties": { "count": { "type": "integer" }, "total": { "type": "integer" }, "symbol": { "type": "string" }, "market": { "type": "string", "enum": [ "KR", "US" ] }, "issuer_symbol": { "type": "string", "example": "005930", "description": "Symbol whose company-level data (filings, ownership, insiders, treasury stock, financials, consensus …) was read — for Korean preferred shares (e.g. 005935, 005385, 000815) the issuer's common share (005930, 005380, 000810); otherwise the requested symbol" }, "share_class": { "type": [ "string", "null" ], "enum": [ "common", "preferred", null ], "description": "Korean share class — common or preferred. Null for US symbols (not determined)" }, "issuer_note": { "type": "string", "description": "Preferred shares only — note that company-level data is the issuer's" }, "as_of": { "type": "string", "format": "date-time" } } } }, "required": [ "data", "next_cursor", "has_more", "meta" ] }, "example": { "data": [ { "report_date": "2026-10-15", "reporter": "국민연금공단", "report_type": "일반", "reason": "보유비율 변동", "holding_qty": 435123456, "holding_qty_change": -5123456, "holding_rate": 7.35, "holding_rate_change": -0.09, "url": "https://dart.fss.or.kr/dsaf001/main.do?rcpNo=20261015000321", "rcept_no": "20261015000321", "market": "KR" } ], "next_cursor": "c1.eyJrIjpbIjIwMjYtMTAtMjAiLCIyMDI2MTAyMDAwMDEyMyJdLCJmIjoiQWJDZEVmR2hJaksifQ", "has_more": true, "meta": { "count": 1, "total": 18, "symbol": "005930", "market": "KR", "as_of": "2026-10-21T06:30:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequiredOrMarket" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/insider-trades/{symbol}": { "get": { "operationId": "listInsiderTrades", "tags": [ "Insider trading" ], "summary": "Insider ownership reports (Korea)", "x-summary-en": "Insider ownership reports (Korea)", "x-markets": [ "KR" ], "x-market-scoped": true, "x-paginated": "cursor", "description": "Reports on specified securities held by officers and major shareholders — shares held, change, ownership ratio (newest report date first). `is_new_report=true` means the change is an initial report, not a trade.\n\n> Markets: KR · Pagination: cursor + limit\n\n> 🔒 **Paid tiers only** (Launch, Business, Scale, Enterprise; PoC included) — Free keys and accounts whose paid-tier term has ended receive 403 `PLAN_REQUIRED`; accounts whose PoC has ended receive 403 `POC_ENDED`.\n\n> 🌐 **Data coverage** — the account receives data only for the markets it has contracted. A market outside the contract (symbol or `market`) returns 403 `MARKET_NOT_ENTITLED` before any limit is counted; Japan (`JP`) and China (`CN`) return 400 `MARKET_NOT_AVAILABLE` (coming soon). For POST /query, authentication applies first; if every line is outside the contract, it returns 403 with zero per-minute, ordinary daily and AI calls. A storage failure or timeout during key, plan, company or market resolution returns HTTP 503 `UNAVAILABLE` with zero per-minute, ordinary daily and AI calls, without falling back to Free. Otherwise it returns HTTP 200 with per-line errors and counts as one ordinary call.", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "symbol", "in": "path", "required": true, "description": "Korean 6-digit symbol code (e.g. 005930; a leading A is ignored)", "schema": { "type": "string", "pattern": "^A?\\d[0-9A-Z]{5}$", "example": "005930" } }, { "name": "market", "in": "query", "required": false, "description": "Optional — the market is determined by the symbol code (Korean 6-digit code or US ticker). If given, verifies that the symbol belongs to that market (otherwise 400 BAD_SYMBOL). Only KR symbols are supported (others return 400 UNSUPPORTED_MARKET).", "schema": { "type": "string", "enum": [ "KR", "US" ] } }, { "name": "cursor", "in": "query", "required": false, "description": "Next page — pass the previous response's next_cursor as-is, with the same filters. Omit for the first page", "schema": { "type": "string", "maxLength": 2100, "example": "c1.eyJrIjpbIjIwMjYtMTAtMjAiLCIyMDI2MTAyMDAwMDEyMyJdLCJmIjoiQWJDZEVmR2hJaksifQ" } }, { "name": "limit", "in": "query", "required": false, "description": "Items per page (1–200, default 50)", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Quota-Period": { "$ref": "#/components/headers/X-Quota-Period" }, "X-Quota-Reset": { "$ref": "#/components/headers/X-Quota-Reset" }, "X-Markets": { "$ref": "#/components/headers/X-Markets" }, "X-Plan": { "$ref": "#/components/headers/X-Plan" }, "X-Plan-Tier": { "$ref": "#/components/headers/X-Plan-Tier" }, "X-Plan-Expires": { "$ref": "#/components/headers/X-Plan-Expires" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InsiderTrade" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page — null if there are no more pages" }, "has_more": { "type": "boolean", "description": "Whether there is a next page" }, "meta": { "type": "object", "properties": { "count": { "type": "integer" }, "total": { "type": "integer" }, "symbol": { "type": "string" }, "market": { "type": "string", "enum": [ "KR", "US" ] }, "issuer_symbol": { "type": "string", "example": "005930", "description": "Symbol whose company-level data (filings, ownership, insiders, treasury stock, financials, consensus …) was read — for Korean preferred shares (e.g. 005935, 005385, 000815) the issuer's common share (005930, 005380, 000810); otherwise the requested symbol" }, "share_class": { "type": [ "string", "null" ], "enum": [ "common", "preferred", null ], "description": "Korean share class — common or preferred. Null for US symbols (not determined)" }, "issuer_note": { "type": "string", "description": "Preferred shares only — note that company-level data is the issuer's" }, "as_of": { "type": "string", "format": "date-time" } } } }, "required": [ "data", "next_cursor", "has_more", "meta" ] }, "example": { "data": [ { "report_date": "2026-10-20", "reporter": "홍길동", "is_registered_officer": "등기임원", "position": "사내이사", "is_major_shareholder": "-", "owned_qty": 12000, "owned_qty_change": 2000, "url": "https://dart.fss.or.kr/dsaf001/main.do?rcpNo=20261020000123", "rcept_no": "20261020000123", "owned_rate": 0, "owned_rate_change": 0, "is_new_report": false, "market": "KR" } ], "next_cursor": "c1.eyJrIjpbIjIwMjYtMTAtMjAiLCIyMDI2MTAyMDAwMDEyMyJdLCJmIjoiQWJDZEVmR2hJaksifQ", "has_more": true, "meta": { "count": 1, "total": 240, "symbol": "005930", "market": "KR", "as_of": "2026-10-21T06:30:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequiredOrMarket" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/treasury/{symbol}": { "get": { "operationId": "getTreasuryStock", "tags": [ "Treasury stock" ], "summary": "Treasury stock acquisitions, disposals and cancellations (Korea)", "x-summary-en": "Treasury stock acquisitions, disposals and cancellations (Korea)", "x-markets": [ "KR" ], "x-market-scoped": true, "x-paginated": "cursor", "description": "Treasury stock acquisition, disposal, and retirement quantities (DART, in source table order). **By default only total rows (`row_kind=total`) are returned** — the source table mixes total, subtotal, and individual rows, so summing them as-is counts the same quantity multiple times. For the breakdown, use `detail=1` (all rows, distinguished by `row_kind`).\n\n> Markets: KR · Pagination: cursor + limit\n\n> 🔒 **Paid tiers only** (Launch, Business, Scale, Enterprise; PoC included) — Free keys and accounts whose paid-tier term has ended receive 403 `PLAN_REQUIRED`; accounts whose PoC has ended receive 403 `POC_ENDED`.\n\n> 🌐 **Data coverage** — the account receives data only for the markets it has contracted. A market outside the contract (symbol or `market`) returns 403 `MARKET_NOT_ENTITLED` before any limit is counted; Japan (`JP`) and China (`CN`) return 400 `MARKET_NOT_AVAILABLE` (coming soon). For POST /query, authentication applies first; if every line is outside the contract, it returns 403 with zero per-minute, ordinary daily and AI calls. A storage failure or timeout during key, plan, company or market resolution returns HTTP 503 `UNAVAILABLE` with zero per-minute, ordinary daily and AI calls, without falling back to Free. Otherwise it returns HTTP 200 with per-line errors and counts as one ordinary call.", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "symbol", "in": "path", "required": true, "description": "Korean 6-digit symbol code (e.g. 005930; a leading A is ignored)", "schema": { "type": "string", "pattern": "^A?\\d[0-9A-Z]{5}$", "example": "005930" } }, { "name": "market", "in": "query", "required": false, "description": "Optional — the market is determined by the symbol code (Korean 6-digit code or US ticker). If given, verifies that the symbol belongs to that market (otherwise 400 BAD_SYMBOL). Only KR symbols are supported (others return 400 UNSUPPORTED_MARKET).", "schema": { "type": "string", "enum": [ "KR", "US" ] } }, { "name": "year", "in": "query", "required": false, "description": "Fiscal year YYYY (if omitted, the previous year; if that is not yet filed, automatically the year before)", "schema": { "type": "string", "pattern": "^\\d{4}$", "example": "2025" } }, { "name": "report", "in": "query", "required": false, "description": "11011 annual report; 11012 half-year report; 11013 Q1 report; 11014 Q3 report", "schema": { "type": "string", "enum": [ "11011", "11012", "11013", "11014" ] } }, { "name": "detail", "in": "query", "required": false, "description": "If 1, all total, subtotal, and individual rows", "schema": { "type": "string", "enum": [ "0", "1" ], "default": "0" } }, { "name": "cursor", "in": "query", "required": false, "description": "Next page — pass the previous response's next_cursor as-is, with the same filters. Omit for the first page", "schema": { "type": "string", "maxLength": 2100, "example": "c1.eyJrIjpbIjIwMjYtMTAtMjAiLCIyMDI2MTAyMDAwMDEyMyJdLCJmIjoiQWJDZEVmR2hJaksifQ" } }, { "name": "limit", "in": "query", "required": false, "description": "Items per page (1–200, default 50)", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Quota-Period": { "$ref": "#/components/headers/X-Quota-Period" }, "X-Quota-Reset": { "$ref": "#/components/headers/X-Quota-Reset" }, "X-Markets": { "$ref": "#/components/headers/X-Markets" }, "X-Plan": { "$ref": "#/components/headers/X-Plan" }, "X-Plan-Tier": { "$ref": "#/components/headers/X-Plan-Tier" }, "X-Plan-Expires": { "$ref": "#/components/headers/X-Plan-Expires" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TreasuryItem" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page — null if there are no more pages" }, "has_more": { "type": "boolean", "description": "Whether there is a next page" }, "meta": { "type": "object", "properties": { "count": { "type": "integer" }, "symbol": { "type": "string" }, "market": { "type": "string", "enum": [ "KR", "US" ] }, "issuer_symbol": { "type": "string", "example": "005930", "description": "Symbol whose company-level data (filings, ownership, insiders, treasury stock, financials, consensus …) was read — for Korean preferred shares (e.g. 005935, 005385, 000815) the issuer's common share (005930, 005380, 000810); otherwise the requested symbol" }, "share_class": { "type": [ "string", "null" ], "enum": [ "common", "preferred", null ], "description": "Korean share class — common or preferred. Null for US symbols (not determined)" }, "issuer_note": { "type": "string", "description": "Preferred shares only — note that company-level data is the issuer's" }, "year": { "type": "string" }, "report": { "type": "string" }, "detail": { "type": "boolean" }, "as_of": { "type": "string", "format": "date-time" } } } }, "required": [ "data", "next_cursor", "has_more", "meta" ] }, "example": { "data": [ { "acquisition_method": "총계", "stock_kind": "보통주", "begin_qty": 105432448, "acquired_qty": 0, "disposed_qty": 0, "cancelled_qty": 0, "end_qty": 105432448, "row_kind": "total", "settle_date": "2025-12-31", "rcept_no": "20260311001234", "note": null, "market": "KR" } ], "next_cursor": null, "has_more": false, "meta": { "count": 1, "symbol": "005930", "market": "KR", "year": "2025", "report": "11011", "detail": false, "as_of": "2026-10-21T06:30:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequiredOrMarket" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/employees/{symbol}": { "get": { "operationId": "listEmployees", "tags": [ "Employees" ], "summary": "Employees and pay (Korea)", "x-summary-en": "Employees and pay (Korea)", "x-markets": [ "KR" ], "x-market-scoped": true, "x-paginated": "cursor", "description": "Number of employees (permanent, contract), average years of service, total annual salary, and average salary per employee (DART, in source table order). `row_kind=detail|total` separates component rows from aggregates/subtotals. Do not sum aggregates together with components.\n\n> Markets: KR · Pagination: cursor + limit\n\n> 🔒 **Paid tiers only** (Launch, Business, Scale, Enterprise; PoC included) — Free keys and accounts whose paid-tier term has ended receive 403 `PLAN_REQUIRED`; accounts whose PoC has ended receive 403 `POC_ENDED`.\n\n> 🌐 **Data coverage** — the account receives data only for the markets it has contracted. A market outside the contract (symbol or `market`) returns 403 `MARKET_NOT_ENTITLED` before any limit is counted; Japan (`JP`) and China (`CN`) return 400 `MARKET_NOT_AVAILABLE` (coming soon). For POST /query, authentication applies first; if every line is outside the contract, it returns 403 with zero per-minute, ordinary daily and AI calls. A storage failure or timeout during key, plan, company or market resolution returns HTTP 503 `UNAVAILABLE` with zero per-minute, ordinary daily and AI calls, without falling back to Free. Otherwise it returns HTTP 200 with per-line errors and counts as one ordinary call.", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "symbol", "in": "path", "required": true, "description": "Korean 6-digit symbol code (e.g. 005930; a leading A is ignored)", "schema": { "type": "string", "pattern": "^A?\\d[0-9A-Z]{5}$", "example": "005930" } }, { "name": "market", "in": "query", "required": false, "description": "Optional — the market is determined by the symbol code (Korean 6-digit code or US ticker). If given, verifies that the symbol belongs to that market (otherwise 400 BAD_SYMBOL). Only KR symbols are supported (others return 400 UNSUPPORTED_MARKET).", "schema": { "type": "string", "enum": [ "KR", "US" ] } }, { "name": "year", "in": "query", "required": false, "description": "Fiscal year YYYY (if omitted, the previous year; if that is not yet filed, automatically the year before)", "schema": { "type": "string", "pattern": "^\\d{4}$", "example": "2025" } }, { "name": "report", "in": "query", "required": false, "description": "11011 annual report; 11012 half-year report; 11013 Q1 report; 11014 Q3 report", "schema": { "type": "string", "enum": [ "11011", "11012", "11013", "11014" ] } }, { "name": "cursor", "in": "query", "required": false, "description": "Next page — pass the previous response's next_cursor as-is, with the same filters. Omit for the first page", "schema": { "type": "string", "maxLength": 2100, "example": "c1.eyJrIjpbIjIwMjYtMTAtMjAiLCIyMDI2MTAyMDAwMDEyMyJdLCJmIjoiQWJDZEVmR2hJaksifQ" } }, { "name": "limit", "in": "query", "required": false, "description": "Items per page (1–200, default 50)", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Quota-Period": { "$ref": "#/components/headers/X-Quota-Period" }, "X-Quota-Reset": { "$ref": "#/components/headers/X-Quota-Reset" }, "X-Markets": { "$ref": "#/components/headers/X-Markets" }, "X-Plan": { "$ref": "#/components/headers/X-Plan" }, "X-Plan-Tier": { "$ref": "#/components/headers/X-Plan-Tier" }, "X-Plan-Expires": { "$ref": "#/components/headers/X-Plan-Expires" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EmployeeItem" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page — null if there are no more pages" }, "has_more": { "type": "boolean", "description": "Whether there is a next page" }, "meta": { "type": "object", "properties": { "count": { "type": "integer" }, "symbol": { "type": "string" }, "market": { "type": "string", "enum": [ "KR", "US" ] }, "issuer_symbol": { "type": "string", "example": "005930", "description": "Symbol whose company-level data (filings, ownership, insiders, treasury stock, financials, consensus …) was read — for Korean preferred shares (e.g. 005935, 005385, 000815) the issuer's common share (005930, 005380, 000810); otherwise the requested symbol" }, "share_class": { "type": [ "string", "null" ], "enum": [ "common", "preferred", null ], "description": "Korean share class — common or preferred. Null for US symbols (not determined)" }, "issuer_note": { "type": "string", "description": "Preferred shares only — note that company-level data is the issuer's" }, "year": { "type": "string" }, "report": { "type": "string" }, "as_of": { "type": "string", "format": "date-time" } } } }, "required": [ "data", "next_cursor", "has_more", "meta" ] }, "example": { "data": [ { "division": "DX", "row_kind": "detail", "gender": "남", "regular_count": 41023, "contract_count": 512, "total_count": 41535, "avg_service_years": 14.1, "annual_salary_total": 5123456000000, "avg_salary_per_person": 130000000, "market": "KR" } ], "next_cursor": null, "has_more": false, "meta": { "count": 1, "symbol": "005930", "market": "KR", "year": "2025", "report": "11011", "as_of": "2026-10-21T06:30:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequiredOrMarket" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/credit-ratings/{symbol}": { "get": { "operationId": "listCreditRatings", "tags": [ "Credit ratings" ], "summary": "Credit ratings and bond filings (Korea)", "x-summary-en": "Credit ratings and bond filings (Korea)", "x-markets": [ "KR" ], "x-market-scoped": true, "x-paginated": "cursor", "description": "DART filings related to credit ratings and bonds — rating, outlook, rating agency, source link (last 2 years, newest date first). `grade` normalizes a flat 0 suffix (AA0 becomes AA); `grade_raw` preserves the source notation. Agency aliases are deduplicated to canonical names. `instrument_type` identifies only an instrument explicitly stated beside the rating; absent or ambiguous evidence returns null. Grades and instrument types are extracted only for the existing five most recent body lookups; other rows return null. Missing URLs are null.\n\n> Markets: KR · Pagination: cursor + limit\n\n> 🔒 **Paid tiers only** (Launch, Business, Scale, Enterprise; PoC included) — Free keys and accounts whose paid-tier term has ended receive 403 `PLAN_REQUIRED`; accounts whose PoC has ended receive 403 `POC_ENDED`.\n\n> 🌐 **Data coverage** — the account receives data only for the markets it has contracted. A market outside the contract (symbol or `market`) returns 403 `MARKET_NOT_ENTITLED` before any limit is counted; Japan (`JP`) and China (`CN`) return 400 `MARKET_NOT_AVAILABLE` (coming soon). For POST /query, authentication applies first; if every line is outside the contract, it returns 403 with zero per-minute, ordinary daily and AI calls. A storage failure or timeout during key, plan, company or market resolution returns HTTP 503 `UNAVAILABLE` with zero per-minute, ordinary daily and AI calls, without falling back to Free. Otherwise it returns HTTP 200 with per-line errors and counts as one ordinary call.", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "symbol", "in": "path", "required": true, "description": "Korean 6-digit symbol code (e.g. 005930; a leading A is ignored)", "schema": { "type": "string", "pattern": "^A?\\d[0-9A-Z]{5}$", "example": "005930" } }, { "name": "market", "in": "query", "required": false, "description": "Optional — the market is determined by the symbol code (Korean 6-digit code or US ticker). If given, verifies that the symbol belongs to that market (otherwise 400 BAD_SYMBOL). Only KR symbols are supported (others return 400 UNSUPPORTED_MARKET).", "schema": { "type": "string", "enum": [ "KR", "US" ] } }, { "name": "cursor", "in": "query", "required": false, "description": "Next page — pass the previous response's next_cursor as-is, with the same filters. Omit for the first page", "schema": { "type": "string", "maxLength": 2100, "example": "c1.eyJrIjpbIjIwMjYtMTAtMjAiLCIyMDI2MTAyMDAwMDEyMyJdLCJmIjoiQWJDZEVmR2hJaksifQ" } }, { "name": "limit", "in": "query", "required": false, "description": "Items per page (1–200, default 50)", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Quota-Period": { "$ref": "#/components/headers/X-Quota-Period" }, "X-Quota-Reset": { "$ref": "#/components/headers/X-Quota-Reset" }, "X-Markets": { "$ref": "#/components/headers/X-Markets" }, "X-Plan": { "$ref": "#/components/headers/X-Plan" }, "X-Plan-Tier": { "$ref": "#/components/headers/X-Plan-Tier" }, "X-Plan-Expires": { "$ref": "#/components/headers/X-Plan-Expires" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CreditRatingItem" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page — null if there are no more pages" }, "has_more": { "type": "boolean", "description": "Whether there is a next page" }, "meta": { "type": "object", "properties": { "count": { "type": "integer" }, "total": { "type": "integer" }, "symbol": { "type": "string" }, "market": { "type": "string", "enum": [ "KR", "US" ] }, "issuer_symbol": { "type": "string", "example": "005930", "description": "Symbol whose company-level data (filings, ownership, insiders, treasury stock, financials, consensus …) was read — for Korean preferred shares (e.g. 005935, 005385, 000815) the issuer's common share (005930, 005380, 000810); otherwise the requested symbol" }, "share_class": { "type": [ "string", "null" ], "enum": [ "common", "preferred", null ], "description": "Korean share class — common or preferred. Null for US symbols (not determined)" }, "issuer_note": { "type": "string", "description": "Preferred shares only — note that company-level data is the issuer's" }, "as_of": { "type": "string", "format": "date-time" } } } }, "required": [ "data", "next_cursor", "has_more", "meta" ] }, "example": { "data": [ { "date": "2026-09-15", "title": "증권발행실적보고서", "filer": "현대자동차", "grade": "AA", "grade_raw": "AA0", "instrument_type": null, "outlook": "안정적", "agencies": [ "한국신용평가", "NICE신용평가" ], "url": "https://dart.fss.or.kr/dsaf001/main.do?rcpNo=20260915000555", "market": "KR" } ], "next_cursor": null, "has_more": false, "meta": { "count": 1, "total": 7, "symbol": "005380", "market": "KR", "as_of": "2026-10-21T06:30:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequiredOrMarket" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/clinical-trials": { "get": { "operationId": "listClinicalTrials", "tags": [ "Clinical trials" ], "summary": "Clinical trials (global registry)", "x-summary-en": "Clinical trials (global registry)", "x-markets": [ "KR" ], "x-market-scoped": true, "x-paginated": "cursor", "description": "Global clinical trials (ClinicalTrials.gov) — phase, status, condition, sponsor, last update (newest last update and NCT number first, up to 100). Either `symbol` (Korean biotech mapping) or `sponsor` (sponsor name in English, worldwide) is required.\n\n> Markets: KR · Pagination: cursor + limit\n\n> 🔒 **Paid tiers only** (Launch, Business, Scale, Enterprise; PoC included) — Free keys and accounts whose paid-tier term has ended receive 403 `PLAN_REQUIRED`; accounts whose PoC has ended receive 403 `POC_ENDED`.\n\n> 🌐 **Data coverage** — the account receives data only for the markets it has contracted. A market outside the contract (symbol or `market`) returns 403 `MARKET_NOT_ENTITLED` before any limit is counted; Japan (`JP`) and China (`CN`) return 400 `MARKET_NOT_AVAILABLE` (coming soon). For POST /query, authentication applies first; if every line is outside the contract, it returns 403 with zero per-minute, ordinary daily and AI calls. A storage failure or timeout during key, plan, company or market resolution returns HTTP 503 `UNAVAILABLE` with zero per-minute, ordinary daily and AI calls, without falling back to Free. Otherwise it returns HTTP 200 with per-line errors and counts as one ordinary call.", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "symbol", "in": "query", "required": false, "description": "Korean 6-digit code", "schema": { "type": "string" } }, { "name": "sponsor", "in": "query", "required": false, "description": "Sponsor name (English)", "schema": { "type": "string", "minLength": 2, "maxLength": 80, "example": "Alteogen" } }, { "name": "status", "in": "query", "required": false, "description": "Status (comma-separated, e.g. RECRUITING,COMPLETED)", "schema": { "type": "string", "maxLength": 120 } }, { "name": "cursor", "in": "query", "required": false, "description": "Next page — pass the previous response's next_cursor as-is, with the same filters. Omit for the first page", "schema": { "type": "string", "maxLength": 2100, "example": "c1.eyJrIjpbIjIwMjYtMTAtMjAiLCIyMDI2MTAyMDAwMDEyMyJdLCJmIjoiQWJDZEVmR2hJaksifQ" } }, { "name": "limit", "in": "query", "required": false, "description": "Items per page (1–200, default 50)", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Quota-Period": { "$ref": "#/components/headers/X-Quota-Period" }, "X-Quota-Reset": { "$ref": "#/components/headers/X-Quota-Reset" }, "X-Markets": { "$ref": "#/components/headers/X-Markets" }, "X-Plan": { "$ref": "#/components/headers/X-Plan" }, "X-Plan-Tier": { "$ref": "#/components/headers/X-Plan-Tier" }, "X-Plan-Expires": { "$ref": "#/components/headers/X-Plan-Expires" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ClinicalTrial" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page — null if there are no more pages" }, "has_more": { "type": "boolean", "description": "Whether there is a next page" }, "meta": { "type": "object", "properties": { "count": { "type": "integer" }, "sponsors": { "type": "array", "items": { "type": "string" } }, "note": { "type": "string" }, "as_of": { "type": "string", "format": "date-time" } } } }, "required": [ "data", "next_cursor", "has_more", "meta" ] }, "example": { "data": [ { "nct_id": "NCT01234567", "title": "A Study of ALT-B4 in Healthy Volunteers", "phase": "PHASE1", "status": "COMPLETED", "conditions": [ "Healthy" ], "sponsor": "Alteogen", "start_date": "2024-03", "completion_date": "2025-01", "last_update": "2026-02-10", "url": "https://clinicaltrials.gov/study/NCT01234567" } ], "next_cursor": null, "has_more": false, "meta": { "count": 1, "sponsors": [ "Alteogen" ], "as_of": "2026-10-21T06:30:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequiredOrMarket" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/earnings": { "get": { "operationId": "listEarnings", "tags": [ "Earnings calendar" ], "summary": "Earnings release calendar (US)", "x-summary-en": "Earnings release calendar (US)", "x-markets": [ "US" ], "x-market-scoped": true, "x-paginated": "cursor", "description": "Earnings release schedule for US-listed companies — ticker, report date, and time (bmo/amc), sorted by report date then ticker. The report date is `report_date` (added 2026-10-21); the old name `reportDate` keeps carrying the same value (deprecated). Default range = today through 30 days.\n\n⚠️ Since 2026-10-21, external estimates (`epsEst`, `revenueEst`) are not included. For revenue and operating income consensus, use `/companies/{symbol}/consensus`. `market=KR` is not supported yet (400 UNSUPPORTED_MARKET).\n\n> Markets: US · Pagination: cursor + limit\n\n> 🔒 **Paid tiers only** (Launch, Business, Scale, Enterprise; PoC included) — Free keys and accounts whose paid-tier term has ended receive 403 `PLAN_REQUIRED`; accounts whose PoC has ended receive 403 `POC_ENDED`.\n\n> 🌐 **Data coverage** — the account receives data only for the markets it has contracted. A market outside the contract (symbol or `market`) returns 403 `MARKET_NOT_ENTITLED` before any limit is counted; Japan (`JP`) and China (`CN`) return 400 `MARKET_NOT_AVAILABLE` (coming soon). For POST /query, authentication applies first; if every line is outside the contract, it returns 403 with zero per-minute, ordinary daily and AI calls. A storage failure or timeout during key, plan, company or market resolution returns HTTP 503 `UNAVAILABLE` with zero per-minute, ordinary daily and AI calls, without falling back to Free. Otherwise it returns HTTP 200 with per-line errors and counts as one ordinary call.", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "market", "in": "query", "required": false, "description": "Market — only US is supported (US if omitted; other values return 400 UNSUPPORTED_MARKET)", "schema": { "type": "string", "enum": [ "KR", "US" ], "default": "US" } }, { "name": "from", "in": "query", "required": false, "description": "Start date (default today)", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "End date (default +30 days)", "schema": { "type": "string", "format": "date" } }, { "name": "symbol", "in": "query", "required": false, "description": "Ticker", "schema": { "type": "string", "example": "AAPL" } }, { "name": "cursor", "in": "query", "required": false, "description": "Next page — pass the previous response's next_cursor as-is, with the same filters. Omit for the first page", "schema": { "type": "string", "maxLength": 2100, "example": "c1.eyJrIjpbIjIwMjYtMTAtMjAiLCIyMDI2MTAyMDAwMDEyMyJdLCJmIjoiQWJDZEVmR2hJaksifQ" } }, { "name": "limit", "in": "query", "required": false, "description": "Items per page (1–200, default 50)", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Quota-Period": { "$ref": "#/components/headers/X-Quota-Period" }, "X-Quota-Reset": { "$ref": "#/components/headers/X-Quota-Reset" }, "X-Markets": { "$ref": "#/components/headers/X-Markets" }, "X-Plan": { "$ref": "#/components/headers/X-Plan" }, "X-Plan-Tier": { "$ref": "#/components/headers/X-Plan-Tier" }, "X-Plan-Expires": { "$ref": "#/components/headers/X-Plan-Expires" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EarningsItem" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page — null if there are no more pages" }, "has_more": { "type": "boolean", "description": "Whether there is a next page" }, "meta": { "type": "object", "properties": { "count": { "type": "integer" }, "market": { "type": "string", "enum": [ "KR", "US" ] }, "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "as_of": { "type": "string", "format": "date-time" } } } }, "required": [ "data", "next_cursor", "has_more", "meta" ] }, "example": { "data": [ { "ticker": "NKE", "report_date": "2026-12-18", "reportDate": "2026-12-18", "time": "amc", "market": "US" } ], "next_cursor": "c1.eyJrIjpbIjIwMjYtMTAtMjAiLCIyMDI2MTAyMDAwMDEyMyJdLCJmIjoiQWJDZEVmR2hJaksifQ", "has_more": true, "meta": { "count": 1, "market": "US", "from": "2026-10-21", "to": "2026-12-31", "as_of": "2026-10-21T06:30:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequiredOrMarket" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/us-filings": { "get": { "operationId": "listUsFilings", "tags": [ "Filing list" ], "summary": "US SEC filings feed (all companies)", "x-summary-en": "US SEC filings feed (all companies)", "x-markets": [ "US" ], "x-market-scoped": true, "x-paginated": "cursor", "description": "SEC filings of every US-listed company (8-K, 6-K, 10-Q, 10-K, 20-F, 40-F, amendments included) in one list — newest first by filing date → SEC acceptance time → id (older filings without a recorded acceptance time sort last within their date).\n\n- **Real time**: pass `since` (SEC acceptance time, ISO 8601) to receive only what arrived after your previous call. `since` and `until` return only filings that have an acceptance time.\n- **Times and latency**: `accepted_at` (SEC acceptance) · `detected_at` (detection) · `analysis.published_at` (analysis published) · `analysis.latency_seconds` (acceptance → publication).\n- **Event types**: `items[].code` is the SEC 8-K item code (e.g. 2.02 results of operations, 5.02 officer changes, 1.01 material agreements). Filter with `items=2.02,5.02`.\n- **Analysis state**: `analysis.status` — published · pending · withheld · unreadable source (images, PDF) · not analyzed. It is a point-in-time state and can change (pending → published, and so on). `analysis=published` returns published ones only.\n- **Body**: up to the one-line headline. Report bodies are a PRO API feature.\n\n> Markets: US · Pagination: cursor + limit\n\n> 🔒 **Paid tiers only** (Launch, Business, Scale, Enterprise; PoC included) — Free keys and accounts whose paid-tier term has ended receive 403 `PLAN_REQUIRED`; accounts whose PoC has ended receive 403 `POC_ENDED`.\n\n> 🌐 **Data coverage** — the account receives data only for the markets it has contracted. A market outside the contract (symbol or `market`) returns 403 `MARKET_NOT_ENTITLED` before any limit is counted; Japan (`JP`) and China (`CN`) return 400 `MARKET_NOT_AVAILABLE` (coming soon). For POST /query, authentication applies first; if every line is outside the contract, it returns 403 with zero per-minute, ordinary daily and AI calls. A storage failure or timeout during key, plan, company or market resolution returns HTTP 503 `UNAVAILABLE` with zero per-minute, ordinary daily and AI calls, without falling back to Free. Otherwise it returns HTTP 200 with per-line errors and counts as one ordinary call.", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "market", "in": "query", "required": false, "description": "Market — only US is supported (US if omitted; other values return 400 UNSUPPORTED_MARKET)", "schema": { "type": "string", "enum": [ "KR", "US" ], "default": "US" } }, { "name": "since", "in": "query", "required": false, "description": "Lower bound of the SEC acceptance time (inclusive, ISO 8601 with offset)", "schema": { "type": "string", "format": "date-time", "example": "2026-10-27T10:00:00Z" } }, { "name": "until", "in": "query", "required": false, "description": "Upper bound of the SEC acceptance time (exclusive)", "schema": { "type": "string", "format": "date-time" } }, { "name": "from", "in": "query", "required": false, "description": "Filing date (US) from", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "Filing date (US) to", "schema": { "type": "string", "format": "date" } }, { "name": "form", "in": "query", "required": false, "description": "Forms (comma-separated, amendments /A included) — 8-K, 6-K, 10-Q, 10-K, 20-F, 40-F", "schema": { "type": "string", "example": "8-K,10-Q" } }, { "name": "items", "in": "query", "required": false, "description": "8-K item codes (comma-separated, max 20) — a filing matches if any code overlaps. Without from or since, the last 90 days", "schema": { "type": "string", "example": "2.02,5.02" } }, { "name": "symbol", "in": "query", "required": false, "description": "Tickers (comma-separated, max 50)", "schema": { "type": "string", "example": "AAPL,MSFT" } }, { "name": "analysis", "in": "query", "required": false, "description": "published = only filings whose analysis is published", "schema": { "type": "string", "enum": [ "any", "published" ], "default": "any" } }, { "name": "cursor", "in": "query", "required": false, "description": "Next page — pass the previous response's next_cursor as-is, with the same filters. Omit for the first page", "schema": { "type": "string", "maxLength": 2100, "example": "c1.eyJrIjpbIjIwMjYtMTAtMjAiLCIyMDI2MTAyMDAwMDEyMyJdLCJmIjoiQWJDZEVmR2hJaksifQ" } }, { "name": "limit", "in": "query", "required": false, "description": "Items per page (1–200, default 50)", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Quota-Period": { "$ref": "#/components/headers/X-Quota-Period" }, "X-Quota-Reset": { "$ref": "#/components/headers/X-Quota-Reset" }, "X-Markets": { "$ref": "#/components/headers/X-Markets" }, "X-Plan": { "$ref": "#/components/headers/X-Plan" }, "X-Plan-Tier": { "$ref": "#/components/headers/X-Plan-Tier" }, "X-Plan-Expires": { "$ref": "#/components/headers/X-Plan-Expires" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/UsFilingEvent" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page — null if there are no more pages" }, "has_more": { "type": "boolean", "description": "Whether there is a next page" }, "meta": { "type": "object", "properties": { "count": { "type": "integer" }, "market": { "type": "string", "enum": [ "KR", "US" ] }, "source": { "type": "string", "enum": [ "SEC" ] }, "as_of": { "type": "string", "format": "date-time" }, "note": { "type": "string" } } } }, "required": [ "data", "next_cursor", "has_more", "meta" ] }, "example": { "data": [ { "id": "CMS:0001104659-26-118972", "market": "US", "symbol": "CMS", "cik": "0000811156", "accession": "0001104659-26-118972", "company": { "name": "CMS 에너지", "name_en": "CMS Energy Corp" }, "form": "8-K", "amended": false, "items": [ { "code": "2.02", "label": "실적 발표", "label_en": "Results of Operations and Financial Condition" }, { "code": "9.01", "label": "재무제표·첨부서류", "label_en": "Financial Statements and Exhibits" } ], "category": "실적 발표", "title": "CMS Energy Corp 8-K", "filed_date": "2026-10-27", "report_date": "2026-10-27", "accepted_at": "2026-10-27T10:39:00.000Z", "detected_at": "2026-10-27T10:40:12.000Z", "source_url": "https://www.sec.gov/Archives/edgar/data/811156/000110465926118972/tm2628313d1_8k.htm", "analysis": { "status": "published", "headline": "회사는 2026년 3분기 조정 주당순이익이 …라고 밝혔습니다.", "headline_en": null, "published_at": "2026-10-27T10:43:05.000Z", "latency_seconds": 245, "page_url": "https://www.chickstockfi.com/disclosures/CMS%3A0001104659-26-118972" } } ], "next_cursor": "c1.eyJrIjpbIjIwMjYtMTAtMjAiLCIyMDI2MTAyMDAwMDEyMyJdLCJmIjoiQWJDZEVmR2hJaksifQ", "has_more": true, "meta": { "count": 1, "market": "US", "source": "SEC", "as_of": "2026-10-21T06:30:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequiredOrMarket" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/us-earnings": { "get": { "operationId": "listUsEarnings", "tags": [ "US earnings figures" ], "summary": "US earnings release figures", "x-summary-en": "US earnings release figures", "x-markets": [ "US" ], "x-market-scoped": true, "x-paginated": "cursor", "description": "Figures verified from US-listed companies' 8-K earnings releases (Item 2.02 press releases) — newest first by filing date, then id.\n\n- **Figures**: revenue, operating income, net income, GAAP diluted EPS, adjusted EPS, adjusted EBITDA, cash flow; banks (net interest income, provision for credit losses, net interest margin) and REITs (FFO/AFFO per share). Values are in base units (USD, USD per share, percent) with the prior-year value from the same release.\n- **Provenance**: every figure has `source` — `table_cell` (the SEC HTML table cell, row label and column header), `quote` (an exact sentence of the release and the number as written in it) or `income_statement` (the three-month column of the income statement). A model locates figures; code checks each against the release, and only verified values are returned.\n- **Change**: `yoy_pct` is computed from the two values of the same release (only when the prior value is positive). Profit measures whose sign changed carry `turnaround` (흑자전환 turned profitable · 적자전환 turned to a loss · 적자지속 loss in both periods) instead of a percentage.\n- **Flash**: `flash` is a one- or two-line Korean summary built by code from these figures (not written by AI). Figures whose two readings disagree (`cross_check: differs`) are left out.\n- **Pre-release consensus**: not computed in this list (`surprise: null`); it is in `GET /us-earnings/{id}` and the `us_earnings.figures` webhook.\n- **Outlook vs consensus**: `guidance_comparison` — this release's outlook against the pre-release consensus and the previous statement. Detail and webhooks only (null in the list).\n- **Price reaction**: `reaction` — last regular-session close before the announcement → first regular-session close after it (%). In the list, the detail and webhooks (usually `pending` at webhook time).\n- **Real time**: figures usually exist within a minute of the SEC acceptance. Use the `us_earnings.figures` webhook to receive new releases as they happen.\n\n> Markets: US · Pagination: cursor + limit\n\n> 🔒 **Paid tiers only** (Launch, Business, Scale, Enterprise; PoC included) — Free keys and accounts whose paid-tier term has ended receive 403 `PLAN_REQUIRED`; accounts whose PoC has ended receive 403 `POC_ENDED`.\n\n> 🌐 **Data coverage** — the account receives data only for the markets it has contracted. A market outside the contract (symbol or `market`) returns 403 `MARKET_NOT_ENTITLED` before any limit is counted; Japan (`JP`) and China (`CN`) return 400 `MARKET_NOT_AVAILABLE` (coming soon). For POST /query, authentication applies first; if every line is outside the contract, it returns 403 with zero per-minute, ordinary daily and AI calls. A storage failure or timeout during key, plan, company or market resolution returns HTTP 503 `UNAVAILABLE` with zero per-minute, ordinary daily and AI calls, without falling back to Free. Otherwise it returns HTTP 200 with per-line errors and counts as one ordinary call.", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "market", "in": "query", "required": false, "description": "Market — only US is supported (US if omitted; other values return 400 UNSUPPORTED_MARKET)", "schema": { "type": "string", "enum": [ "KR", "US" ], "default": "US" } }, { "name": "symbol", "in": "query", "required": false, "description": "Tickers (comma-separated, max 50)", "schema": { "type": "string", "example": "WSO,AAPL" } }, { "name": "from", "in": "query", "required": false, "description": "Filing date (US) from", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "Filing date (US) to", "schema": { "type": "string", "format": "date" } }, { "name": "cursor", "in": "query", "required": false, "description": "Next page — pass the previous response's next_cursor as-is, with the same filters. Omit for the first page", "schema": { "type": "string", "maxLength": 2100, "example": "c1.eyJrIjpbIjIwMjYtMTAtMjAiLCIyMDI2MTAyMDAwMDEyMyJdLCJmIjoiQWJDZEVmR2hJaksifQ" } }, { "name": "limit", "in": "query", "required": false, "description": "Items per page (1–200, default 50)", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Quota-Period": { "$ref": "#/components/headers/X-Quota-Period" }, "X-Quota-Reset": { "$ref": "#/components/headers/X-Quota-Reset" }, "X-Markets": { "$ref": "#/components/headers/X-Markets" }, "X-Plan": { "$ref": "#/components/headers/X-Plan" }, "X-Plan-Tier": { "$ref": "#/components/headers/X-Plan-Tier" }, "X-Plan-Expires": { "$ref": "#/components/headers/X-Plan-Expires" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/UsEarningsRelease" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page — null if there are no more pages" }, "has_more": { "type": "boolean", "description": "Whether there is a next page" }, "meta": { "type": "object", "properties": { "count": { "type": "integer" }, "market": { "type": "string", "enum": [ "KR", "US" ] }, "source": { "type": "string", "enum": [ "SEC" ] }, "as_of": { "type": "string", "format": "date-time" }, "note": { "type": "string" } } } }, "required": [ "data", "next_cursor", "has_more", "meta" ] }, "example": { "data": [ { "id": "WSO:0000105016-26-000123", "market": "US", "symbol": "WSO", "cik": "0000105016", "accession": "0000105016-26-000123", "company": { "name": "와츠코", "name_en": "Watsco Inc" }, "form": "8-K", "items": [ { "code": "2.02", "label": "실적 발표", "label_en": "Results of Operations and Financial Condition" } ], "filed_date": "2026-10-28", "report_date": "2026-10-28", "period": { "label_ko": "2026년 3분기", "end": "2026-09-30", "header": "Quarter Ended September 30, 2026", "duration": "quarter" }, "currency": "USD", "figures": [ { "metric": "revenue", "name": "매출", "name_en": "Revenue", "unit": "USD", "basis": "gaap", "value": 2220400000, "prior_value": 2067000000, "yoy_pct": 7.4, "change_pp": null, "turnaround": null, "source": { "kind": "table_cell", "ref": "T2.R3.C1", "row_label": "Revenues", "column": "Quarter Ended September 30, 2026" }, "prior_source": { "kind": "table_cell", "ref": "T2.R3.C2", "row_label": "Revenues", "column": "Quarter Ended September 30, 2025" }, "cross_check": "match" }, { "metric": "eps_diluted", "name": "GAAP 희석 EPS", "name_en": "Diluted EPS (GAAP)", "unit": "USD_PER_SHARE", "basis": "gaap", "value": 3.77, "prior_value": 3.98, "yoy_pct": -5.3, "change_pp": null, "turnaround": null, "source": { "kind": "table_cell", "ref": "T2.R21.C1", "row_label": "Diluted earnings per share", "column": "Quarter Ended September 30, 2026" }, "prior_source": { "kind": "table_cell", "ref": "T2.R21.C2", "row_label": "Diluted earnings per share", "column": "Quarter Ended September 30, 2025" }, "cross_check": null } ], "margins": { "gross_margin_pct": null, "operating_margin_pct": { "value": 10.1, "prior_value": 11.3 } }, "kpis": [ { "name": "동일 점포 매출 증가율", "unit": "PERCENT", "value": 4, "text": "4%", "quote": "Revenues increased 7% to a record $2.22 billion (4% increase on a same-store basis)." } ], "outlook": [], "surprise": null, "flash": { "headline": "와츠코(WSO) 2026년 3분기 매출 22.2억 달러(+7.4%) · GAAP 희석 EPS 3.77달러(-5.3%)", "text": "와츠코(WSO) 2026년 3분기 매출 22.2억 달러, 1년 전보다 7.4% 늘어 · 영업이익 2.25억 달러(-4.1%) · GAAP 희석 EPS 3.77달러(-5.3%).", "lines": [ "와츠코(WSO) 2026년 3분기 매출 22.2억 달러, 1년 전보다 7.4% 늘어 · 영업이익 2.25억 달러(-4.1%) · GAAP 희석 EPS 3.77달러(-5.3%)" ] }, "revision": { "fingerprint": "3b1f0c9e8d2a7765" }, "timestamps": { "accepted_at": "2026-10-28T10:31:05.000Z", "release_fetched_at": "2026-10-28T10:31:21.000Z", "extracted_at": "2026-10-28T10:31:39.000Z", "latency_seconds": 16 }, "extraction": { "version": "us-earnings-extract-v1", "method": "both" }, "source_url": "https://www.sec.gov/Archives/edgar/data/105016/000010501626000123/wso-20261028.htm", "exhibit_url": "https://www.sec.gov/Archives/edgar/data/105016/000010501626000123/ex99.htm", "page_url": "https://www.chickstockfi.com/analysis/earnings/WSO%3A0000105016-26-000123" } ], "next_cursor": "c1.eyJrIjpbIjIwMjYtMTAtMjAiLCIyMDI2MTAyMDAwMDEyMyJdLCJmIjoiQWJDZEVmR2hJaksifQ", "has_more": true, "meta": { "count": 1, "market": "US", "source": "SEC", "as_of": "2026-10-21T06:30:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequiredOrMarket" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/us-earnings/{id}": { "get": { "operationId": "getUsEarnings", "tags": [ "US earnings figures" ], "summary": "US earnings release figures (one filing, with consensus comparison)", "x-summary-en": "US earnings release figures (one filing, with consensus comparison)", "x-markets": [ "US" ], "x-market-scoped": true, "description": "Verified figures, provenance and outlook quotes of one earnings release, with the **comparison to the pre-release consensus** (`surprise`).\n\n- `surprise` is computed only for the same fiscal period and the same basis (GAAP diluted EPS and adjusted EPS are never mixed) — (actual ÷ consensus − 1) × 100. The consensus is the last value observed before the release (`consensus.observed_on`), named `시장 컨센서스` (market consensus) or `시장 예상치` (market estimate). When nothing is comparable the array is empty.\n- `flash.lines[1]` exists only with a comparison (e.g. `발표 직전 시장 예상치(10월 27일 기준) 대비 EPS -7.8%`).\n- The id is the id of `GET /us-earnings` and `GET /us-filings` (ticker:SEC accession number). 404 until figures exist.\n\n> Markets: US\n\n> 🔒 **Paid tiers only** (Launch, Business, Scale, Enterprise; PoC included) — Free keys and accounts whose paid-tier term has ended receive 403 `PLAN_REQUIRED`; accounts whose PoC has ended receive 403 `POC_ENDED`.\n\n> 🌐 **Data coverage** — the account receives data only for the markets it has contracted. A market outside the contract (symbol or `market`) returns 403 `MARKET_NOT_ENTITLED` before any limit is counted; Japan (`JP`) and China (`CN`) return 400 `MARKET_NOT_AVAILABLE` (coming soon). For POST /query, authentication applies first; if every line is outside the contract, it returns 403 with zero per-minute, ordinary daily and AI calls. A storage failure or timeout during key, plan, company or market resolution returns HTTP 503 `UNAVAILABLE` with zero per-minute, ordinary daily and AI calls, without falling back to Free. Otherwise it returns HTTP 200 with per-line errors and counts as one ordinary call.", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker:SEC accession number (e.g. WSO:0000105016-26-000123)", "schema": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9.-]{0,11}:\\d{10}-\\d{2}-\\d{6}$", "example": "WSO:0000105016-26-000123" } }, { "name": "market", "in": "query", "required": false, "description": "Market — only US is supported (US if omitted; other values return 400 UNSUPPORTED_MARKET)", "schema": { "type": "string", "enum": [ "KR", "US" ], "default": "US" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Quota-Period": { "$ref": "#/components/headers/X-Quota-Period" }, "X-Quota-Reset": { "$ref": "#/components/headers/X-Quota-Reset" }, "X-Markets": { "$ref": "#/components/headers/X-Markets" }, "X-Plan": { "$ref": "#/components/headers/X-Plan" }, "X-Plan-Tier": { "$ref": "#/components/headers/X-Plan-Tier" }, "X-Plan-Expires": { "$ref": "#/components/headers/X-Plan-Expires" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/UsEarningsRelease" }, "meta": { "type": "object", "properties": { "market": { "type": "string", "enum": [ "KR", "US" ] }, "source": { "type": "string", "enum": [ "SEC" ] }, "as_of": { "type": "string", "format": "date-time" }, "note": { "type": "string" } } } }, "required": [ "data", "meta" ] }, "example": { "data": { "id": "WSO:0000105016-26-000123", "market": "US", "symbol": "WSO", "cik": "0000105016", "accession": "0000105016-26-000123", "company": { "name": "와츠코", "name_en": "Watsco Inc" }, "form": "8-K", "items": [ { "code": "2.02", "label": "실적 발표", "label_en": "Results of Operations and Financial Condition" } ], "filed_date": "2026-10-28", "report_date": "2026-10-28", "period": { "label_ko": "2026년 3분기", "end": "2026-09-30", "header": "Quarter Ended September 30, 2026", "duration": "quarter" }, "currency": "USD", "figures": [ { "metric": "revenue", "name": "매출", "name_en": "Revenue", "unit": "USD", "basis": "gaap", "value": 2220400000, "prior_value": 2067000000, "yoy_pct": 7.4, "change_pp": null, "turnaround": null, "source": { "kind": "table_cell", "ref": "T2.R3.C1", "row_label": "Revenues", "column": "Quarter Ended September 30, 2026" }, "prior_source": { "kind": "table_cell", "ref": "T2.R3.C2", "row_label": "Revenues", "column": "Quarter Ended September 30, 2025" }, "cross_check": "match" }, { "metric": "eps_diluted", "name": "GAAP 희석 EPS", "name_en": "Diluted EPS (GAAP)", "unit": "USD_PER_SHARE", "basis": "gaap", "value": 3.77, "prior_value": 3.98, "yoy_pct": -5.3, "change_pp": null, "turnaround": null, "source": { "kind": "table_cell", "ref": "T2.R21.C1", "row_label": "Diluted earnings per share", "column": "Quarter Ended September 30, 2026" }, "prior_source": { "kind": "table_cell", "ref": "T2.R21.C2", "row_label": "Diluted earnings per share", "column": "Quarter Ended September 30, 2025" }, "cross_check": null } ], "margins": { "gross_margin_pct": null, "operating_margin_pct": { "value": 10.1, "prior_value": 11.3 } }, "kpis": [ { "name": "동일 점포 매출 증가율", "unit": "PERCENT", "value": 4, "text": "4%", "quote": "Revenues increased 7% to a record $2.22 billion (4% increase on a same-store basis)." } ], "outlook": [], "surprise": [ { "metric": "eps", "name": "EPS(주당순이익)", "basis": "GAAP 희석 · 3개월", "eps_basis": "gaap_diluted", "currency": "USD", "unit": "USD_PER_SHARE", "actual": { "value": 3.77, "text": "$3.77", "source": { "kind": "sec", "doc": "8-K 실적 발표", "id": "0000105016-26-000123", "filed_on": "2026-10-28", "url": "https://www.sec.gov/Archives/edgar/data/105016/000010501626000123/ex99.htm" } }, "consensus": { "value": 4.09, "text": "$4.09", "label": "시장 예상치", "observed_on": "2026-10-27", "as_of_basis": "captured", "estimate_date": null }, "surprise_pct": -7.8 } ], "flash": { "headline": "와츠코(WSO) 2026년 3분기 매출 22.2억 달러(+7.4%) · GAAP 희석 EPS 3.77달러(-5.3%)", "text": "와츠코(WSO) 2026년 3분기 매출 22.2억 달러, 1년 전보다 7.4% 늘어 · 영업이익 2.25억 달러(-4.1%) · GAAP 희석 EPS 3.77달러(-5.3%). 발표 직전 시장 예상치(10월 27일 기준) 대비 EPS -7.8%.", "lines": [ "와츠코(WSO) 2026년 3분기 매출 22.2억 달러, 1년 전보다 7.4% 늘어 · 영업이익 2.25억 달러(-4.1%) · GAAP 희석 EPS 3.77달러(-5.3%)", "발표 직전 시장 예상치(10월 27일 기준) 대비 EPS -7.8%" ] }, "revision": { "fingerprint": "3b1f0c9e8d2a7765" }, "timestamps": { "accepted_at": "2026-10-28T10:31:05.000Z", "release_fetched_at": "2026-10-28T10:31:21.000Z", "extracted_at": "2026-10-28T10:31:39.000Z", "latency_seconds": 16 }, "extraction": { "version": "us-earnings-extract-v1", "method": "both" }, "source_url": "https://www.sec.gov/Archives/edgar/data/105016/000010501626000123/wso-20261028.htm", "exhibit_url": "https://www.sec.gov/Archives/edgar/data/105016/000010501626000123/ex99.htm", "page_url": "https://www.chickstockfi.com/analysis/earnings/WSO%3A0000105016-26-000123" }, "meta": { "market": "US", "source": "SEC", "as_of": "2026-10-21T06:30:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequiredOrMarket" }, "404": { "description": "No figures yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "No verified earnings figures for this filing yet, or it is not an earnings release.", "docs": "https://openapi.chickstockfi.com/docs" } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/webhooks": { "get": { "operationId": "listWebhooks", "tags": [ "Webhooks" ], "summary": "List webhooks", "x-summary-en": "List webhooks", "x-markets": [ "US" ], "x-market-scoped": true, "description": "Your registered webhooks (at most 5 per account, in registration order). Signing secrets are never shown again.\n\n> Markets: US\n\n> 🔒 **Paid tiers only** (Launch, Business, Scale, Enterprise; PoC included) — Free keys and accounts whose paid-tier term has ended receive 403 `PLAN_REQUIRED`; accounts whose PoC has ended receive 403 `POC_ENDED`.\n\n> 🌐 **Data coverage** — the account receives data only for the markets it has contracted. A market outside the contract (symbol or `market`) returns 403 `MARKET_NOT_ENTITLED` before any limit is counted; Japan (`JP`) and China (`CN`) return 400 `MARKET_NOT_AVAILABLE` (coming soon). For POST /query, authentication applies first; if every line is outside the contract, it returns 403 with zero per-minute, ordinary daily and AI calls. A storage failure or timeout during key, plan, company or market resolution returns HTTP 503 `UNAVAILABLE` with zero per-minute, ordinary daily and AI calls, without falling back to Free. Otherwise it returns HTTP 200 with per-line errors and counts as one ordinary call.", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Quota-Period": { "$ref": "#/components/headers/X-Quota-Period" }, "X-Quota-Reset": { "$ref": "#/components/headers/X-Quota-Reset" }, "X-Markets": { "$ref": "#/components/headers/X-Markets" }, "X-Plan": { "$ref": "#/components/headers/X-Plan" }, "X-Plan-Tier": { "$ref": "#/components/headers/X-Plan-Tier" }, "X-Plan-Expires": { "$ref": "#/components/headers/X-Plan-Expires" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } }, "meta": { "type": "object", "properties": { "count": { "type": "integer" }, "limit": { "type": "integer" }, "events": { "type": "array", "items": { "type": "string" } }, "as_of": { "type": "string", "format": "date-time" } } } }, "required": [ "data", "meta" ] }, "example": { "data": [ { "id": "3f6b2a0e-7c1d-4a55-9a43-2b8e5f0c9d11", "url": "https://hooks.example.com/sec", "events": [ "us_filing.detected", "us_filing.analysis_published" ], "filters": { "symbols": [ "AAPL", "MSFT" ], "forms": null, "items": [ "2.02" ] }, "status": "active", "disabled_reason": null, "consecutive_failures": 0, "created_at": "2026-10-27T11:00:00.000Z", "updated_at": "2026-10-27T11:00:00.000Z" } ], "meta": { "count": 1, "limit": 5, "events": [ "us_filing.detected", "us_filing.analysis_published", "us_filing.analysis_revoked", "us_earnings.figures" ], "as_of": "2026-10-21T06:30:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequiredOrMarket" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "post": { "operationId": "createWebhook", "tags": [ "Webhooks" ], "summary": "Register a webhook", "x-summary-en": "Register a webhook", "x-markets": [ "US" ], "x-market-scoped": true, "description": "Register an HTTPS endpoint for US filing and earnings events (at most 5 per account). The `secret` in the response is shown only this once.\n\n- **Events**: `us_filing.detected` (a filing was detected; analysis state at that moment) · `us_filing.analysis_published` (its analysis was published: headline, publication time, latency) · `us_filing.analysis_revoked` (a published analysis was withdrawn) · `us_earnings.figures` (earnings release figures). Filing events carry a `GET /us-filings` item as `data`; earnings events carry the `GET /us-earnings/{id}` object. Publication events cover filings dated within the last 7 days.\n- **Corrections and revisions**: when an analysis is corrected and published again, `us_filing.analysis_published` arrives once more for the new version (`data.publication.revision` 2, 3… · `replaces` = the version it replaced). When a published analysis is withdrawn, `us_filing.analysis_revoked` arrives once per version (`data.revocation` — withdrawal time, and `replacement` when a new version is already public). Revocations are sent for versions we announced by webhook (last 30 days). When a new reading changes earnings figures (only when figure or outlook values differ), `us_earnings.figures` arrives again (`data.revision.number` 2, 3… · `changed` = the measures that changed). Events are not ordered; reconcile with the revision numbers and `replaces`.\n- **Filters**: `filters.symbols` (tickers, up to 100) · `filters.forms` (8-K, 6-K, 10-Q, 10-K, 20-F, 40-F, amendments included) · `filters.items` (8-K item codes, up to 20; any overlap matches). Leave empty to receive everything.\n- **Signature**: Standard Webhooks scheme. Headers `webhook-id` · `webhook-timestamp` (Unix seconds) · `webhook-signature` (`v1,`). The signed content is `{webhook-id}.{webhook-timestamp}.{body}` and the key is the base64-decoded part after `whsec_`. Open-source libraries (standardwebhooks) verify it.\n- **Delivery**: a 2xx answer within 5 seconds counts as delivered (redirects are not followed). Failures are retried after 1 min, 5 min, 30 min, 2 h and 6 h, then dropped. After 100 consecutive failures the webhook is disabled; re-enable it with `PATCH` `status: active`. An event can arrive twice, so deduplicate on `webhook-id`. Order is not guaranteed.\n- **Endpoint**: public-internet HTTPS on port 443 only. Names that resolve to private or internal addresses are refused.\n\n> Markets: US\n\n> 🔒 **Paid tiers only** (Launch, Business, Scale, Enterprise; PoC included) — Free keys and accounts whose paid-tier term has ended receive 403 `PLAN_REQUIRED`; accounts whose PoC has ended receive 403 `POC_ENDED`.\n\n> 🌐 **Data coverage** — the account receives data only for the markets it has contracted. A market outside the contract (symbol or `market`) returns 403 `MARKET_NOT_ENTITLED` before any limit is counted; Japan (`JP`) and China (`CN`) return 400 `MARKET_NOT_AVAILABLE` (coming soon). For POST /query, authentication applies first; if every line is outside the contract, it returns 403 with zero per-minute, ordinary daily and AI calls. A storage failure or timeout during key, plan, company or market resolution returns HTTP 503 `UNAVAILABLE` with zero per-minute, ordinary daily and AI calls, without falling back to Free. Otherwise it returns HTTP 200 with per-line errors and counts as one ordinary call.", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRequest" }, "example": { "url": "https://hooks.example.com/sec", "events": [ "us_filing.analysis_published" ], "filters": { "symbols": [ "AAPL", "MSFT" ], "items": [ "2.02" ] } } } } }, "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Quota-Period": { "$ref": "#/components/headers/X-Quota-Period" }, "X-Quota-Reset": { "$ref": "#/components/headers/X-Quota-Reset" }, "X-Markets": { "$ref": "#/components/headers/X-Markets" }, "X-Plan": { "$ref": "#/components/headers/X-Plan" }, "X-Plan-Tier": { "$ref": "#/components/headers/X-Plan-Tier" }, "X-Plan-Expires": { "$ref": "#/components/headers/X-Plan-Expires" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "us_filing.detected", "us_filing.analysis_published", "us_filing.analysis_revoked", "us_earnings.figures" ] } }, "filters": { "$ref": "#/components/schemas/WebhookFilters" }, "status": { "type": "string", "enum": [ "active", "disabled" ] }, "disabled_reason": { "type": [ "string", "null" ], "enum": [ "consecutive_failures", "disabled_by_customer", null ], "description": "Why it is disabled — consecutive_failures · disabled_by_customer" }, "consecutive_failures": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "secret": { "type": "string", "description": "Signing secret (whsec_…) — only in the registration response" } } }, "meta": { "type": "object", "properties": { "note": { "type": "string" } } } }, "required": [ "data" ] }, "example": { "data": { "id": "3f6b2a0e-7c1d-4a55-9a43-2b8e5f0c9d11", "url": "https://hooks.example.com/sec", "events": [ "us_filing.detected", "us_filing.analysis_published" ], "filters": { "symbols": [ "AAPL", "MSFT" ], "forms": null, "items": [ "2.02" ] }, "status": "active", "disabled_reason": null, "consecutive_failures": 0, "created_at": "2026-10-27T11:00:00.000Z", "updated_at": "2026-10-27T11:00:00.000Z", "secret": "whsec_Q2hpY2tlbi1leGFtcGxlLXNlY3JldA==" }, "meta": { "note": "Store secret now: it is shown only once." } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequiredOrMarket" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/webhooks/{id}": { "patch": { "operationId": "updateWebhook", "tags": [ "Webhooks" ], "summary": "Update or re-enable a webhook", "x-summary-en": "Update or re-enable a webhook", "x-markets": [ "US" ], "x-market-scoped": true, "description": "Change the URL, events, filters or status. Only the fields you send change, and `filters` is replaced as a whole. Re-enabling a disabled webhook with `status: active` resets its failure streak.\n\n> Markets: US\n\n> 🔒 **Paid tiers only** (Launch, Business, Scale, Enterprise; PoC included) — Free keys and accounts whose paid-tier term has ended receive 403 `PLAN_REQUIRED`; accounts whose PoC has ended receive 403 `POC_ENDED`.\n\n> 🌐 **Data coverage** — the account receives data only for the markets it has contracted. A market outside the contract (symbol or `market`) returns 403 `MARKET_NOT_ENTITLED` before any limit is counted; Japan (`JP`) and China (`CN`) return 400 `MARKET_NOT_AVAILABLE` (coming soon). For POST /query, authentication applies first; if every line is outside the contract, it returns 403 with zero per-minute, ordinary daily and AI calls. A storage failure or timeout during key, plan, company or market resolution returns HTTP 503 `UNAVAILABLE` with zero per-minute, ordinary daily and AI calls, without falling back to Free. Otherwise it returns HTTP 200 with per-line errors and counts as one ordinary call.", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook id (UUID)", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRequest" }, "example": { "status": "active" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Quota-Period": { "$ref": "#/components/headers/X-Quota-Period" }, "X-Quota-Reset": { "$ref": "#/components/headers/X-Quota-Reset" }, "X-Markets": { "$ref": "#/components/headers/X-Markets" }, "X-Plan": { "$ref": "#/components/headers/X-Plan" }, "X-Plan-Tier": { "$ref": "#/components/headers/X-Plan-Tier" }, "X-Plan-Expires": { "$ref": "#/components/headers/X-Plan-Expires" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Webhook" } }, "required": [ "data" ] }, "example": { "data": { "id": "3f6b2a0e-7c1d-4a55-9a43-2b8e5f0c9d11", "url": "https://hooks.example.com/sec", "events": [ "us_filing.detected", "us_filing.analysis_published" ], "filters": { "symbols": [ "AAPL", "MSFT" ], "forms": null, "items": [ "2.02" ] }, "status": "active", "disabled_reason": null, "consecutive_failures": 0, "created_at": "2026-10-27T11:00:00.000Z", "updated_at": "2026-10-27T11:00:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequiredOrMarket" }, "404": { "description": "Webhook not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "Webhook not found.", "docs": "https://openapi.chickstockfi.com/docs" } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "delete": { "operationId": "deleteWebhook", "tags": [ "Webhooks" ], "summary": "Delete a webhook", "x-summary-en": "Delete a webhook", "x-markets": [ "US" ], "x-market-scoped": true, "description": "Delete a webhook. Events not yet delivered are deleted with it.\n\n> Markets: US\n\n> 🔒 **Paid tiers only** (Launch, Business, Scale, Enterprise; PoC included) — Free keys and accounts whose paid-tier term has ended receive 403 `PLAN_REQUIRED`; accounts whose PoC has ended receive 403 `POC_ENDED`.\n\n> 🌐 **Data coverage** — the account receives data only for the markets it has contracted. A market outside the contract (symbol or `market`) returns 403 `MARKET_NOT_ENTITLED` before any limit is counted; Japan (`JP`) and China (`CN`) return 400 `MARKET_NOT_AVAILABLE` (coming soon). For POST /query, authentication applies first; if every line is outside the contract, it returns 403 with zero per-minute, ordinary daily and AI calls. A storage failure or timeout during key, plan, company or market resolution returns HTTP 503 `UNAVAILABLE` with zero per-minute, ordinary daily and AI calls, without falling back to Free. Otherwise it returns HTTP 200 with per-line errors and counts as one ordinary call.", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook id (UUID)", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Quota-Period": { "$ref": "#/components/headers/X-Quota-Period" }, "X-Quota-Reset": { "$ref": "#/components/headers/X-Quota-Reset" }, "X-Markets": { "$ref": "#/components/headers/X-Markets" }, "X-Plan": { "$ref": "#/components/headers/X-Plan" }, "X-Plan-Tier": { "$ref": "#/components/headers/X-Plan-Tier" }, "X-Plan-Expires": { "$ref": "#/components/headers/X-Plan-Expires" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "deleted": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "id": "3f6b2a0e-7c1d-4a55-9a43-2b8e5f0c9d11", "deleted": true } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequiredOrMarket" }, "404": { "description": "Webhook not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "Webhook not found.", "docs": "https://openapi.chickstockfi.com/docs" } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/webhooks/{id}/test": { "post": { "operationId": "testWebhook", "tags": [ "Webhooks" ], "summary": "Send a test event", "x-summary-en": "Send a test event", "x-markets": [ "US" ], "x-market-scoped": true, "description": "Send one signed `webhook.test` event now (not stored, not retried) to check the endpoint and your signature verification. Returns the response code of your server and the time it took.\n\n> Markets: US\n\n> 🔒 **Paid tiers only** (Launch, Business, Scale, Enterprise; PoC included) — Free keys and accounts whose paid-tier term has ended receive 403 `PLAN_REQUIRED`; accounts whose PoC has ended receive 403 `POC_ENDED`.\n\n> 🌐 **Data coverage** — the account receives data only for the markets it has contracted. A market outside the contract (symbol or `market`) returns 403 `MARKET_NOT_ENTITLED` before any limit is counted; Japan (`JP`) and China (`CN`) return 400 `MARKET_NOT_AVAILABLE` (coming soon). For POST /query, authentication applies first; if every line is outside the contract, it returns 403 with zero per-minute, ordinary daily and AI calls. A storage failure or timeout during key, plan, company or market resolution returns HTTP 503 `UNAVAILABLE` with zero per-minute, ordinary daily and AI calls, without falling back to Free. Otherwise it returns HTTP 200 with per-line errors and counts as one ordinary call.", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook id (UUID)", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Quota-Period": { "$ref": "#/components/headers/X-Quota-Period" }, "X-Quota-Reset": { "$ref": "#/components/headers/X-Quota-Reset" }, "X-Markets": { "$ref": "#/components/headers/X-Markets" }, "X-Plan": { "$ref": "#/components/headers/X-Plan" }, "X-Plan-Tier": { "$ref": "#/components/headers/X-Plan-Tier" }, "X-Plan-Expires": { "$ref": "#/components/headers/X-Plan-Expires" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "delivered": { "type": "boolean" }, "status": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ] }, "duration_ms": { "type": "integer" }, "message_id": { "type": "string" } } } }, "required": [ "data" ] }, "example": { "data": { "delivered": true, "status": 200, "error": null, "duration_ms": 182, "message_id": "msg_test_8a0c…" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequiredOrMarket" }, "404": { "description": "Webhook not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "Webhook not found.", "docs": "https://openapi.chickstockfi.com/docs" } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/webhooks/{id}/deliveries": { "get": { "operationId": "listWebhookDeliveries", "tags": [ "Webhooks" ], "summary": "Webhook delivery log", "x-summary-en": "Webhook delivery log", "x-markets": [ "US" ], "x-market-scoped": true, "description": "Recent deliveries (newest first, 50 by default and up to 100, kept 30 days) — state (pending, delivered, dead), attempts, last response code and error.\n\n> Markets: US\n\n> 🔒 **Paid tiers only** (Launch, Business, Scale, Enterprise; PoC included) — Free keys and accounts whose paid-tier term has ended receive 403 `PLAN_REQUIRED`; accounts whose PoC has ended receive 403 `POC_ENDED`.\n\n> 🌐 **Data coverage** — the account receives data only for the markets it has contracted. A market outside the contract (symbol or `market`) returns 403 `MARKET_NOT_ENTITLED` before any limit is counted; Japan (`JP`) and China (`CN`) return 400 `MARKET_NOT_AVAILABLE` (coming soon). For POST /query, authentication applies first; if every line is outside the contract, it returns 403 with zero per-minute, ordinary daily and AI calls. A storage failure or timeout during key, plan, company or market resolution returns HTTP 503 `UNAVAILABLE` with zero per-minute, ordinary daily and AI calls, without falling back to Free. Otherwise it returns HTTP 200 with per-line errors and counts as one ordinary call.", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook id (UUID)", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "Count (default 50, max 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Quota-Period": { "$ref": "#/components/headers/X-Quota-Period" }, "X-Quota-Reset": { "$ref": "#/components/headers/X-Quota-Reset" }, "X-Markets": { "$ref": "#/components/headers/X-Markets" }, "X-Plan": { "$ref": "#/components/headers/X-Plan" }, "X-Plan-Tier": { "$ref": "#/components/headers/X-Plan-Tier" }, "X-Plan-Expires": { "$ref": "#/components/headers/X-Plan-Expires" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "meta": { "type": "object", "properties": { "count": { "type": "integer" }, "as_of": { "type": "string", "format": "date-time" } } } }, "required": [ "data", "meta" ] }, "example": { "data": [ { "id": "msg_6f1c…", "event_id": "evt_1042", "type": "us_filing.analysis_published", "filing_id": "CMS:0001104659-26-118972", "status": "delivered", "attempts": 1, "last_status": 200, "last_error": null, "created_at": "2026-10-27T10:43:06.000Z", "delivered_at": "2026-10-27T10:43:06.000Z", "next_attempt_at": null } ], "meta": { "count": 1, "as_of": "2026-10-21T06:30:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequiredOrMarket" }, "404": { "description": "Webhook not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "Webhook not found.", "docs": "https://openapi.chickstockfi.com/docs" } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/ir-calendar": { "get": { "operationId": "listIrCalendar", "tags": [ "IR" ], "summary": "Investor relations events (Korea)", "x-summary-en": "Investor relations events (Korea)", "x-markets": [ "KR" ], "x-market-scoped": true, "x-paginated": "cursor", "description": "Investor relations (IR) events of Korean listed companies — company, date, time, venue (date and time ascending). Events with presentation materials carry `material_id` (the old name `materialId` has the same value, deprecated). If the range is omitted, from today.\n\n> Markets: KR · Pagination: cursor + limit\n\n> 🔒 **Paid tiers only** (Launch, Business, Scale, Enterprise; PoC included) — Free keys and accounts whose paid-tier term has ended receive 403 `PLAN_REQUIRED`; accounts whose PoC has ended receive 403 `POC_ENDED`.\n\n> 🌐 **Data coverage** — the account receives data only for the markets it has contracted. A market outside the contract (symbol or `market`) returns 403 `MARKET_NOT_ENTITLED` before any limit is counted; Japan (`JP`) and China (`CN`) return 400 `MARKET_NOT_AVAILABLE` (coming soon). For POST /query, authentication applies first; if every line is outside the contract, it returns 403 with zero per-minute, ordinary daily and AI calls. A storage failure or timeout during key, plan, company or market resolution returns HTTP 503 `UNAVAILABLE` with zero per-minute, ordinary daily and AI calls, without falling back to Free. Otherwise it returns HTTP 200 with per-line errors and counts as one ordinary call.", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "market", "in": "query", "required": false, "description": "Market — only KR is supported (KR if omitted; other values return 400 UNSUPPORTED_MARKET)", "schema": { "type": "string", "enum": [ "KR", "US" ], "default": "KR" } }, { "name": "from", "in": "query", "required": false, "description": "Start date (default today)", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "End date", "schema": { "type": "string", "format": "date" } }, { "name": "symbol", "in": "query", "required": false, "description": "Korean 6-digit code", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Next page — pass the previous response's next_cursor as-is, with the same filters. Omit for the first page", "schema": { "type": "string", "maxLength": 2100, "example": "c1.eyJrIjpbIjIwMjYtMTAtMjAiLCIyMDI2MTAyMDAwMDEyMyJdLCJmIjoiQWJDZEVmR2hJaksifQ" } }, { "name": "limit", "in": "query", "required": false, "description": "Items per page (1–200, default 50)", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Quota-Period": { "$ref": "#/components/headers/X-Quota-Period" }, "X-Quota-Reset": { "$ref": "#/components/headers/X-Quota-Reset" }, "X-Markets": { "$ref": "#/components/headers/X-Markets" }, "X-Plan": { "$ref": "#/components/headers/X-Plan" }, "X-Plan-Tier": { "$ref": "#/components/headers/X-Plan-Tier" }, "X-Plan-Expires": { "$ref": "#/components/headers/X-Plan-Expires" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/IrCalendarItem" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page — null if there are no more pages" }, "has_more": { "type": "boolean", "description": "Whether there is a next page" }, "meta": { "type": "object", "properties": { "count": { "type": "integer" }, "market": { "type": "string", "enum": [ "KR", "US" ] }, "as_of": { "type": "string", "format": "date-time" } } } }, "required": [ "data", "next_cursor", "has_more", "meta" ] }, "example": { "data": [ { "id": "ir_20261028_005930", "symbol": "005930", "company": "삼성전자", "title": "2026년 3분기 실적 설명회", "place": "컨퍼런스콜", "date": "2026-10-30", "time": "10:00", "material_id": null, "materialId": null, "market": "KR" } ], "next_cursor": "c1.eyJrIjpbIjIwMjYtMTAtMjAiLCIyMDI2MTAyMDAwMDEyMyJdLCJmIjoiQWJDZEVmR2hJaksifQ", "has_more": true, "meta": { "count": 1, "market": "KR", "as_of": "2026-10-21T06:30:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequiredOrMarket" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/ir-materials": { "get": { "operationId": "listIrMaterials", "tags": [ "IR" ], "summary": "Investor relations materials (Korea)", "x-summary-en": "Investor relations materials (Korea)", "x-markets": [ "KR" ], "x-market-scoped": true, "x-paginated": "cursor", "description": "Publication feed of IR presentation materials from Korean listed companies (materials issued by the companies) — company, date, title, and file and viewer links (newest publication date first). Links are present only when Phoenix AI holds an archived copy; otherwise null.\n\n> Markets: KR · Pagination: cursor + limit\n\n> 🔒 **Paid tiers only** (Launch, Business, Scale, Enterprise; PoC included) — Free keys and accounts whose paid-tier term has ended receive 403 `PLAN_REQUIRED`; accounts whose PoC has ended receive 403 `POC_ENDED`.\n\n> 🌐 **Data coverage** — the account receives data only for the markets it has contracted. A market outside the contract (symbol or `market`) returns 403 `MARKET_NOT_ENTITLED` before any limit is counted; Japan (`JP`) and China (`CN`) return 400 `MARKET_NOT_AVAILABLE` (coming soon). For POST /query, authentication applies first; if every line is outside the contract, it returns 403 with zero per-minute, ordinary daily and AI calls. A storage failure or timeout during key, plan, company or market resolution returns HTTP 503 `UNAVAILABLE` with zero per-minute, ordinary daily and AI calls, without falling back to Free. Otherwise it returns HTTP 200 with per-line errors and counts as one ordinary call.", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "market", "in": "query", "required": false, "description": "Market — only KR is supported (KR if omitted; other values return 400 UNSUPPORTED_MARKET)", "schema": { "type": "string", "enum": [ "KR", "US" ], "default": "KR" } }, { "name": "symbol", "in": "query", "required": false, "description": "Korean 6-digit code", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Next page — pass the previous response's next_cursor as-is, with the same filters. Omit for the first page", "schema": { "type": "string", "maxLength": 2100, "example": "c1.eyJrIjpbIjIwMjYtMTAtMjAiLCIyMDI2MTAyMDAwMDEyMyJdLCJmIjoiQWJDZEVmR2hJaksifQ" } }, { "name": "limit", "in": "query", "required": false, "description": "Items per page (1–200, default 50)", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Quota-Period": { "$ref": "#/components/headers/X-Quota-Period" }, "X-Quota-Reset": { "$ref": "#/components/headers/X-Quota-Reset" }, "X-Markets": { "$ref": "#/components/headers/X-Markets" }, "X-Plan": { "$ref": "#/components/headers/X-Plan" }, "X-Plan-Tier": { "$ref": "#/components/headers/X-Plan-Tier" }, "X-Plan-Expires": { "$ref": "#/components/headers/X-Plan-Expires" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/IrMaterialItem" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page — null if there are no more pages" }, "has_more": { "type": "boolean", "description": "Whether there is a next page" }, "meta": { "type": "object", "properties": { "count": { "type": "integer" }, "market": { "type": "string", "enum": [ "KR", "US" ] }, "as_of": { "type": "string", "format": "date-time" } } } }, "required": [ "data", "next_cursor", "has_more", "meta" ] }, "example": { "data": [ { "id": "irm_77120", "symbol": "005930", "company": "삼성전자", "title": "2026년 2분기 실적 발표", "date": "2026-07-31", "download_url": "https://www.chickstockfi.com/api/market/ir-doc/irm_77120", "view_url": "https://www.chickstockfi.com/api/market/ir-doc/irm_77120/view", "market": "KR" } ], "next_cursor": "c1.eyJrIjpbIjIwMjYtMTAtMjAiLCIyMDI2MTAyMDAwMDEyMyJdLCJmIjoiQWJDZEVmR2hJaksifQ", "has_more": true, "meta": { "count": 1, "market": "KR", "as_of": "2026-10-21T06:30:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequiredOrMarket" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/ipo-offerings": { "get": { "operationId": "listIpoOfferings", "tags": [ "IPO" ], "summary": "IPO subscriptions (Korea)", "x-summary-en": "IPO subscriptions (Korea)", "x-markets": [ "KR" ], "x-market-scoped": true, "x-paginated": "cursor", "description": "Korean IPO subscription schedule — book-building, subscription, payment date, indicative offering price range (KRW), final offer price, offering amount, expected listing date, underwriters (subscription start date ascending). Because these companies are not yet listed, `symbol` is mostly null. If the range is omitted, from 7 days ago.\n\n- **One offering = one row**: when an amended filing changes the schedule or the company is renamed (e.g. 케이비제34호스팩 → KB제34호스팩), it stays one row with the same `id`.\n- **Prices**: `price_low` / `price_high` = the indicative price range (always low ≤ high; if the source lists them reversed we correct it and note it in `quality_flags`), `offer_price` = the final offer price, `offer_amount` = the offering amount (KRW). SPACs are usually fixed at KRW 2,000. Values not yet read from the source are null (never estimated).\n- **Coverage**: `meta.coverage_from` = the earliest stored subscription start date.\n\n> Markets: KR · Pagination: cursor + limit\n\n> 🔒 **Paid tiers only** (Launch, Business, Scale, Enterprise; PoC included) — Free keys and accounts whose paid-tier term has ended receive 403 `PLAN_REQUIRED`; accounts whose PoC has ended receive 403 `POC_ENDED`.\n\n> 🌐 **Data coverage** — the account receives data only for the markets it has contracted. A market outside the contract (symbol or `market`) returns 403 `MARKET_NOT_ENTITLED` before any limit is counted; Japan (`JP`) and China (`CN`) return 400 `MARKET_NOT_AVAILABLE` (coming soon). For POST /query, authentication applies first; if every line is outside the contract, it returns 403 with zero per-minute, ordinary daily and AI calls. A storage failure or timeout during key, plan, company or market resolution returns HTTP 503 `UNAVAILABLE` with zero per-minute, ordinary daily and AI calls, without falling back to Free. Otherwise it returns HTTP 200 with per-line errors and counts as one ordinary call.", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "market", "in": "query", "required": false, "description": "Market — only KR is supported (KR if omitted; other values return 400 UNSUPPORTED_MARKET)", "schema": { "type": "string", "enum": [ "KR", "US" ], "default": "KR" } }, { "name": "from", "in": "query", "required": false, "description": "Start date (default 7 days ago)", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "End date", "schema": { "type": "string", "format": "date" } }, { "name": "symbol", "in": "query", "required": false, "description": "Korean 6-digit code (only after listing)", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Next page — pass the previous response's next_cursor as-is, with the same filters. Omit for the first page", "schema": { "type": "string", "maxLength": 2100, "example": "c1.eyJrIjpbIjIwMjYtMTAtMjAiLCIyMDI2MTAyMDAwMDEyMyJdLCJmIjoiQWJDZEVmR2hJaksifQ" } }, { "name": "limit", "in": "query", "required": false, "description": "Items per page (1–200, default 50)", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Quota-Period": { "$ref": "#/components/headers/X-Quota-Period" }, "X-Quota-Reset": { "$ref": "#/components/headers/X-Quota-Reset" }, "X-Markets": { "$ref": "#/components/headers/X-Markets" }, "X-Plan": { "$ref": "#/components/headers/X-Plan" }, "X-Plan-Tier": { "$ref": "#/components/headers/X-Plan-Tier" }, "X-Plan-Expires": { "$ref": "#/components/headers/X-Plan-Expires" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/IpoOffering" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page — null if there are no more pages" }, "has_more": { "type": "boolean", "description": "Whether there is a next page" }, "meta": { "type": "object", "properties": { "count": { "type": "integer" }, "market": { "type": "string", "enum": [ "KR", "US" ] }, "coverage_from": { "type": [ "string", "null" ], "format": "date", "description": "The earliest stored subscription start date" }, "as_of": { "type": "string", "format": "date-time" } } } }, "required": [ "data", "next_cursor", "has_more", "meta" ] }, "example": { "data": [ { "id": "8f2c41d07a9b3e65c120", "symbol": null, "symbol_reason": "not_yet_listed", "company": "에이비씨바이오", "exchange": "KOSDAQ", "is_spac": false, "filing_date": "2026-09-30", "demand_from": "2026-10-22", "demand_to": "2026-10-28", "subscribe_from": "2026-11-02", "subscribe_to": "2026-11-03", "payment_date": "2026-11-05", "price_low": 18000, "price_high": 21000, "offer_price": 21000, "offer_amount": 25200000000, "offer_shares": 1200000, "offer_price_vs_band": "within", "quality_flags": [], "expected_listing_date": "2026-11-12", "underwriters": "한국투자증권", "market": "KR" } ], "next_cursor": "c1.eyJrIjpbIjIwMjYtMTAtMjAiLCIyMDI2MTAyMDAwMDEyMyJdLCJmIjoiQWJDZEVmR2hJaksifQ", "has_more": true, "meta": { "count": 1, "market": "KR", "coverage_from": "2026-06-09", "as_of": "2026-10-21T06:30:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequiredOrMarket" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/ipo-listings": { "get": { "operationId": "listIpoListings", "tags": [ "IPO" ], "summary": "New listings (Korea)", "x-summary-en": "New listings (Korea)", "x-markets": [ "KR" ], "x-market-scoped": true, "x-paginated": "cursor", "description": "Korean new listing schedule — listing date, listing type, market, security type, industry, underwriters (listing date ascending). If the range is omitted, from 7 days ago. One listing = one row (the same `id` even if the company is renamed). `meta.coverage_from` = the earliest stored listing date.\n\n> Markets: KR · Pagination: cursor + limit\n\n> 🔒 **Paid tiers only** (Launch, Business, Scale, Enterprise; PoC included) — Free keys and accounts whose paid-tier term has ended receive 403 `PLAN_REQUIRED`; accounts whose PoC has ended receive 403 `POC_ENDED`.\n\n> 🌐 **Data coverage** — the account receives data only for the markets it has contracted. A market outside the contract (symbol or `market`) returns 403 `MARKET_NOT_ENTITLED` before any limit is counted; Japan (`JP`) and China (`CN`) return 400 `MARKET_NOT_AVAILABLE` (coming soon). For POST /query, authentication applies first; if every line is outside the contract, it returns 403 with zero per-minute, ordinary daily and AI calls. A storage failure or timeout during key, plan, company or market resolution returns HTTP 503 `UNAVAILABLE` with zero per-minute, ordinary daily and AI calls, without falling back to Free. Otherwise it returns HTTP 200 with per-line errors and counts as one ordinary call.", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "market", "in": "query", "required": false, "description": "Market — only KR is supported (KR if omitted; other values return 400 UNSUPPORTED_MARKET)", "schema": { "type": "string", "enum": [ "KR", "US" ], "default": "KR" } }, { "name": "from", "in": "query", "required": false, "description": "Start date (default 7 days ago)", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "End date", "schema": { "type": "string", "format": "date" } }, { "name": "symbol", "in": "query", "required": false, "description": "Korean 6-digit code", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Next page — pass the previous response's next_cursor as-is, with the same filters. Omit for the first page", "schema": { "type": "string", "maxLength": 2100, "example": "c1.eyJrIjpbIjIwMjYtMTAtMjAiLCIyMDI2MTAyMDAwMDEyMyJdLCJmIjoiQWJDZEVmR2hJaksifQ" } }, { "name": "limit", "in": "query", "required": false, "description": "Items per page (1–200, default 50)", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Quota-Period": { "$ref": "#/components/headers/X-Quota-Period" }, "X-Quota-Reset": { "$ref": "#/components/headers/X-Quota-Reset" }, "X-Markets": { "$ref": "#/components/headers/X-Markets" }, "X-Plan": { "$ref": "#/components/headers/X-Plan" }, "X-Plan-Tier": { "$ref": "#/components/headers/X-Plan-Tier" }, "X-Plan-Expires": { "$ref": "#/components/headers/X-Plan-Expires" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/IpoListing" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page — null if there are no more pages" }, "has_more": { "type": "boolean", "description": "Whether there is a next page" }, "meta": { "type": "object", "properties": { "count": { "type": "integer" }, "market": { "type": "string", "enum": [ "KR", "US" ] }, "coverage_from": { "type": [ "string", "null" ], "format": "date", "description": "The earliest stored listing date" }, "as_of": { "type": "string", "format": "date-time" } } } }, "required": [ "data", "next_cursor", "has_more", "meta" ] }, "example": { "data": [ { "id": "1c9e0b77f3a2d4e58b61", "symbol": "0089A0", "symbol_reason": null, "company": "에이비씨바이오", "exchange": "KOSDAQ", "is_spac": false, "listing_date": "2026-09-30", "list_type": "신규상장", "security_type": "주권", "industry": "의약품 제조업", "country": "대한민국", "underwriters": "한국투자증권", "market": "KR" } ], "next_cursor": "c1.eyJrIjpbIjIwMjYtMTAtMjAiLCIyMDI2MTAyMDAwMDEyMyJdLCJmIjoiQWJDZEVmR2hJaksifQ", "has_more": true, "meta": { "count": 1, "market": "KR", "coverage_from": "2026-05-20", "as_of": "2026-10-21T06:30:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequiredOrMarket" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/corporate-actions": { "get": { "operationId": "listCorporateActions", "tags": [ "Corporate actions" ], "summary": "Corporate actions feed (Korea)", "x-summary-en": "Corporate actions feed (Korea)", "x-markets": [ "KR" ], "x-market-scoped": true, "x-paginated": "cursor", "description": "Market-wide corporate actions (newest date first) — rights offerings, bonus issues, capital reductions, treasury stock retirements, mergers, spin-offs, par value changes, name changes, preliminary earnings, bond issuance, dividend decisions, etc. Filter by type with `type`; if the range is omitted, the last 14 days.\n\n> Markets: KR · Pagination: cursor + limit\n\n> 🔒 **Paid tiers only** (Launch, Business, Scale, Enterprise; PoC included) — Free keys and accounts whose paid-tier term has ended receive 403 `PLAN_REQUIRED`; accounts whose PoC has ended receive 403 `POC_ENDED`.\n\n> 🌐 **Data coverage** — the account receives data only for the markets it has contracted. A market outside the contract (symbol or `market`) returns 403 `MARKET_NOT_ENTITLED` before any limit is counted; Japan (`JP`) and China (`CN`) return 400 `MARKET_NOT_AVAILABLE` (coming soon). For POST /query, authentication applies first; if every line is outside the contract, it returns 403 with zero per-minute, ordinary daily and AI calls. A storage failure or timeout during key, plan, company or market resolution returns HTTP 503 `UNAVAILABLE` with zero per-minute, ordinary daily and AI calls, without falling back to Free. Otherwise it returns HTTP 200 with per-line errors and counts as one ordinary call.", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "market", "in": "query", "required": false, "description": "Market — only KR is supported (KR if omitted; other values return 400 UNSUPPORTED_MARKET)", "schema": { "type": "string", "enum": [ "KR", "US" ], "default": "KR" } }, { "name": "from", "in": "query", "required": false, "description": "Start date", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "End date", "schema": { "type": "string", "format": "date" } }, { "name": "type", "in": "query", "required": false, "description": "Type", "schema": { "type": "string", "enum": [ "유상증자", "무상증자", "감자", "자기주식소각", "자기주식취득", "자기주식처분", "합병", "분할", "액면변경", "사채발행", "영업양수도", "잠정실적", "상호변경", "배당결정", "주식교환·이전", "부실·구조조정", "IR|실적발표", "IR|경영현황" ], "maxLength": 20, "example": "유상증자" } }, { "name": "cursor", "in": "query", "required": false, "description": "Next page — pass the previous response's next_cursor as-is, with the same filters. Omit for the first page", "schema": { "type": "string", "maxLength": 2100, "example": "c1.eyJrIjpbIjIwMjYtMTAtMjAiLCIyMDI2MTAyMDAwMDEyMyJdLCJmIjoiQWJDZEVmR2hJaksifQ" } }, { "name": "limit", "in": "query", "required": false, "description": "Items per page (1–200, default 50)", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Quota-Period": { "$ref": "#/components/headers/X-Quota-Period" }, "X-Quota-Reset": { "$ref": "#/components/headers/X-Quota-Reset" }, "X-Markets": { "$ref": "#/components/headers/X-Markets" }, "X-Plan": { "$ref": "#/components/headers/X-Plan" }, "X-Plan-Tier": { "$ref": "#/components/headers/X-Plan-Tier" }, "X-Plan-Expires": { "$ref": "#/components/headers/X-Plan-Expires" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CorporateAction" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page — null if there are no more pages" }, "has_more": { "type": "boolean", "description": "Whether there is a next page" }, "meta": { "type": "object", "properties": { "count": { "type": "integer" }, "market": { "type": "string", "enum": [ "KR", "US" ] }, "as_of": { "type": "string", "format": "date-time" } } } }, "required": [ "data", "next_cursor", "has_more", "meta" ] }, "example": { "data": [ { "date": "2026-10-20", "symbol": "012345", "company": "에이비씨", "type": "유상증자", "title": "주요사항보고서(유상증자결정)", "filer": "에이비씨", "url": "https://dart.fss.or.kr/dsaf001/main.do?rcpNo=20261020000999", "market": "KR" } ], "next_cursor": "c1.eyJrIjpbIjIwMjYtMTAtMjAiLCIyMDI2MTAyMDAwMDEyMyJdLCJmIjoiQWJDZEVmR2hJaksifQ", "has_more": true, "meta": { "count": 1, "market": "KR", "as_of": "2026-10-21T06:30:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequiredOrMarket" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/corporate-actions/{symbol}": { "get": { "operationId": "listCorporateActionsBySymbol", "tags": [ "Corporate actions" ], "summary": "Corporate actions by symbol (Korea)", "x-summary-en": "Corporate actions by symbol (Korea)", "x-markets": [ "KR" ], "x-market-scoped": true, "x-paginated": "cursor", "description": "Corporate action history for a symbol (last 1 year, newest date first).\n\n> Markets: KR · Pagination: cursor + limit\n\n> 🔒 **Paid tiers only** (Launch, Business, Scale, Enterprise; PoC included) — Free keys and accounts whose paid-tier term has ended receive 403 `PLAN_REQUIRED`; accounts whose PoC has ended receive 403 `POC_ENDED`.\n\n> 🌐 **Data coverage** — the account receives data only for the markets it has contracted. A market outside the contract (symbol or `market`) returns 403 `MARKET_NOT_ENTITLED` before any limit is counted; Japan (`JP`) and China (`CN`) return 400 `MARKET_NOT_AVAILABLE` (coming soon). For POST /query, authentication applies first; if every line is outside the contract, it returns 403 with zero per-minute, ordinary daily and AI calls. A storage failure or timeout during key, plan, company or market resolution returns HTTP 503 `UNAVAILABLE` with zero per-minute, ordinary daily and AI calls, without falling back to Free. Otherwise it returns HTTP 200 with per-line errors and counts as one ordinary call.", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "symbol", "in": "path", "required": true, "description": "Korean 6-digit symbol code (e.g. 005930; a leading A is ignored)", "schema": { "type": "string", "pattern": "^A?\\d[0-9A-Z]{5}$", "example": "005930" } }, { "name": "market", "in": "query", "required": false, "description": "Optional — the market is determined by the symbol code (Korean 6-digit code or US ticker). If given, verifies that the symbol belongs to that market (otherwise 400 BAD_SYMBOL). Only KR symbols are supported (others return 400 UNSUPPORTED_MARKET).", "schema": { "type": "string", "enum": [ "KR", "US" ] } }, { "name": "cursor", "in": "query", "required": false, "description": "Next page — pass the previous response's next_cursor as-is, with the same filters. Omit for the first page", "schema": { "type": "string", "maxLength": 2100, "example": "c1.eyJrIjpbIjIwMjYtMTAtMjAiLCIyMDI2MTAyMDAwMDEyMyJdLCJmIjoiQWJDZEVmR2hJaksifQ" } }, { "name": "limit", "in": "query", "required": false, "description": "Items per page (1–200, default 50)", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Quota-Period": { "$ref": "#/components/headers/X-Quota-Period" }, "X-Quota-Reset": { "$ref": "#/components/headers/X-Quota-Reset" }, "X-Markets": { "$ref": "#/components/headers/X-Markets" }, "X-Plan": { "$ref": "#/components/headers/X-Plan" }, "X-Plan-Tier": { "$ref": "#/components/headers/X-Plan-Tier" }, "X-Plan-Expires": { "$ref": "#/components/headers/X-Plan-Expires" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CorporateAction" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page — null if there are no more pages" }, "has_more": { "type": "boolean", "description": "Whether there is a next page" }, "meta": { "type": "object", "properties": { "count": { "type": "integer" }, "total": { "type": "integer" }, "symbol": { "type": "string" }, "market": { "type": "string", "enum": [ "KR", "US" ] }, "issuer_symbol": { "type": "string", "example": "005930", "description": "Symbol whose company-level data (filings, ownership, insiders, treasury stock, financials, consensus …) was read — for Korean preferred shares (e.g. 005935, 005385, 000815) the issuer's common share (005930, 005380, 000810); otherwise the requested symbol" }, "share_class": { "type": [ "string", "null" ], "enum": [ "common", "preferred", null ], "description": "Korean share class — common or preferred. Null for US symbols (not determined)" }, "issuer_note": { "type": "string", "description": "Preferred shares only — note that company-level data is the issuer's" }, "as_of": { "type": "string", "format": "date-time" } } } }, "required": [ "data", "next_cursor", "has_more", "meta" ] }, "example": { "data": [ { "date": "2026-07-31", "symbol": "005930", "company": "삼성전자", "type": "잠정실적", "title": "연결재무제표기준영업(잠정)실적(공정공시)", "filer": "삼성전자", "url": "https://dart.fss.or.kr/dsaf001/main.do?rcpNo=20260731800123", "market": "KR" } ], "next_cursor": null, "has_more": false, "meta": { "count": 1, "total": 9, "symbol": "005930", "market": "KR", "as_of": "2026-10-21T06:30:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequiredOrMarket" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/events": { "get": { "operationId": "listEvents", "tags": [ "Corporate actions" ], "summary": "Classified filing events feed (Korea)", "x-summary-en": "Classified filing events feed (Korea)", "x-markets": [ "KR" ], "x-market-scoped": true, "x-paginated": "cursor", "description": "Feed of classified DART filing events, accumulated daily (newest date and receipt number first) — capital increases, capital reductions, treasury stock, mergers, spin-offs, preliminary earnings, bonds, 5% major shareholding, insider trading, etc. If the range is omitted, the last 30 days.\n\n> Markets: KR · Pagination: cursor + limit\n\n> 🔒 **Paid tiers only** (Launch, Business, Scale, Enterprise; PoC included) — Free keys and accounts whose paid-tier term has ended receive 403 `PLAN_REQUIRED`; accounts whose PoC has ended receive 403 `POC_ENDED`.\n\n> 🌐 **Data coverage** — the account receives data only for the markets it has contracted. A market outside the contract (symbol or `market`) returns 403 `MARKET_NOT_ENTITLED` before any limit is counted; Japan (`JP`) and China (`CN`) return 400 `MARKET_NOT_AVAILABLE` (coming soon). For POST /query, authentication applies first; if every line is outside the contract, it returns 403 with zero per-minute, ordinary daily and AI calls. A storage failure or timeout during key, plan, company or market resolution returns HTTP 503 `UNAVAILABLE` with zero per-minute, ordinary daily and AI calls, without falling back to Free. Otherwise it returns HTTP 200 with per-line errors and counts as one ordinary call.", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "market", "in": "query", "required": false, "description": "Market — only KR is supported (KR if omitted; other values return 400 UNSUPPORTED_MARKET)", "schema": { "type": "string", "enum": [ "KR", "US" ], "default": "KR" } }, { "name": "from", "in": "query", "required": false, "description": "Start date", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "End date", "schema": { "type": "string", "format": "date" } }, { "name": "group", "in": "query", "required": false, "description": "Group", "schema": { "type": "string", "enum": [ "corporate_action", "earnings", "bond", "ownership", "distress", "contract", "other" ] } }, { "name": "type", "in": "query", "required": false, "description": "Subtype", "schema": { "type": "string", "enum": [ "유상증자", "무상증자", "감자", "자기주식소각", "자기주식취득", "자기주식처분", "합병", "분할", "액면변경", "사채발행", "영업양수도", "잠정실적", "상호변경", "배당결정", "주식교환·이전", "부실·구조조정", "대량보유", "내부자거래", "공급계약", "주요리스크", "최대주주변경", "투자·출자", "기술·인허가", "주요경영사항", "주주총회", "최대주주 지분변동", "의결권 권유", "전환·행사가 조정", "전환청구권 행사", "채무보증·대여", "기업가치 제고계획", "대표이사 변경", "실적 전망", "공개매수", "차입 결정", "사채권 처분", "영업·생산 재개", "주식매수선택권", "자기주식 신탁", "기타 경영사항" ], "maxLength": 20 } }, { "name": "symbol", "in": "query", "required": false, "description": "Symbol", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Next page — pass the previous response's next_cursor as-is, with the same filters. Omit for the first page", "schema": { "type": "string", "maxLength": 2100, "example": "c1.eyJrIjpbIjIwMjYtMTAtMjAiLCIyMDI2MTAyMDAwMDEyMyJdLCJmIjoiQWJDZEVmR2hJaksifQ" } }, { "name": "limit", "in": "query", "required": false, "description": "Items per page (1–200, default 50)", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Quota-Period": { "$ref": "#/components/headers/X-Quota-Period" }, "X-Quota-Reset": { "$ref": "#/components/headers/X-Quota-Reset" }, "X-Markets": { "$ref": "#/components/headers/X-Markets" }, "X-Plan": { "$ref": "#/components/headers/X-Plan" }, "X-Plan-Tier": { "$ref": "#/components/headers/X-Plan-Tier" }, "X-Plan-Expires": { "$ref": "#/components/headers/X-Plan-Expires" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DartEvent" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page — null if there are no more pages" }, "has_more": { "type": "boolean", "description": "Whether there is a next page" }, "meta": { "type": "object", "properties": { "count": { "type": "integer" }, "market": { "type": "string", "enum": [ "KR", "US" ] }, "as_of": { "type": "string", "format": "date-time" } } } }, "required": [ "data", "next_cursor", "has_more", "meta" ] }, "example": { "data": [ { "id": "20261020000456", "date": "2026-10-20", "at": "2026-10-20T07:31:00.000Z", "symbol": "005930", "company": "삼성전자", "category": "공급계약", "group": "corporate_action", "title": "단일판매ㆍ공급계약체결", "url": "https://dart.fss.or.kr/dsaf001/main.do?rcpNo=20261020000456", "market": "KR" } ], "next_cursor": "c1.eyJrIjpbIjIwMjYtMTAtMjAiLCIyMDI2MTAyMDAwMDEyMyJdLCJmIjoiQWJDZEVmR2hJaksifQ", "has_more": true, "meta": { "count": 1, "market": "KR", "as_of": "2026-10-21T06:30:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequiredOrMarket" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/macro/rates": { "get": { "operationId": "getMacroRates", "tags": [ "Economic indicators" ], "summary": "US Treasury, real yields and breakeven inflation", "x-summary-en": "US Treasury, real yields and breakeven inflation", "x-markets": [ "US" ], "x-market-scoped": true, "description": "Daily US observations. Omitting date selects the latest completed US regular trading session. Dates use YYYY-MM-DD; future or unfinished sessions return 400 BAD_REQUEST. An explicit non-trading date returns unavailable observations. Reads use stored data without collecting from providers. These fixed matrices are not paginated.\n\nEach row includes observation_date, value, and changes over 1, 5 and 20 trading sessions with from, to and unit. Rate/OAS changes use bp, oil/ETF returns use %, and excess returns over SPY use percentage points (%p). All comparisons use the US equity-session calendar. Missing releases, missing endpoints or gaps within a window produce null and unavailable_reason, never a shifted date or zero. Different series IDs or adjustment bases are not joined. Storage read failures return 503 UNAVAILABLE. Current FRED matrices require a cache refresh within 36 hours. Historical values reflect stored revisions, not point-in-time release vintages.\n\nT10YIE is the 10-year nominal minus real yield: breakeven inflation includes risk and liquidity premiums and is not pure expected inflation. Oil prices are spot USD/barrel. Free access to ICE BofA OAS does not grant redistribution rights; third-party distribution requires written permission from the rights holder.\n\nSectors: XLK, XLC, XLY, XLP, XLE, XLF, XLV, XLI, XLB, XLU, XLRE. Benchmark: SPY; auxiliary: SOXX. Returns use verified adjusted closing prices, not dividend-inclusive total returns. E5/E20 = ETF return minus SPY return over identical dates. E5>0 and E20>0: persistent_outperformance; E5>0 and E20<=0: short_term_recovery; E5<=0 and E20>0: medium_term_strength_short_term_pullback; both <=0: no_relative_strength; missing either: unavailable. Only the 11 sectors rank by descending 20-session excess return, with ticker ascending as the tie-breaker. Any missing sector withholds the entire ranking and top/bottom three. SPY and SOXX are excluded. Interpretation is limited to agreement or conflict among signals, without investment recommendations.\n\n> Markets: US\n\n> 🔒 **Paid tiers only** (Launch, Business, Scale, Enterprise; PoC included) — Free keys and accounts whose paid-tier term has ended receive 403 `PLAN_REQUIRED`; accounts whose PoC has ended receive 403 `POC_ENDED`.\n\n> 🌐 **Data coverage** — the account receives data only for the markets it has contracted. A market outside the contract (symbol or `market`) returns 403 `MARKET_NOT_ENTITLED` before any limit is counted; Japan (`JP`) and China (`CN`) return 400 `MARKET_NOT_AVAILABLE` (coming soon). For POST /query, authentication applies first; if every line is outside the contract, it returns 403 with zero per-minute, ordinary daily and AI calls. A storage failure or timeout during key, plan, company or market resolution returns HTTP 503 `UNAVAILABLE` with zero per-minute, ordinary daily and AI calls, without falling back to Free. Otherwise it returns HTTP 200 with per-line errors and counts as one ordinary call.", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "market", "in": "query", "required": false, "description": "Market — only US is supported (US if omitted; other values return 400 UNSUPPORTED_MARKET)", "schema": { "type": "string", "enum": [ "KR", "US" ], "default": "US" } }, { "name": "date", "in": "query", "required": false, "description": "Observation date; defaults to the latest completed US regular trading session", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Quota-Period": { "$ref": "#/components/headers/X-Quota-Period" }, "X-Quota-Reset": { "$ref": "#/components/headers/X-Quota-Reset" }, "X-Markets": { "$ref": "#/components/headers/X-Markets" }, "X-Plan": { "$ref": "#/components/headers/X-Plan" }, "X-Plan-Tier": { "$ref": "#/components/headers/X-Plan-Tier" }, "X-Plan-Expires": { "$ref": "#/components/headers/X-Plan-Expires" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GlobalMacroFred" }, "example": { "data": { "observation_date": "2026-10-23", "rows": [ { "series_id": "DGS10", "name": "US Treasury 10Y", "observation_date": null, "requested_date": "2026-10-23", "value": null, "unit": "%", "status": "unavailable", "unavailable_reason": "observation_missing", "change_1d": { "value": null, "unit": "bp", "from": "2026-10-22", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "change_5d": { "value": null, "unit": "bp", "from": "2026-10-16", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "change_20d": { "value": null, "unit": "bp", "from": "2026-09-25", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "note": null, "source": "FRED", "source_url": "https://fred.stlouisfed.org/series/DGS10" }, { "series_id": "T10Y2Y", "name": "Treasury 10Y minus 2Y", "observation_date": null, "requested_date": "2026-10-23", "value": null, "unit": "%p", "status": "unavailable", "unavailable_reason": "observation_missing", "change_1d": { "value": null, "unit": "bp", "from": "2026-10-22", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "change_5d": { "value": null, "unit": "bp", "from": "2026-10-16", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "change_20d": { "value": null, "unit": "bp", "from": "2026-09-25", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "note": null, "source": "FRED", "source_url": "https://fred.stlouisfed.org/series/T10Y2Y" }, { "series_id": "DGS2", "name": "US Treasury 2Y", "observation_date": null, "requested_date": "2026-10-23", "value": null, "unit": "%", "status": "unavailable", "unavailable_reason": "observation_missing", "change_1d": { "value": null, "unit": "bp", "from": "2026-10-22", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "change_5d": { "value": null, "unit": "bp", "from": "2026-10-16", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "change_20d": { "value": null, "unit": "bp", "from": "2026-09-25", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "note": null, "source": "FRED", "source_url": "https://fred.stlouisfed.org/series/DGS2" }, { "series_id": "DGS5", "name": "US Treasury 5Y", "observation_date": null, "requested_date": "2026-10-23", "value": null, "unit": "%", "status": "unavailable", "unavailable_reason": "observation_missing", "change_1d": { "value": null, "unit": "bp", "from": "2026-10-22", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "change_5d": { "value": null, "unit": "bp", "from": "2026-10-16", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "change_20d": { "value": null, "unit": "bp", "from": "2026-09-25", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "note": null, "source": "FRED", "source_url": "https://fred.stlouisfed.org/series/DGS5" }, { "series_id": "DGS30", "name": "US Treasury 30Y", "observation_date": null, "requested_date": "2026-10-23", "value": null, "unit": "%", "status": "unavailable", "unavailable_reason": "observation_missing", "change_1d": { "value": null, "unit": "bp", "from": "2026-10-22", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "change_5d": { "value": null, "unit": "bp", "from": "2026-10-16", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "change_20d": { "value": null, "unit": "bp", "from": "2026-09-25", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "note": null, "source": "FRED", "source_url": "https://fred.stlouisfed.org/series/DGS30" }, { "series_id": "DGS3", "name": "US Treasury 3Y", "observation_date": null, "requested_date": "2026-10-23", "value": null, "unit": "%", "status": "unavailable", "unavailable_reason": "observation_missing", "change_1d": { "value": null, "unit": "bp", "from": "2026-10-22", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "change_5d": { "value": null, "unit": "bp", "from": "2026-10-16", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "change_20d": { "value": null, "unit": "bp", "from": "2026-09-25", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "note": null, "source": "FRED", "source_url": "https://fred.stlouisfed.org/series/DGS3" }, { "series_id": "DGS7", "name": "US Treasury 7Y", "observation_date": null, "requested_date": "2026-10-23", "value": null, "unit": "%", "status": "unavailable", "unavailable_reason": "observation_missing", "change_1d": { "value": null, "unit": "bp", "from": "2026-10-22", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "change_5d": { "value": null, "unit": "bp", "from": "2026-10-16", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "change_20d": { "value": null, "unit": "bp", "from": "2026-09-25", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "note": null, "source": "FRED", "source_url": "https://fred.stlouisfed.org/series/DGS7" }, { "series_id": "DGS20", "name": "US Treasury 20Y", "observation_date": null, "requested_date": "2026-10-23", "value": null, "unit": "%", "status": "unavailable", "unavailable_reason": "observation_missing", "change_1d": { "value": null, "unit": "bp", "from": "2026-10-22", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "change_5d": { "value": null, "unit": "bp", "from": "2026-10-16", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "change_20d": { "value": null, "unit": "bp", "from": "2026-09-25", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "note": null, "source": "FRED", "source_url": "https://fred.stlouisfed.org/series/DGS20" }, { "series_id": "DFII10", "name": "US Treasury real yield 10Y", "observation_date": null, "requested_date": "2026-10-23", "value": null, "unit": "%", "status": "unavailable", "unavailable_reason": "observation_missing", "change_1d": { "value": null, "unit": "bp", "from": "2026-10-22", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "change_5d": { "value": null, "unit": "bp", "from": "2026-10-16", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "change_20d": { "value": null, "unit": "bp", "from": "2026-09-25", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "note": null, "source": "FRED", "source_url": "https://fred.stlouisfed.org/series/DFII10" }, { "series_id": "T10YIE", "name": "10Y breakeven inflation", "observation_date": null, "requested_date": "2026-10-23", "value": null, "unit": "%", "status": "unavailable", "unavailable_reason": "observation_missing", "change_1d": { "value": null, "unit": "bp", "from": "2026-10-22", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "change_5d": { "value": null, "unit": "bp", "from": "2026-10-16", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "change_20d": { "value": null, "unit": "bp", "from": "2026-09-25", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "note": "10Y nominal minus real yield; includes risk and liquidity premiums, not pure expected inflation.", "source": "FRED", "source_url": "https://fred.stlouisfed.org/series/T10YIE" } ], "read_status": "available" }, "meta": { "market": "US", "observation_date": "2026-10-23", "as_of": "2026-10-24T01:00:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequiredOrMarket" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/macro/credit": { "get": { "operationId": "getMacroCredit", "tags": [ "Economic indicators" ], "summary": "US credit OAS", "x-summary-en": "US credit OAS", "x-markets": [ "US" ], "x-market-scoped": true, "description": "Daily US observations. Omitting date selects the latest completed US regular trading session. Dates use YYYY-MM-DD; future or unfinished sessions return 400 BAD_REQUEST. An explicit non-trading date returns unavailable observations. Reads use stored data without collecting from providers. These fixed matrices are not paginated.\n\nEach row includes observation_date, value, and changes over 1, 5 and 20 trading sessions with from, to and unit. Rate/OAS changes use bp, oil/ETF returns use %, and excess returns over SPY use percentage points (%p). All comparisons use the US equity-session calendar. Missing releases, missing endpoints or gaps within a window produce null and unavailable_reason, never a shifted date or zero. Different series IDs or adjustment bases are not joined. Storage read failures return 503 UNAVAILABLE. Current FRED matrices require a cache refresh within 36 hours. Historical values reflect stored revisions, not point-in-time release vintages.\n\nT10YIE is the 10-year nominal minus real yield: breakeven inflation includes risk and liquidity premiums and is not pure expected inflation. Oil prices are spot USD/barrel. Free access to ICE BofA OAS does not grant redistribution rights; third-party distribution requires written permission from the rights holder.\n\nSectors: XLK, XLC, XLY, XLP, XLE, XLF, XLV, XLI, XLB, XLU, XLRE. Benchmark: SPY; auxiliary: SOXX. Returns use verified adjusted closing prices, not dividend-inclusive total returns. E5/E20 = ETF return minus SPY return over identical dates. E5>0 and E20>0: persistent_outperformance; E5>0 and E20<=0: short_term_recovery; E5<=0 and E20>0: medium_term_strength_short_term_pullback; both <=0: no_relative_strength; missing either: unavailable. Only the 11 sectors rank by descending 20-session excess return, with ticker ascending as the tie-breaker. Any missing sector withholds the entire ranking and top/bottom three. SPY and SOXX are excluded. Interpretation is limited to agreement or conflict among signals, without investment recommendations.\n\n> Markets: US\n\n> 🔒 **Paid tiers only** (Launch, Business, Scale, Enterprise; PoC included) — Free keys and accounts whose paid-tier term has ended receive 403 `PLAN_REQUIRED`; accounts whose PoC has ended receive 403 `POC_ENDED`.\n\n> 🌐 **Data coverage** — the account receives data only for the markets it has contracted. A market outside the contract (symbol or `market`) returns 403 `MARKET_NOT_ENTITLED` before any limit is counted; Japan (`JP`) and China (`CN`) return 400 `MARKET_NOT_AVAILABLE` (coming soon). For POST /query, authentication applies first; if every line is outside the contract, it returns 403 with zero per-minute, ordinary daily and AI calls. A storage failure or timeout during key, plan, company or market resolution returns HTTP 503 `UNAVAILABLE` with zero per-minute, ordinary daily and AI calls, without falling back to Free. Otherwise it returns HTTP 200 with per-line errors and counts as one ordinary call.", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "market", "in": "query", "required": false, "description": "Market — only US is supported (US if omitted; other values return 400 UNSUPPORTED_MARKET)", "schema": { "type": "string", "enum": [ "KR", "US" ], "default": "US" } }, { "name": "date", "in": "query", "required": false, "description": "Observation date; defaults to the latest completed US regular trading session", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Quota-Period": { "$ref": "#/components/headers/X-Quota-Period" }, "X-Quota-Reset": { "$ref": "#/components/headers/X-Quota-Reset" }, "X-Markets": { "$ref": "#/components/headers/X-Markets" }, "X-Plan": { "$ref": "#/components/headers/X-Plan" }, "X-Plan-Tier": { "$ref": "#/components/headers/X-Plan-Tier" }, "X-Plan-Expires": { "$ref": "#/components/headers/X-Plan-Expires" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GlobalMacroFred" }, "example": { "data": { "observation_date": "2026-10-23", "rows": [ { "series_id": "BAMLH0A0HYM2", "name": "ICE BofA HY OAS", "observation_date": null, "requested_date": "2026-10-23", "value": null, "unit": "%p", "status": "unavailable", "unavailable_reason": "observation_missing", "change_1d": { "value": null, "unit": "bp", "from": "2026-10-22", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "change_5d": { "value": null, "unit": "bp", "from": "2026-10-16", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "change_20d": { "value": null, "unit": "bp", "from": "2026-09-25", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "note": null, "source": "FRED", "source_url": "https://fred.stlouisfed.org/series/BAMLH0A0HYM2" }, { "series_id": "BAMLC0A0CM", "name": "ICE BofA IG OAS", "observation_date": null, "requested_date": "2026-10-23", "value": null, "unit": "%p", "status": "unavailable", "unavailable_reason": "observation_missing", "change_1d": { "value": null, "unit": "bp", "from": "2026-10-22", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "change_5d": { "value": null, "unit": "bp", "from": "2026-10-16", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "change_20d": { "value": null, "unit": "bp", "from": "2026-09-25", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "note": null, "source": "FRED", "source_url": "https://fred.stlouisfed.org/series/BAMLC0A0CM" }, { "series_id": "BAMLC0A4CBBB", "name": "ICE BofA BBB OAS", "observation_date": null, "requested_date": "2026-10-23", "value": null, "unit": "%p", "status": "unavailable", "unavailable_reason": "observation_missing", "change_1d": { "value": null, "unit": "bp", "from": "2026-10-22", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "change_5d": { "value": null, "unit": "bp", "from": "2026-10-16", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "change_20d": { "value": null, "unit": "bp", "from": "2026-09-25", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "note": null, "source": "FRED", "source_url": "https://fred.stlouisfed.org/series/BAMLC0A4CBBB" }, { "series_id": "BAMLC0A1CAAA", "name": "ICE BofA AAA OAS", "observation_date": null, "requested_date": "2026-10-23", "value": null, "unit": "%p", "status": "unavailable", "unavailable_reason": "observation_missing", "change_1d": { "value": null, "unit": "bp", "from": "2026-10-22", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "change_5d": { "value": null, "unit": "bp", "from": "2026-10-16", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "change_20d": { "value": null, "unit": "bp", "from": "2026-09-25", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "note": null, "source": "FRED", "source_url": "https://fred.stlouisfed.org/series/BAMLC0A1CAAA" }, { "series_id": "BAMLC0A3CA", "name": "ICE BofA A OAS", "observation_date": null, "requested_date": "2026-10-23", "value": null, "unit": "%p", "status": "unavailable", "unavailable_reason": "observation_missing", "change_1d": { "value": null, "unit": "bp", "from": "2026-10-22", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "change_5d": { "value": null, "unit": "bp", "from": "2026-10-16", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "change_20d": { "value": null, "unit": "bp", "from": "2026-09-25", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "note": null, "source": "FRED", "source_url": "https://fred.stlouisfed.org/series/BAMLC0A3CA" }, { "series_id": "BAMLH0A1HYBB", "name": "ICE BofA BB OAS", "observation_date": null, "requested_date": "2026-10-23", "value": null, "unit": "%p", "status": "unavailable", "unavailable_reason": "observation_missing", "change_1d": { "value": null, "unit": "bp", "from": "2026-10-22", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "change_5d": { "value": null, "unit": "bp", "from": "2026-10-16", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "change_20d": { "value": null, "unit": "bp", "from": "2026-09-25", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "note": null, "source": "FRED", "source_url": "https://fred.stlouisfed.org/series/BAMLH0A1HYBB" }, { "series_id": "BAMLH0A2HYB", "name": "ICE BofA B OAS", "observation_date": null, "requested_date": "2026-10-23", "value": null, "unit": "%p", "status": "unavailable", "unavailable_reason": "observation_missing", "change_1d": { "value": null, "unit": "bp", "from": "2026-10-22", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "change_5d": { "value": null, "unit": "bp", "from": "2026-10-16", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "change_20d": { "value": null, "unit": "bp", "from": "2026-09-25", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "note": null, "source": "FRED", "source_url": "https://fred.stlouisfed.org/series/BAMLH0A2HYB" } ], "read_status": "available" }, "meta": { "market": "US", "observation_date": "2026-10-23", "as_of": "2026-10-24T01:00:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequiredOrMarket" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/macro/oil": { "get": { "operationId": "getMacroOil", "tags": [ "Economic indicators" ], "summary": "Spot oil", "x-summary-en": "Spot oil", "x-markets": [ "US" ], "x-market-scoped": true, "description": "Daily US observations. Omitting date selects the latest completed US regular trading session. Dates use YYYY-MM-DD; future or unfinished sessions return 400 BAD_REQUEST. An explicit non-trading date returns unavailable observations. Reads use stored data without collecting from providers. These fixed matrices are not paginated.\n\nEach row includes observation_date, value, and changes over 1, 5 and 20 trading sessions with from, to and unit. Rate/OAS changes use bp, oil/ETF returns use %, and excess returns over SPY use percentage points (%p). All comparisons use the US equity-session calendar. Missing releases, missing endpoints or gaps within a window produce null and unavailable_reason, never a shifted date or zero. Different series IDs or adjustment bases are not joined. Storage read failures return 503 UNAVAILABLE. Current FRED matrices require a cache refresh within 36 hours. Historical values reflect stored revisions, not point-in-time release vintages.\n\nT10YIE is the 10-year nominal minus real yield: breakeven inflation includes risk and liquidity premiums and is not pure expected inflation. Oil prices are spot USD/barrel. Free access to ICE BofA OAS does not grant redistribution rights; third-party distribution requires written permission from the rights holder.\n\nSectors: XLK, XLC, XLY, XLP, XLE, XLF, XLV, XLI, XLB, XLU, XLRE. Benchmark: SPY; auxiliary: SOXX. Returns use verified adjusted closing prices, not dividend-inclusive total returns. E5/E20 = ETF return minus SPY return over identical dates. E5>0 and E20>0: persistent_outperformance; E5>0 and E20<=0: short_term_recovery; E5<=0 and E20>0: medium_term_strength_short_term_pullback; both <=0: no_relative_strength; missing either: unavailable. Only the 11 sectors rank by descending 20-session excess return, with ticker ascending as the tie-breaker. Any missing sector withholds the entire ranking and top/bottom three. SPY and SOXX are excluded. Interpretation is limited to agreement or conflict among signals, without investment recommendations.\n\n> Markets: US\n\n> 🔒 **Paid tiers only** (Launch, Business, Scale, Enterprise; PoC included) — Free keys and accounts whose paid-tier term has ended receive 403 `PLAN_REQUIRED`; accounts whose PoC has ended receive 403 `POC_ENDED`.\n\n> 🌐 **Data coverage** — the account receives data only for the markets it has contracted. A market outside the contract (symbol or `market`) returns 403 `MARKET_NOT_ENTITLED` before any limit is counted; Japan (`JP`) and China (`CN`) return 400 `MARKET_NOT_AVAILABLE` (coming soon). For POST /query, authentication applies first; if every line is outside the contract, it returns 403 with zero per-minute, ordinary daily and AI calls. A storage failure or timeout during key, plan, company or market resolution returns HTTP 503 `UNAVAILABLE` with zero per-minute, ordinary daily and AI calls, without falling back to Free. Otherwise it returns HTTP 200 with per-line errors and counts as one ordinary call.", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "market", "in": "query", "required": false, "description": "Market — only US is supported (US if omitted; other values return 400 UNSUPPORTED_MARKET)", "schema": { "type": "string", "enum": [ "KR", "US" ], "default": "US" } }, { "name": "date", "in": "query", "required": false, "description": "Observation date; defaults to the latest completed US regular trading session", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Quota-Period": { "$ref": "#/components/headers/X-Quota-Period" }, "X-Quota-Reset": { "$ref": "#/components/headers/X-Quota-Reset" }, "X-Markets": { "$ref": "#/components/headers/X-Markets" }, "X-Plan": { "$ref": "#/components/headers/X-Plan" }, "X-Plan-Tier": { "$ref": "#/components/headers/X-Plan-Tier" }, "X-Plan-Expires": { "$ref": "#/components/headers/X-Plan-Expires" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GlobalMacroFred" }, "example": { "data": { "observation_date": "2026-10-23", "rows": [ { "series_id": "DCOILWTICO", "name": "WTI spot", "observation_date": null, "requested_date": "2026-10-23", "value": null, "unit": "USD/barrel", "status": "unavailable", "unavailable_reason": "observation_missing", "change_1d": { "value": null, "unit": "%", "from": "2026-10-22", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "change_5d": { "value": null, "unit": "%", "from": "2026-10-16", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "change_20d": { "value": null, "unit": "%", "from": "2026-09-25", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "note": null, "source": "FRED", "source_url": "https://fred.stlouisfed.org/series/DCOILWTICO" }, { "series_id": "DCOILBRENTEU", "name": "Brent spot", "observation_date": null, "requested_date": "2026-10-23", "value": null, "unit": "USD/barrel", "status": "unavailable", "unavailable_reason": "observation_missing", "change_1d": { "value": null, "unit": "%", "from": "2026-10-22", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "change_5d": { "value": null, "unit": "%", "from": "2026-10-16", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "change_20d": { "value": null, "unit": "%", "from": "2026-09-25", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "note": null, "source": "FRED", "source_url": "https://fred.stlouisfed.org/series/DCOILBRENTEU" } ], "read_status": "available" }, "meta": { "market": "US", "observation_date": "2026-10-23", "as_of": "2026-10-24T01:00:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequiredOrMarket" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/macro/sectors": { "get": { "operationId": "getMacroSectors", "tags": [ "Economic indicators" ], "summary": "US sector relative strength", "x-summary-en": "US sector relative strength", "x-markets": [ "US" ], "x-market-scoped": true, "description": "Daily US observations. Omitting date selects the latest completed US regular trading session. Dates use YYYY-MM-DD; future or unfinished sessions return 400 BAD_REQUEST. An explicit non-trading date returns unavailable observations. Reads use stored data without collecting from providers. These fixed matrices are not paginated.\n\nEach row includes observation_date, value, and changes over 1, 5 and 20 trading sessions with from, to and unit. Rate/OAS changes use bp, oil/ETF returns use %, and excess returns over SPY use percentage points (%p). All comparisons use the US equity-session calendar. Missing releases, missing endpoints or gaps within a window produce null and unavailable_reason, never a shifted date or zero. Different series IDs or adjustment bases are not joined. Storage read failures return 503 UNAVAILABLE. Current FRED matrices require a cache refresh within 36 hours. Historical values reflect stored revisions, not point-in-time release vintages.\n\nT10YIE is the 10-year nominal minus real yield: breakeven inflation includes risk and liquidity premiums and is not pure expected inflation. Oil prices are spot USD/barrel. Free access to ICE BofA OAS does not grant redistribution rights; third-party distribution requires written permission from the rights holder.\n\nSectors: XLK, XLC, XLY, XLP, XLE, XLF, XLV, XLI, XLB, XLU, XLRE. Benchmark: SPY; auxiliary: SOXX. Returns use verified adjusted closing prices, not dividend-inclusive total returns. E5/E20 = ETF return minus SPY return over identical dates. E5>0 and E20>0: persistent_outperformance; E5>0 and E20<=0: short_term_recovery; E5<=0 and E20>0: medium_term_strength_short_term_pullback; both <=0: no_relative_strength; missing either: unavailable. Only the 11 sectors rank by descending 20-session excess return, with ticker ascending as the tie-breaker. Any missing sector withholds the entire ranking and top/bottom three. SPY and SOXX are excluded. Interpretation is limited to agreement or conflict among signals, without investment recommendations.\n\n> Markets: US\n\n> 🔒 **Paid tiers only** (Launch, Business, Scale, Enterprise; PoC included) — Free keys and accounts whose paid-tier term has ended receive 403 `PLAN_REQUIRED`; accounts whose PoC has ended receive 403 `POC_ENDED`.\n\n> 🌐 **Data coverage** — the account receives data only for the markets it has contracted. A market outside the contract (symbol or `market`) returns 403 `MARKET_NOT_ENTITLED` before any limit is counted; Japan (`JP`) and China (`CN`) return 400 `MARKET_NOT_AVAILABLE` (coming soon). For POST /query, authentication applies first; if every line is outside the contract, it returns 403 with zero per-minute, ordinary daily and AI calls. A storage failure or timeout during key, plan, company or market resolution returns HTTP 503 `UNAVAILABLE` with zero per-minute, ordinary daily and AI calls, without falling back to Free. Otherwise it returns HTTP 200 with per-line errors and counts as one ordinary call.", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "market", "in": "query", "required": false, "description": "Market — only US is supported (US if omitted; other values return 400 UNSUPPORTED_MARKET)", "schema": { "type": "string", "enum": [ "KR", "US" ], "default": "US" } }, { "name": "date", "in": "query", "required": false, "description": "Observation date; defaults to the latest completed US regular trading session", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Quota-Period": { "$ref": "#/components/headers/X-Quota-Period" }, "X-Quota-Reset": { "$ref": "#/components/headers/X-Quota-Reset" }, "X-Markets": { "$ref": "#/components/headers/X-Markets" }, "X-Plan": { "$ref": "#/components/headers/X-Plan" }, "X-Plan-Tier": { "$ref": "#/components/headers/X-Plan-Tier" }, "X-Plan-Expires": { "$ref": "#/components/headers/X-Plan-Expires" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GlobalMacroSectors" }, "example": { "data": { "observation_date": "2026-10-23", "benchmark": { "symbol": "SPY", "name": "S&P 500 ETF", "role": "benchmark", "observation_date": null, "requested_date": "2026-10-23", "status": "unavailable", "return_1d": { "value": null, "unit": "%", "from": "2026-10-22", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "return_5d": { "value": null, "unit": "%", "from": "2026-10-16", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "return_20d": { "value": null, "unit": "%", "from": "2026-09-25", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "excess_5d": { "value": null, "unit": "%p", "from": "2026-10-16", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "excess_20d": { "value": null, "unit": "%p", "from": "2026-09-25", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "classification": "unavailable", "rank_20d": null }, "auxiliary": { "symbol": "SOXX", "name": "Semiconductor ETF", "role": "auxiliary", "observation_date": null, "requested_date": "2026-10-23", "status": "unavailable", "return_1d": { "value": null, "unit": "%", "from": "2026-10-22", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "return_5d": { "value": null, "unit": "%", "from": "2026-10-16", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "return_20d": { "value": null, "unit": "%", "from": "2026-09-25", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "excess_5d": { "value": null, "unit": "%p", "from": "2026-10-16", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "excess_20d": { "value": null, "unit": "%p", "from": "2026-09-25", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "classification": "unavailable", "rank_20d": null }, "sectors": [ { "symbol": "XLK", "name": "Information technology", "role": "sector", "observation_date": null, "requested_date": "2026-10-23", "status": "unavailable", "return_1d": { "value": null, "unit": "%", "from": "2026-10-22", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "return_5d": { "value": null, "unit": "%", "from": "2026-10-16", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "return_20d": { "value": null, "unit": "%", "from": "2026-09-25", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "excess_5d": { "value": null, "unit": "%p", "from": "2026-10-16", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "excess_20d": { "value": null, "unit": "%p", "from": "2026-09-25", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "classification": "unavailable", "rank_20d": null }, { "symbol": "XLC", "name": "Communication services", "role": "sector", "observation_date": null, "requested_date": "2026-10-23", "status": "unavailable", "return_1d": { "value": null, "unit": "%", "from": "2026-10-22", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "return_5d": { "value": null, "unit": "%", "from": "2026-10-16", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "return_20d": { "value": null, "unit": "%", "from": "2026-09-25", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "excess_5d": { "value": null, "unit": "%p", "from": "2026-10-16", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "excess_20d": { "value": null, "unit": "%p", "from": "2026-09-25", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "classification": "unavailable", "rank_20d": null }, { "symbol": "XLY", "name": "Consumer discretionary", "role": "sector", "observation_date": null, "requested_date": "2026-10-23", "status": "unavailable", "return_1d": { "value": null, "unit": "%", "from": "2026-10-22", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "return_5d": { "value": null, "unit": "%", "from": "2026-10-16", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "return_20d": { "value": null, "unit": "%", "from": "2026-09-25", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "excess_5d": { "value": null, "unit": "%p", "from": "2026-10-16", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "excess_20d": { "value": null, "unit": "%p", "from": "2026-09-25", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "classification": "unavailable", "rank_20d": null }, { "symbol": "XLP", "name": "Consumer staples", "role": "sector", "observation_date": null, "requested_date": "2026-10-23", "status": "unavailable", "return_1d": { "value": null, "unit": "%", "from": "2026-10-22", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "return_5d": { "value": null, "unit": "%", "from": "2026-10-16", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "return_20d": { "value": null, "unit": "%", "from": "2026-09-25", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "excess_5d": { "value": null, "unit": "%p", "from": "2026-10-16", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "excess_20d": { "value": null, "unit": "%p", "from": "2026-09-25", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "classification": "unavailable", "rank_20d": null }, { "symbol": "XLE", "name": "Energy", "role": "sector", "observation_date": null, "requested_date": "2026-10-23", "status": "unavailable", "return_1d": { "value": null, "unit": "%", "from": "2026-10-22", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "return_5d": { "value": null, "unit": "%", "from": "2026-10-16", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "return_20d": { "value": null, "unit": "%", "from": "2026-09-25", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "excess_5d": { "value": null, "unit": "%p", "from": "2026-10-16", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "excess_20d": { "value": null, "unit": "%p", "from": "2026-09-25", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "classification": "unavailable", "rank_20d": null }, { "symbol": "XLF", "name": "Financials", "role": "sector", "observation_date": null, "requested_date": "2026-10-23", "status": "unavailable", "return_1d": { "value": null, "unit": "%", "from": "2026-10-22", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "return_5d": { "value": null, "unit": "%", "from": "2026-10-16", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "return_20d": { "value": null, "unit": "%", "from": "2026-09-25", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "excess_5d": { "value": null, "unit": "%p", "from": "2026-10-16", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "excess_20d": { "value": null, "unit": "%p", "from": "2026-09-25", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "classification": "unavailable", "rank_20d": null }, { "symbol": "XLV", "name": "Health care", "role": "sector", "observation_date": null, "requested_date": "2026-10-23", "status": "unavailable", "return_1d": { "value": null, "unit": "%", "from": "2026-10-22", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "return_5d": { "value": null, "unit": "%", "from": "2026-10-16", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "return_20d": { "value": null, "unit": "%", "from": "2026-09-25", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "excess_5d": { "value": null, "unit": "%p", "from": "2026-10-16", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "excess_20d": { "value": null, "unit": "%p", "from": "2026-09-25", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "classification": "unavailable", "rank_20d": null }, { "symbol": "XLI", "name": "Industrials", "role": "sector", "observation_date": null, "requested_date": "2026-10-23", "status": "unavailable", "return_1d": { "value": null, "unit": "%", "from": "2026-10-22", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "return_5d": { "value": null, "unit": "%", "from": "2026-10-16", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "return_20d": { "value": null, "unit": "%", "from": "2026-09-25", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "excess_5d": { "value": null, "unit": "%p", "from": "2026-10-16", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "excess_20d": { "value": null, "unit": "%p", "from": "2026-09-25", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "classification": "unavailable", "rank_20d": null }, { "symbol": "XLB", "name": "Materials", "role": "sector", "observation_date": null, "requested_date": "2026-10-23", "status": "unavailable", "return_1d": { "value": null, "unit": "%", "from": "2026-10-22", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "return_5d": { "value": null, "unit": "%", "from": "2026-10-16", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "return_20d": { "value": null, "unit": "%", "from": "2026-09-25", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "excess_5d": { "value": null, "unit": "%p", "from": "2026-10-16", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "excess_20d": { "value": null, "unit": "%p", "from": "2026-09-25", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "classification": "unavailable", "rank_20d": null }, { "symbol": "XLU", "name": "Utilities", "role": "sector", "observation_date": null, "requested_date": "2026-10-23", "status": "unavailable", "return_1d": { "value": null, "unit": "%", "from": "2026-10-22", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "return_5d": { "value": null, "unit": "%", "from": "2026-10-16", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "return_20d": { "value": null, "unit": "%", "from": "2026-09-25", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "excess_5d": { "value": null, "unit": "%p", "from": "2026-10-16", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "excess_20d": { "value": null, "unit": "%p", "from": "2026-09-25", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "classification": "unavailable", "rank_20d": null }, { "symbol": "XLRE", "name": "Real estate", "role": "sector", "observation_date": null, "requested_date": "2026-10-23", "status": "unavailable", "return_1d": { "value": null, "unit": "%", "from": "2026-10-22", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "return_5d": { "value": null, "unit": "%", "from": "2026-10-16", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "return_20d": { "value": null, "unit": "%", "from": "2026-09-25", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "excess_5d": { "value": null, "unit": "%p", "from": "2026-10-16", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "excess_20d": { "value": null, "unit": "%p", "from": "2026-09-25", "to": "2026-10-23", "unavailable_reason": "observation_missing" }, "classification": "unavailable", "rank_20d": null } ], "ranking_status": "unavailable", "top_3": [], "bottom_3": [], "return_basis": "adjusted_close_price_return", "source": "stored_us_daily", "read_status": "available" }, "meta": { "market": "US", "observation_date": "2026-10-23", "as_of": "2026-10-24T01:00:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequiredOrMarket" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/economic-calendar": { "get": { "operationId": "listEconomicCalendar", "tags": [ "Economic indicators" ], "summary": "Economic calendar (Korea & US)", "x-summary-en": "Economic calendar (Korea & US)", "x-markets": [ "KR", "US" ], "x-market-scoped": true, "x-paginated": "cursor", "description": "Economic calendar (date and time ascending).\n\n- `market=KR` (KR if omitted — for legacy compatibility): base rate decisions and the Bank of Korea statistics release schedule (GDP, balance of payments, consumer sentiment, business survey, producer prices, etc.). These are schedules, not figures. If the range is omitted, from 3 days ago. Filter with `importance`.\n- `market=US`: US economic indicator releases, FDA, and commodity events — release time, importance, previous value, actual value. Default range = 30 days from today. Filter with `category`, `ticker`, and `importance` (minimum level).\n- The legacy `country` field is also accepted (`market` takes precedence). Up to 300 items per request (legacy compatibility).\n\n> Markets: KR · US · Pagination: cursor + limit\n\n> 🔒 **Paid tiers only** (Launch, Business, Scale, Enterprise; PoC included) — Free keys and accounts whose paid-tier term has ended receive 403 `PLAN_REQUIRED`; accounts whose PoC has ended receive 403 `POC_ENDED`.\n\n> 🌐 **Data coverage** — the account receives data only for the markets it has contracted. A market outside the contract (symbol or `market`) returns 403 `MARKET_NOT_ENTITLED` before any limit is counted; Japan (`JP`) and China (`CN`) return 400 `MARKET_NOT_AVAILABLE` (coming soon). For POST /query, authentication applies first; if every line is outside the contract, it returns 403 with zero per-minute, ordinary daily and AI calls. A storage failure or timeout during key, plan, company or market resolution returns HTTP 503 `UNAVAILABLE` with zero per-minute, ordinary daily and AI calls, without falling back to Free. Otherwise it returns HTTP 200 with per-line errors and counts as one ordinary call.", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "market", "in": "query", "required": false, "description": "Market — KR or US (KR if omitted)", "schema": { "type": "string", "enum": [ "KR", "US" ], "default": "KR" } }, { "name": "from", "in": "query", "required": false, "description": "Start date", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "End date", "schema": { "type": "string", "format": "date" } }, { "name": "importance", "in": "query", "required": false, "description": "KR: that importance level only; US: minimum importance", "schema": { "type": "string", "enum": [ "high", "med", "low" ] } }, { "name": "category", "in": "query", "required": false, "description": "US only — category", "schema": { "type": "string", "enum": [ "economic", "fda", "commodity" ] } }, { "name": "ticker", "in": "query", "required": false, "description": "US only — related symbol", "schema": { "type": "string" } }, { "name": "country", "in": "query", "required": false, "description": "Legacy field (deprecated) — use market", "schema": { "type": "string", "enum": [ "KR", "US" ] } }, { "name": "cursor", "in": "query", "required": false, "description": "Next page — pass the previous response's next_cursor as-is, with the same filters. Omit for the first page", "schema": { "type": "string", "maxLength": 2100, "example": "c1.eyJrIjpbIjIwMjYtMTAtMjAiLCIyMDI2MTAyMDAwMDEyMyJdLCJmIjoiQWJDZEVmR2hJaksifQ" } }, { "name": "limit", "in": "query", "required": false, "description": "Items per page (1–300, default 50)", "schema": { "type": "integer", "minimum": 1, "maximum": 300, "default": 50 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Quota-Period": { "$ref": "#/components/headers/X-Quota-Period" }, "X-Quota-Reset": { "$ref": "#/components/headers/X-Quota-Reset" }, "X-Markets": { "$ref": "#/components/headers/X-Markets" }, "X-Plan": { "$ref": "#/components/headers/X-Plan" }, "X-Plan-Tier": { "$ref": "#/components/headers/X-Plan-Tier" }, "X-Plan-Expires": { "$ref": "#/components/headers/X-Plan-Expires" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/EconEvent" }, { "$ref": "#/components/schemas/UsEconEvent" } ] } }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page — null if there are no more pages" }, "has_more": { "type": "boolean", "description": "Whether there is a next page" }, "meta": { "type": "object", "properties": { "count": { "type": "integer" }, "market": { "type": "string", "enum": [ "KR", "US" ] }, "country": { "type": "string" }, "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "as_of": { "type": "string", "format": "date-time" } } } }, "required": [ "data", "next_cursor", "has_more", "meta" ] }, "example": { "data": [ { "id": "kr_20261023_rate", "date": "2026-10-23", "time": "10:00", "event": "금융통화위원회 통화정책방향 결정", "category": "rate", "importance": "high", "agency": "한국은행", "stage": "scheduled", "market": "KR" } ], "next_cursor": "c1.eyJrIjpbIjIwMjYtMTAtMjAiLCIyMDI2MTAyMDAwMDEyMyJdLCJmIjoiQWJDZEVmR2hJaksifQ", "has_more": true, "meta": { "count": 1, "market": "KR", "country": "KR", "as_of": "2026-10-21T06:30:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequiredOrMarket" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/us-economic-calendar": { "get": { "operationId": "listUsEconomicCalendar", "tags": [ "Economic indicators" ], "summary": "US economic calendar (legacy path)", "x-summary-en": "US economic calendar (legacy path)", "x-markets": [ "US" ], "x-market-scoped": true, "x-paginated": "cursor", "description": "**Legacy path (deprecated).** Same as `/economic-calendar?market=US`. US economic indicator releases, FDA, and commodity events — release time, importance, previous value, actual value. Default range = 30 days from today.\n\n> Markets: US · Pagination: cursor + limit\n\n> 🔒 **Paid tiers only** (Launch, Business, Scale, Enterprise; PoC included) — Free keys and accounts whose paid-tier term has ended receive 403 `PLAN_REQUIRED`; accounts whose PoC has ended receive 403 `POC_ENDED`.\n\n> 🌐 **Data coverage** — the account receives data only for the markets it has contracted. A market outside the contract (symbol or `market`) returns 403 `MARKET_NOT_ENTITLED` before any limit is counted; Japan (`JP`) and China (`CN`) return 400 `MARKET_NOT_AVAILABLE` (coming soon). For POST /query, authentication applies first; if every line is outside the contract, it returns 403 with zero per-minute, ordinary daily and AI calls. A storage failure or timeout during key, plan, company or market resolution returns HTTP 503 `UNAVAILABLE` with zero per-minute, ordinary daily and AI calls, without falling back to Free. Otherwise it returns HTTP 200 with per-line errors and counts as one ordinary call.", "deprecated": true, "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "market", "in": "query", "required": false, "description": "Market — only US is supported (US if omitted; other values return 400 UNSUPPORTED_MARKET)", "schema": { "type": "string", "enum": [ "KR", "US" ], "default": "US" } }, { "name": "from", "in": "query", "required": false, "description": "Start date (default today)", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "End date (default +30 days)", "schema": { "type": "string", "format": "date" } }, { "name": "category", "in": "query", "required": false, "description": "Category", "schema": { "type": "string", "enum": [ "economic", "fda", "commodity" ] } }, { "name": "importance", "in": "query", "required": false, "description": "Minimum importance", "schema": { "type": "string", "enum": [ "high", "med", "low" ] } }, { "name": "ticker", "in": "query", "required": false, "description": "Related symbol", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Next page — pass the previous response's next_cursor as-is, with the same filters. Omit for the first page", "schema": { "type": "string", "maxLength": 2100, "example": "c1.eyJrIjpbIjIwMjYtMTAtMjAiLCIyMDI2MTAyMDAwMDEyMyJdLCJmIjoiQWJDZEVmR2hJaksifQ" } }, { "name": "limit", "in": "query", "required": false, "description": "Items per page (1–300, default 50)", "schema": { "type": "integer", "minimum": 1, "maximum": 300, "default": 50 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Quota-Period": { "$ref": "#/components/headers/X-Quota-Period" }, "X-Quota-Reset": { "$ref": "#/components/headers/X-Quota-Reset" }, "X-Markets": { "$ref": "#/components/headers/X-Markets" }, "X-Plan": { "$ref": "#/components/headers/X-Plan" }, "X-Plan-Tier": { "$ref": "#/components/headers/X-Plan-Tier" }, "X-Plan-Expires": { "$ref": "#/components/headers/X-Plan-Expires" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/UsEconEvent" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page — null if there are no more pages" }, "has_more": { "type": "boolean", "description": "Whether there is a next page" }, "meta": { "type": "object", "properties": { "count": { "type": "integer" }, "market": { "type": "string", "enum": [ "KR", "US" ] }, "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "as_of": { "type": "string", "format": "date-time" } } } }, "required": [ "data", "next_cursor", "has_more", "meta" ] }, "example": { "data": [ { "id": "us_cpi_202610", "category": "economic", "date": "2026-10-28", "time": "08:30", "title": "소비자물가지수(CPI) 전월 대비", "title_en": "CPI MoM", "importance": 3, "country": "US", "ticker": null, "actual": null, "consensus": "0.3", "prior": "0.4", "unit": "%", "note": null, "market": "US" } ], "next_cursor": "c1.eyJrIjpbIjIwMjYtMTAtMjAiLCIyMDI2MTAyMDAwMDEyMyJdLCJmIjoiQWJDZEVmR2hJaksifQ", "has_more": true, "meta": { "count": 1, "market": "US", "from": "2026-10-21", "to": "2026-11-20", "as_of": "2026-10-21T06:30:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequiredOrMarket" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/news": { "get": { "operationId": "listNews", "tags": [ "News" ], "summary": "News feed", "x-summary-en": "News feed", "x-markets": [ "KR", "US" ], "x-market-scoped": true, "x-paginated": "cursor", "description": "Latest stock news (newest publication time first) — title, publisher, publication time, opening excerpt (up to 140 characters), and source link. Full article text is not provided.\n\n- **Scope**: `market=KR` = Korean media articles (in Korean); `market=US` = US articles (English-language articles from international media, corporate press releases, SEC filing alerts; the English title is in `title` and Phoenix AI's Korean translation in `title_ko`). Both if omitted. Only articles **already collected** by Phoenix AI are returned (nothing new is fetched at request time).\n- **Symbol filter** (`symbol`): only articles with a verified symbol tag — if a tag verification record exists, its result is used; otherwise the company (name or ticker) must appear in the title or excerpt. Because of this filtering a page may be shorter than `limit`, so follow `has_more` and `next_cursor`.\n- **Publisher** (`publisher`): the publisher name. When an aggregator service's name appears in the publisher field, it is shown as '해외 언론' (international media) for international articles or '뉴스' (news) for Korean articles.\n- Near-duplicates (the same article republished with reworded text) are reduced to the first occurrence within a page.\n- The `market` of each article item keeps the legacy notation (`kr`, `us`).\n\n> Markets: KR · US · Pagination: cursor + limit\n\n> 🔑 Works with Free trial keys as well as PoC and paid-tier keys. Accounts whose PoC has ended receive 403 `POC_ENDED`.\n\n> 🌐 **Data coverage** — the account receives data only for the markets it has contracted. A market outside the contract (symbol or `market`) returns 403 `MARKET_NOT_ENTITLED` before any limit is counted; Japan (`JP`) and China (`CN`) return 400 `MARKET_NOT_AVAILABLE` (coming soon). For POST /query, authentication applies first; if every line is outside the contract, it returns 403 with zero per-minute, ordinary daily and AI calls. A storage failure or timeout during key, plan, company or market resolution returns HTTP 503 `UNAVAILABLE` with zero per-minute, ordinary daily and AI calls, without falling back to Free. Otherwise it returns HTTP 200 with per-line errors and counts as one ordinary call.", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "symbol", "in": "query", "required": false, "description": "Symbol code (005930) or US ticker (NVDA)", "schema": { "type": "string", "pattern": "^[A-Za-z0-9.]{1,12}$" } }, { "name": "market", "in": "query", "required": false, "description": "Market — KR or US (both if omitted)", "schema": { "type": "string", "enum": [ "KR", "US" ] } }, { "name": "cursor", "in": "query", "required": false, "description": "Next page — pass the previous response's next_cursor as-is, with the same filters. Omit for the first page", "schema": { "type": "string", "maxLength": 2100, "example": "c1.eyJrIjpbIjIwMjYtMTAtMjAiLCIyMDI2MTAyMDAwMDEyMyJdLCJmIjoiQWJDZEVmR2hJaksifQ" } }, { "name": "limit", "in": "query", "required": false, "description": "Items per page (1–200, default 50)", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Quota-Period": { "$ref": "#/components/headers/X-Quota-Period" }, "X-Quota-Reset": { "$ref": "#/components/headers/X-Quota-Reset" }, "X-Markets": { "$ref": "#/components/headers/X-Markets" }, "X-Plan": { "$ref": "#/components/headers/X-Plan" }, "X-Plan-Tier": { "$ref": "#/components/headers/X-Plan-Tier" }, "X-Plan-Expires": { "$ref": "#/components/headers/X-Plan-Expires" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Article" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page — null if there are no more pages" }, "has_more": { "type": "boolean", "description": "Whether there is a next page" }, "meta": { "type": "object", "properties": { "count": { "type": "integer" }, "symbol": { "type": [ "string", "null" ] }, "market": { "type": "string", "enum": [ "KR", "US" ] }, "as_of": { "type": "string", "format": "date-time" }, "coverage": { "type": "string", "description": "Which articles this list covers" } } } }, "required": [ "data", "next_cursor", "has_more", "meta" ] }, "example": { "data": [ { "id": "art_3f9k", "symbol": "005930", "market": "kr", "lang": "ko", "title_ko": null, "title": "삼성전자, 3분기 메모리 출하 늘어", "summary": "삼성전자가 3분기 메모리 출하량이 전 분기보다 늘었다고 밝혔다. 서버용 고대역폭 메모리 비중이 커졌다.", "publisher": "연합뉴스", "published_at": "2026-10-21T05:12:00.000Z", "url": "https://api.chickstockfi.com/openapi/v1/articles/art_3f9k/read" } ], "next_cursor": "c1.eyJrIjpbIjIwMjYtMTAtMjAiLCIyMDI2MTAyMDAwMDEyMyJdLCJmIjoiQWJDZEVmR2hJaksifQ", "has_more": true, "meta": { "count": 1, "symbol": "005930", "as_of": "2026-10-21T06:30:00.000Z", "coverage": "국내 기사(국내 언론, 한국어)와 미국 기사(해외 언론의 영문 기사·기업 보도자료·SEC 공시 속보)" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PocEndedOrMarket" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/news/{symbol}": { "get": { "operationId": "listNewsBySymbol", "tags": [ "News" ], "summary": "News by symbol", "x-summary-en": "News by symbol", "x-markets": [ "KR", "US" ], "x-market-scoped": true, "x-paginated": "cursor", "description": "`/news` with the symbol specified in the path (Korean 6-digit code or US ticker). Response shape and scope are the same as `/news`.\n\n- **Scope**: `market=KR` = Korean media articles (in Korean); `market=US` = US articles (English-language articles from international media, corporate press releases, SEC filing alerts; the English title is in `title` and Phoenix AI's Korean translation in `title_ko`). Both if omitted. Only articles **already collected** by Phoenix AI are returned (nothing new is fetched at request time).\n- **Symbol filter** (`symbol`): only articles with a verified symbol tag — if a tag verification record exists, its result is used; otherwise the company (name or ticker) must appear in the title or excerpt. Because of this filtering a page may be shorter than `limit`, so follow `has_more` and `next_cursor`.\n- **Publisher** (`publisher`): the publisher name. When an aggregator service's name appears in the publisher field, it is shown as '해외 언론' (international media) for international articles or '뉴스' (news) for Korean articles.\n- Near-duplicates (the same article republished with reworded text) are reduced to the first occurrence within a page.\n\n> Markets: KR · US · Pagination: cursor + limit\n\n> 🔑 Works with Free trial keys as well as PoC and paid-tier keys. Accounts whose PoC has ended receive 403 `POC_ENDED`.\n\n> 🌐 **Data coverage** — the account receives data only for the markets it has contracted. A market outside the contract (symbol or `market`) returns 403 `MARKET_NOT_ENTITLED` before any limit is counted; Japan (`JP`) and China (`CN`) return 400 `MARKET_NOT_AVAILABLE` (coming soon). For POST /query, authentication applies first; if every line is outside the contract, it returns 403 with zero per-minute, ordinary daily and AI calls. A storage failure or timeout during key, plan, company or market resolution returns HTTP 503 `UNAVAILABLE` with zero per-minute, ordinary daily and AI calls, without falling back to Free. Otherwise it returns HTTP 200 with per-line errors and counts as one ordinary call.", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "symbol", "in": "path", "required": true, "description": "Symbol code or ticker", "schema": { "type": "string", "pattern": "^[A-Za-z0-9.]{1,12}$", "example": "005930" } }, { "name": "market", "in": "query", "required": false, "description": "Market — KR or US (both if omitted)", "schema": { "type": "string", "enum": [ "KR", "US" ] } }, { "name": "cursor", "in": "query", "required": false, "description": "Next page — pass the previous response's next_cursor as-is, with the same filters. Omit for the first page", "schema": { "type": "string", "maxLength": 2100, "example": "c1.eyJrIjpbIjIwMjYtMTAtMjAiLCIyMDI2MTAyMDAwMDEyMyJdLCJmIjoiQWJDZEVmR2hJaksifQ" } }, { "name": "limit", "in": "query", "required": false, "description": "Items per page (1–200, default 50)", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Quota-Period": { "$ref": "#/components/headers/X-Quota-Period" }, "X-Quota-Reset": { "$ref": "#/components/headers/X-Quota-Reset" }, "X-Markets": { "$ref": "#/components/headers/X-Markets" }, "X-Plan": { "$ref": "#/components/headers/X-Plan" }, "X-Plan-Tier": { "$ref": "#/components/headers/X-Plan-Tier" }, "X-Plan-Expires": { "$ref": "#/components/headers/X-Plan-Expires" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Article" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page — null if there are no more pages" }, "has_more": { "type": "boolean", "description": "Whether there is a next page" }, "meta": { "type": "object", "properties": { "count": { "type": "integer" }, "symbol": { "type": [ "string", "null" ] }, "market": { "type": "string", "enum": [ "KR", "US" ] }, "as_of": { "type": "string", "format": "date-time" }, "coverage": { "type": "string", "description": "Which articles this list covers" } } } }, "required": [ "data", "next_cursor", "has_more", "meta" ] }, "example": { "data": [ { "id": "art_3f9k", "symbol": "005930", "market": "kr", "lang": "ko", "title_ko": null, "title": "삼성전자, 3분기 메모리 출하 늘어", "summary": "삼성전자가 3분기 메모리 출하량이 전 분기보다 늘었다고 밝혔다. 서버용 고대역폭 메모리 비중이 커졌다.", "publisher": "연합뉴스", "published_at": "2026-10-21T05:12:00.000Z", "url": "https://api.chickstockfi.com/openapi/v1/articles/art_3f9k/read" } ], "next_cursor": "c1.eyJrIjpbIjIwMjYtMTAtMjAiLCIyMDI2MTAyMDAwMDEyMyJdLCJmIjoiQWJDZEVmR2hJaksifQ", "has_more": true, "meta": { "count": 1, "symbol": "005930", "as_of": "2026-10-21T06:30:00.000Z", "coverage": "국내 기사(국내 언론, 한국어)와 미국 기사(해외 언론의 영문 기사·기업 보도자료·SEC 공시 속보)" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PocEndedOrMarket" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/search": { "get": { "operationId": "searchNews", "tags": [ "News" ], "summary": "Keyword news search (Korea)", "x-summary-en": "Keyword news search (Korea)", "x-markets": [ "KR" ], "x-market-scoped": true, "x-paginated": "cursor", "description": "Searches Korean news by keyword or theme (semiconductors, interest rates, AI, etc.), ordered by search relevance. `mode=title` searches titles; `mode=all` extends the search to article bodies (responses include only the opening excerpt). Up to 30 items per page (search source limit), up to 100 pages via cursor.\n\n> Markets: KR · Pagination: cursor + limit\n\n> 🔑 Works with Free trial keys as well as PoC and paid-tier keys. Accounts whose PoC has ended receive 403 `POC_ENDED`.\n\n> 🌐 **Data coverage** — the account receives data only for the markets it has contracted. A market outside the contract (symbol or `market`) returns 403 `MARKET_NOT_ENTITLED` before any limit is counted; Japan (`JP`) and China (`CN`) return 400 `MARKET_NOT_AVAILABLE` (coming soon). For POST /query, authentication applies first; if every line is outside the contract, it returns 403 with zero per-minute, ordinary daily and AI calls. A storage failure or timeout during key, plan, company or market resolution returns HTTP 503 `UNAVAILABLE` with zero per-minute, ordinary daily and AI calls, without falling back to Free. Otherwise it returns HTTP 200 with per-line errors and counts as one ordinary call.", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Search query", "schema": { "type": "string", "minLength": 1, "maxLength": 40, "example": "반도체" } }, { "name": "mode", "in": "query", "required": false, "description": "title = titles only; all = including article body", "schema": { "type": "string", "enum": [ "title", "all" ], "default": "title" } }, { "name": "market", "in": "query", "required": false, "description": "Market — only KR is supported (KR if omitted; other values return 400 UNSUPPORTED_MARKET)", "schema": { "type": "string", "enum": [ "KR", "US" ], "default": "KR" } }, { "name": "cursor", "in": "query", "required": false, "description": "Next page — pass the previous response's next_cursor as-is, with the same filters. Omit for the first page", "schema": { "type": "string", "maxLength": 2100, "example": "c1.eyJrIjpbIjIwMjYtMTAtMjAiLCIyMDI2MTAyMDAwMDEyMyJdLCJmIjoiQWJDZEVmR2hJaksifQ" } }, { "name": "limit", "in": "query", "required": false, "description": "Items per page (1–30, default 20)", "schema": { "type": "integer", "minimum": 1, "maximum": 30, "default": 20 } }, { "name": "page", "in": "query", "required": false, "description": "Legacy compatibility (deprecated) — use cursor. Only sets the starting position when no cursor is given", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "deprecated": true } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Quota-Period": { "$ref": "#/components/headers/X-Quota-Period" }, "X-Quota-Reset": { "$ref": "#/components/headers/X-Quota-Reset" }, "X-Markets": { "$ref": "#/components/headers/X-Markets" }, "X-Plan": { "$ref": "#/components/headers/X-Plan" }, "X-Plan-Tier": { "$ref": "#/components/headers/X-Plan-Tier" }, "X-Plan-Expires": { "$ref": "#/components/headers/X-Plan-Expires" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SearchArticle" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page — null if there are no more pages" }, "has_more": { "type": "boolean", "description": "Whether there is a next page" }, "meta": { "type": "object", "properties": { "count": { "type": "integer" }, "total": { "type": "integer" }, "q": { "type": "string" }, "mode": { "type": "string" }, "market": { "type": "string", "enum": [ "KR", "US" ] }, "page": { "type": "integer" }, "as_of": { "type": "string", "format": "date-time" } } } }, "required": [ "data", "next_cursor", "has_more", "meta" ] }, "example": { "data": [ { "id": "an_Q2xYz9", "market": "KR", "title": "반도체 수출 3개월 연속 증가", "summary": "10월 1~20일 반도체 수출이 1년 전보다 늘었다.", "publisher": "연합뉴스", "published_at": "2026-10-21T01:00:00.000Z", "url": "https://api.chickstockfi.com/openapi/v1/articles/an_Q2xYz9/read" } ], "next_cursor": "c1.eyJrIjpbIjIwMjYtMTAtMjAiLCIyMDI2MTAyMDAwMDEyMyJdLCJmIjoiQWJDZEVmR2hJaksifQ", "has_more": true, "meta": { "count": 1, "total": 128, "q": "반도체", "mode": "title", "market": "KR", "as_of": "2026-10-21T06:30:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PocEndedOrMarket" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/articles/{id}/read": { "get": { "operationId": "readArticle", "tags": [ "News" ], "summary": "Redirect to the original article", "x-summary-en": "Redirect to the original article", "x-markets": [], "description": "302 redirect to the original article page (for browser clicks — no API key).\n\n> 🔓 No API key required.", "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Article id (art_… or an_…)", "schema": { "type": "string", "example": "art_3f9k" } } ], "responses": { "200": { "description": "Not used (302 redirect)" }, "302": { "description": "Redirect to the original", "headers": { "Location": { "schema": { "type": "string", "format": "uri" }, "description": "Original URL" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "description": "Article not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "Article not found.", "docs": "https://openapi.chickstockfi.com/docs" } } } } }, "429": { "$ref": "#/components/responses/EdgeRateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/briefings/{symbol}": { "get": { "operationId": "getBriefing", "tags": [ "Briefing" ], "summary": "Daily stock briefing (Korea)", "x-summary-en": "Daily stock briefing (Korea)", "x-markets": [ "KR" ], "x-market-scoped": true, "description": "AI daily briefing for a Korean symbol (KOSPI, KOSDAQ, ETF) — price change, key issues, body text, and related articles (opening excerpts only).\n\n- If `date` is omitted, today (recommended after market close) — the first sentence and `price` use the current session and the current price.\n- **Past dates** (`date` before today, Korea time): returns the briefing stored for that date **exactly as it was written** — the session and `price` are as of when it was written (not today's quote). With no stored copy the response is 404 `NO_HISTORY`; past briefings are never generated (`fresh=true` is ignored too, with `meta.fresh_ignored: true`).\n- **Future dates** return 400 `BAD_DATE`.\n- `data.briefing_date` = the requested (stored) date; `data.date` = the regular-session trading day the briefing covers (a briefing written before the open covers the previous trading day).\n- `fresh=true` regenerates the briefing, for today only — if the previous generation is within the cooldown, the stored copy is returned with `meta.fresh_available_in_sec`.\n- `tone=formal` converts summary, key issues and body to formal Korean without additional generation. Unsupported sentences/fragments are preserved as quotations inside formal sentences and counted in `meta.tone_quoted_sentences`. Article headlines/excerpts keep their original tone. Omitting the option preserves the existing tone. Broker and vendor names are masked with neutral labels in every tone.\n- **Standard shape `{ data, meta }`**: `data.market` is `KR` and the exchange is `data.exchange`. The old top-level fields (`market` = KOSPI/KOSDAQ, ...) are kept for compatibility (deprecated).\n- **Response time**: a stored copy returns in about a second. When no copy is stored yet for that day (or with `fresh=true`) the model writes one, which takes a few seconds (usually around 5) — for many symbols, call each once after the close and read stored copies afterwards.\n\n> Markets: KR\n\n> 🔒 **Paid tiers only** (Launch, Business, Scale, Enterprise; PoC included) — Free keys and accounts whose paid-tier term has ended receive 403 `PLAN_REQUIRED`; accounts whose PoC has ended receive 403 `POC_ENDED`.\n\n> 🌐 **Data coverage** — the account receives data only for the markets it has contracted. A market outside the contract (symbol or `market`) returns 403 `MARKET_NOT_ENTITLED` before any limit is counted; Japan (`JP`) and China (`CN`) return 400 `MARKET_NOT_AVAILABLE` (coming soon). For POST /query, authentication applies first; if every line is outside the contract, it returns 403 with zero per-minute, ordinary daily and AI calls. A storage failure or timeout during key, plan, company or market resolution returns HTTP 503 `UNAVAILABLE` with zero per-minute, ordinary daily and AI calls, without falling back to Free. Otherwise it returns HTTP 200 with per-line errors and counts as one ordinary call.\n\n> 🤖 **AI call** — for PoC, Launch, Business and Scale accounts this counts toward the daily AI-call quota (PoC-Launch default 20, KST; see Plans for other tiers) only when no stored copy exists and one is generated. Stored copies are not counted. Over the quota: 429 `AI_QUOTA_EXCEEDED`. Enterprise has no daily cap. A configured monthly cap returns 429 `AI_MONTHLY_QUOTA_EXCEEDED`.", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "symbol", "in": "path", "required": true, "description": "Korean 6-digit symbol code (e.g. 005930; a leading A is ignored)", "schema": { "type": "string", "pattern": "^A?\\d[0-9A-Z]{5}$", "example": "005930" } }, { "name": "market", "in": "query", "required": false, "description": "Optional — the market is determined by the symbol code (Korean 6-digit code or US ticker). If given, verifies that the symbol belongs to that market (otherwise 400 BAD_SYMBOL). Only KR symbols are supported (others return 400 UNSUPPORTED_MARKET).", "schema": { "type": "string", "enum": [ "KR", "US" ] } }, { "name": "date", "in": "query", "required": false, "description": "Briefing date YYYY-MM-DD (Korea time; today if omitted). Past dates return stored copies only (404 NO_HISTORY when none); future dates return 400 BAD_DATE", "schema": { "type": "string", "format": "date" } }, { "name": "fresh", "in": "query", "required": false, "description": "Request regeneration for today (ignored for past dates)", "schema": { "type": "string", "enum": [ "true", "false", "1", "0" ], "default": "false" } }, { "name": "tone", "in": "query", "required": false, "description": "formal selects formal Korean prose; omission preserves the original tone", "schema": { "type": "string", "enum": [ "formal" ] } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Quota-Period": { "$ref": "#/components/headers/X-Quota-Period" }, "X-Quota-Reset": { "$ref": "#/components/headers/X-Quota-Reset" }, "X-Markets": { "$ref": "#/components/headers/X-Markets" }, "X-Plan": { "$ref": "#/components/headers/X-Plan" }, "X-Plan-Tier": { "$ref": "#/components/headers/X-Plan-Tier" }, "X-Plan-Expires": { "$ref": "#/components/headers/X-Plan-Expires" }, "X-AI-Quota-Limit": { "$ref": "#/components/headers/X-AI-Quota-Limit" }, "X-AI-Quota-Remaining": { "$ref": "#/components/headers/X-AI-Quota-Remaining" }, "X-AI-Quota-Reset": { "$ref": "#/components/headers/X-AI-Quota-Reset" }, "X-AI-Quota-Monthly-Limit": { "$ref": "#/components/headers/X-AI-Quota-Monthly-Limit" }, "X-AI-Quota-Monthly-Remaining": { "$ref": "#/components/headers/X-AI-Quota-Monthly-Remaining" }, "X-AI-Quota-Monthly-Reset": { "$ref": "#/components/headers/X-AI-Quota-Monthly-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Briefing" }, "example": { "symbol": "005930", "name": "삼성전자", "market": "KOSPI", "date": "2026-10-20", "session": "closed", "price": { "current": 75400, "change": 800, "change_rate": 0.0107, "open": 74800, "high": 75900, "low": 74500, "prev_close": 74600, "as_of": "2026-10-20T06:30:00.000Z" }, "summary": "정규장이 끝났어요. 75,400원으로 마감해 전일보다 +1.07%예요. 메모리 가격 반등 기대가 이어졌어요.", "briefing": { "key_issues": [ "메모리 가격 반등 기대", "외국인 순매수" ], "body": "삼성전자는 …" }, "articles": [ { "id": "an_Q2xYz9", "title": "삼성전자, 3분기 메모리 출하 늘어", "summary": "삼성전자가 3분기 메모리 출하량이 전 분기보다 늘었다고 밝혔다.", "publisher": "연합뉴스", "published_at": "2026-10-20T05:12:00.000Z", "url": "https://api.chickstockfi.com/openapi/v1/articles/an_Q2xYz9/read" } ], "data": { "symbol": "005930", "name": "삼성전자", "market": "KR", "exchange": "KOSPI", "briefing_date": "2026-10-20", "date": "2026-10-20", "session": "closed", "price": { "current": 75400, "change": 800, "change_rate": 0.0107, "open": 74800, "high": 75900, "low": 74500, "prev_close": 74600, "as_of": "2026-10-20T06:30:00.000Z" }, "summary": "정규장이 끝났어요. 75,400원으로 마감해 전일보다 +1.07%예요. 메모리 가격 반등 기대가 이어졌어요.", "briefing": { "key_issues": [ "메모리 가격 반등 기대", "외국인 순매수" ], "body": "삼성전자는 …" }, "articles": [ { "id": "an_Q2xYz9", "title": "삼성전자, 3분기 메모리 출하 늘어", "summary": "삼성전자가 3분기 메모리 출하량이 전 분기보다 늘었다고 밝혔다.", "publisher": "연합뉴스", "published_at": "2026-10-20T05:12:00.000Z", "url": "https://api.chickstockfi.com/openapi/v1/articles/an_Q2xYz9/read" } ], "generated_at": "2026-10-20T07:10:00.000Z" }, "meta": { "source": "cache", "session": "closed", "generated_at": "2026-10-20T07:10:00.000Z", "briefing_date": "2026-10-20", "as_of": "2026-10-21T06:30:00.000Z", "legacy_top_level": true, "legacy_note": "최상위 칸은 예전 호환용입니다(deprecated). data를 읽으세요." } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequiredOrMarket" }, "404": { "description": "Unknown symbol or no stored copy (NO_HISTORY · NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "No stored briefing for 005930 on 2026-10-01. Past dates are not generated; omit date to get today's briefing.", "docs": "https://openapi.chickstockfi.com/docs" } } } } }, "429": { "$ref": "#/components/responses/RateLimitedOrAiQuota" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/rag": { "get": { "operationId": "askRag", "tags": [ "Q&A" ], "summary": "Grounded answer with citations", "x-summary-en": "Grounded answer with citations", "x-markets": [ "KR", "US" ], "description": "Returns a short answer grounded in official filings and structured financial data, with the list of sources. Figures come only from the sources. The market follows from the companies in the question.\n\n- **As-of time**: every source has `as_of` (prices: quote time; filed financials: filing date; other sources: collection date). Point-in-time values such as price, market cap and P/E are never taken from stored text; only values **read again while answering** (`docType: market`) are used — the same calculation as `data.valuation` in `/quotes/{symbol}` and `/companies/{symbol}/metrics`. Intraday quotes older than 15 minutes, or, when the market is closed, anything other than the latest regular-session close, are left out (a blank rather than a wrong value).\n- **Not provided**: target prices, investment opinions and broker earnings estimates (estimated P/E and EPS, forward P/E). If one slips into an answer it is regenerated once and otherwise the sentence is removed (`meta.guard`).\n- If the model cannot be called or fails, the response is 503 `UNAVAILABLE` (+ `Retry-After`). Responses usually take 3–5 seconds; the answer model is cut off at 20 seconds.\n\n> Markets: KR · US\n\n> 🔑 Works with Free trial keys as well as PoC and paid-tier keys. Accounts whose PoC has ended receive 403 `POC_ENDED`.\n\n> 🤖 **AI call** — for PoC, Launch, Business and Scale accounts this counts toward the daily AI-call quota (PoC-Launch default 20, KST; see Plans for other tiers) only when the answer model actually runs. Questions with no matching data, live-quote shortcut answers (no model) and model failures (503) are not counted. With no quota left the call returns 429 `AI_QUOTA_EXCEEDED` before any work. Enterprise has no daily cap. A configured monthly cap returns 429 `AI_MONTHLY_QUOTA_EXCEEDED`.", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Question", "schema": { "type": "string", "minLength": 2, "maxLength": 500, "example": "삼성전자 2025년 영업이익" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Quota-Period": { "$ref": "#/components/headers/X-Quota-Period" }, "X-Quota-Reset": { "$ref": "#/components/headers/X-Quota-Reset" }, "X-Markets": { "$ref": "#/components/headers/X-Markets" }, "X-Plan": { "$ref": "#/components/headers/X-Plan" }, "X-Plan-Tier": { "$ref": "#/components/headers/X-Plan-Tier" }, "X-Plan-Expires": { "$ref": "#/components/headers/X-Plan-Expires" }, "X-AI-Quota-Limit": { "$ref": "#/components/headers/X-AI-Quota-Limit" }, "X-AI-Quota-Remaining": { "$ref": "#/components/headers/X-AI-Quota-Remaining" }, "X-AI-Quota-Reset": { "$ref": "#/components/headers/X-AI-Quota-Reset" }, "X-AI-Quota-Monthly-Limit": { "$ref": "#/components/headers/X-AI-Quota-Monthly-Limit" }, "X-AI-Quota-Monthly-Remaining": { "$ref": "#/components/headers/X-AI-Quota-Monthly-Remaining" }, "X-AI-Quota-Monthly-Reset": { "$ref": "#/components/headers/X-AI-Quota-Monthly-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "answer": { "type": "string" }, "grounded": { "type": "boolean" }, "status": { "type": "string", "enum": [ "answered", "no_data", "entity_not_found" ] }, "sources": { "type": "array", "items": { "type": "object", "properties": { "n": { "type": "integer" }, "code": { "type": "string" }, "name": { "type": "string" }, "docType": { "type": "string", "description": "market (price and valuation read again while answering) · financial · financial_quarterly · business · etf_overview · etf_holdings, etc." }, "score": { "type": "number" }, "text": { "type": "string" }, "sourceUrl": { "type": "string" }, "report": { "type": "string" }, "rceptDate": { "type": "string" }, "as_of": { "type": [ "string", "null" ], "description": "As-of time of the source — prices: quote time; filed financials: filing date; others: collection date" } } } } } }, "meta": { "type": "object", "properties": { "sources": { "type": "integer" }, "as_of": { "type": "string", "format": "date-time" }, "model_invoked": { "type": "boolean", "description": "Whether the answer model ran (the PoC AI-call quota counts only then)" }, "numbers_verified": { "type": [ "boolean", "null" ], "description": "Whether every KRW 100-million / trillion amount in the answer appears in the sources" }, "guard": { "type": "string", "enum": [ "none", "regenerated", "redacted" ], "description": "Result of the post-check for items not provided (target price, investment opinion, estimated P/E or EPS)" }, "excluded": { "type": "array", "items": { "type": "string" } } } } } }, "example": { "data": { "answer": "삼성전자의 2025년 연결 영업이익은 32조 7,260억원입니다.[1]", "grounded": true, "status": "answered", "sources": [ { "n": 1, "code": "005930", "name": "삼성전자", "docType": "financial", "score": 1, "text": "삼성전자(005930) 재무 (2025 연간·연결, 2026-03-11 공시): 영업이익 32.7조원, 매출액 300.9조원", "sourceUrl": "https://dart.fss.or.kr/dsaf001/main.do?rcpNo=20260311001234", "report": "사업보고서 (2025.12)", "rceptDate": "2026-03-11", "as_of": "2026-03-11" } ] }, "meta": { "sources": 1, "as_of": "2026-10-21T06:30:00.000Z", "model_invoked": true, "numbers_verified": true, "guard": "none", "excluded": [ "target_price", "investment_opinion", "forward_estimates", "stored_price_snapshots" ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PocEnded" }, "429": { "$ref": "#/components/responses/RateLimitedOrAiQuota" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/research/search": { "get": { "operationId": "searchResearch", "tags": [ "Discontinued" ], "summary": "Broker research search (deprecated)", "x-summary-en": "Broker research search (deprecated)", "x-markets": [ "KR" ], "x-market-scoped": true, "description": "**Discontinued (deprecated, 2026-10-21).** Available only to keys under existing contracts; other keys get 403 `FEATURE_DISABLED`. Analyst names and report file links are not included. The cursor convention does not apply.\n\n> Markets: KR\n\n> 🔒 **Paid tiers only** (Launch, Business, Scale, Enterprise; PoC included) — Free keys and accounts whose paid-tier term has ended receive 403 `PLAN_REQUIRED`; accounts whose PoC has ended receive 403 `POC_ENDED`.\n\n> 🌐 **Data coverage** — the account receives data only for the markets it has contracted. A market outside the contract (symbol or `market`) returns 403 `MARKET_NOT_ENTITLED` before any limit is counted; Japan (`JP`) and China (`CN`) return 400 `MARKET_NOT_AVAILABLE` (coming soon). For POST /query, authentication applies first; if every line is outside the contract, it returns 403 with zero per-minute, ordinary daily and AI calls. A storage failure or timeout during key, plan, company or market resolution returns HTTP 503 `UNAVAILABLE` with zero per-minute, ordinary daily and AI calls, without falling back to Free. Otherwise it returns HTTP 200 with per-line errors and counts as one ordinary call.", "deprecated": true, "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Search query (company name, title)", "schema": { "type": "string", "example": "삼성전자" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items (1–50, default 20)", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Quota-Period": { "$ref": "#/components/headers/X-Quota-Period" }, "X-Quota-Reset": { "$ref": "#/components/headers/X-Quota-Reset" }, "X-Markets": { "$ref": "#/components/headers/X-Markets" }, "X-Plan": { "$ref": "#/components/headers/X-Plan" }, "X-Plan-Tier": { "$ref": "#/components/headers/X-Plan-Tier" }, "X-Plan-Expires": { "$ref": "#/components/headers/X-Plan-Expires" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ResearchReport" } }, "meta": { "type": "object", "properties": { "count": { "type": "integer" }, "query": { "type": "string" }, "deprecated": { "type": "boolean" }, "as_of": { "type": "string", "format": "date-time" } } } }, "required": [ "data", "meta" ] }, "example": { "data": [ { "id": "rsh_81234", "title": "3Q26 Preview", "firm": "○○증권", "date": "2026-10-14", "opinion": "Buy", "targetPrice": 95000 } ], "meta": { "count": 1, "query": "삼성전자", "deprecated": true, "as_of": "2026-10-21T06:30:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequiredOrFeatureDisabled" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/research/{symbol}": { "get": { "operationId": "listResearch", "tags": [ "Discontinued" ], "summary": "Broker research by symbol (deprecated)", "x-summary-en": "Broker research by symbol (deprecated)", "x-markets": [ "KR" ], "x-market-scoped": true, "description": "**Discontinued (deprecated, 2026-10-21).** Available only to keys under existing contracts; other keys get 403 `FEATURE_DISABLED`. Analyst names and report file links are not included. The cursor convention does not apply.\n\n> Markets: KR\n\n> 🔒 **Paid tiers only** (Launch, Business, Scale, Enterprise; PoC included) — Free keys and accounts whose paid-tier term has ended receive 403 `PLAN_REQUIRED`; accounts whose PoC has ended receive 403 `POC_ENDED`.\n\n> 🌐 **Data coverage** — the account receives data only for the markets it has contracted. A market outside the contract (symbol or `market`) returns 403 `MARKET_NOT_ENTITLED` before any limit is counted; Japan (`JP`) and China (`CN`) return 400 `MARKET_NOT_AVAILABLE` (coming soon). For POST /query, authentication applies first; if every line is outside the contract, it returns 403 with zero per-minute, ordinary daily and AI calls. A storage failure or timeout during key, plan, company or market resolution returns HTTP 503 `UNAVAILABLE` with zero per-minute, ordinary daily and AI calls, without falling back to Free. Otherwise it returns HTTP 200 with per-line errors and counts as one ordinary call.", "deprecated": true, "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "symbol", "in": "path", "required": true, "description": "Korean 6-digit symbol code (e.g. 005930; a leading A is ignored)", "schema": { "type": "string", "pattern": "^A?\\d[0-9A-Z]{5}$", "example": "005930" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items (1–50, default 20)", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Quota-Period": { "$ref": "#/components/headers/X-Quota-Period" }, "X-Quota-Reset": { "$ref": "#/components/headers/X-Quota-Reset" }, "X-Markets": { "$ref": "#/components/headers/X-Markets" }, "X-Plan": { "$ref": "#/components/headers/X-Plan" }, "X-Plan-Tier": { "$ref": "#/components/headers/X-Plan-Tier" }, "X-Plan-Expires": { "$ref": "#/components/headers/X-Plan-Expires" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ResearchReport" } }, "meta": { "type": "object", "properties": { "count": { "type": "integer" }, "symbol": { "type": "string" }, "deprecated": { "type": "boolean" }, "as_of": { "type": "string", "format": "date-time" } } } }, "required": [ "data", "meta" ] }, "example": { "data": [ { "id": "rsh_81234", "title": "3Q26 Preview", "firm": "○○증권", "date": "2026-10-14", "opinion": "Buy", "targetPrice": 95000 } ], "meta": { "count": 1, "symbol": "005930", "deprecated": true, "as_of": "2026-10-21T06:30:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanRequiredOrFeatureDisabled" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/Internal" } } } } }, "webhooks": { "us_filing.detected": { "post": { "operationId": "onUsFilingDetected", "tags": [ "Webhooks" ], "summary": "us_filing.detected", "description": "A SEC filing appeared in the feed (8-K, 6-K, 10-Q, 10-K, 20-F, 40-F, amendments included). `data.analysis.status` is the state at send time.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "2xx" } } } }, "us_filing.analysis_published": { "post": { "operationId": "onUsFilingAnalysisPublished", "tags": [ "Webhooks" ], "summary": "us_filing.analysis_published", "description": "The analysis of a filing was published (filings dated within the last 7 days). `data.analysis` carries the headline, publication time and latency. A corrected analysis published again arrives once more as a new version (`data.publication.revision`, `replaces`).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "2xx" } } } }, "us_filing.analysis_revoked": { "post": { "operationId": "onUsFilingAnalysisRevoked", "tags": [ "Webhooks" ], "summary": "us_filing.analysis_revoked", "description": "An analysis announced by webhook was withdrawn — once per version (last 30 days). `data.revocation` carries the withdrawn version id, its publication and withdrawal times, and `replacement` when a new version is already public. `data.analysis` is the state at send time.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRevokedEvent" } } } }, "responses": { "200": { "description": "2xx" } } } }, "us_earnings.figures": { "post": { "operationId": "onUsEarningsFigures", "tags": [ "Webhooks" ], "summary": "us_earnings.figures", "description": "Sent when verified figures of a US earnings release (8-K Item 2.02) first exist (filings dated within the last two days). `data` has the same shape as `GET /us-earnings/{id}`, comparison to the pre-release consensus included. Sent again when a new reading changes figure or outlook values (`data.revision.number`, `changed`).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEarningsEvent" } } } }, "responses": { "200": { "description": "2xx" } } } } } }