{ "openapi": "3.1.0", "info": { "title": "Phoenix AI PRO API", "version": "1.0.0", "termsOfService": "https://www.chickstockfi.com/pro/terms", "contact": { "name": "Phoenix AI PRO 문의", "email": "help@alpsoft.io", "url": "https://openapi.chickstockfi.com/docs/support" }, "description": "Phoenix AI PRO API는 공식 공시(DART·SEC)와 재무제표로 만든 데이터, 그리고 Phoenix AI PRO 대화형 리서치를 프로그램에서 쓰는 유료 API입니다. 기업용 Data API와 키·플랜·한도를 따로 운영합니다.\n\n**베이스 URL** — `https://api.chickstockfi.com/openapi/pro/v1` (같은 API를 `https://www.chickstockfi.com/openapi/pro/v1`로도 호출할 수 있습니다)\n\n**인증** — PRO API 키(`ck_pers_…`)를 `Authorization: Bearer ` 또는 `X-API-Key: ` 헤더로 보내세요. PRO 플랜이 있는 계정만 [개발자 콘솔](https://openapi.chickstockfi.com/login)에서 키를 만들 수 있습니다. Data API 키(`ck_live_…`)는 여기서 `WRONG_KEY_SCOPE`(401)를 받습니다. → [인증과 API 키](https://openapi.chickstockfi.com/docs/authentication)\n\n**플랜(가격 협의)** — Data(기본 하루 1,000회 · 초당 2회 · AI 공시 요약 즉석 생성 하루 50건) · Ask(대화형 질문 월 300회 포함) · Bundle(둘 다). 가격은 도입 문의(help@alpsoft.io)로 협의합니다. 하루 한도는 한국시간 0시에 다시 열립니다. → [호출 한도와 쿼터](https://openapi.chickstockfi.com/docs/rate-limits)\n\n**응답** — 데이터 응답은 모두 `{ data, as_of, sources, disclaimer, meta }` 모양입니다. `sources`에는 DART · SEC 원문과 Phoenix AI 페이지 링크만 담깁니다. 시세와 시세에서 나온 값(현재가 · 등락 · 시가총액 · PER · PBR · PSR · 배당수익률 · 이동평균 · RSI · 52주)을 포함합니다. 개별 증권사 추정치 · 선행 PER · 목표가 · 리포트 본문 · 애널리스트 이름, 경제지표 예상치, 뉴스 본문 · 기사 목록은 제공하지 않습니다. 컨센서스는 실적 차이표(`/earnings/{symbol}/variance`)의 발표 전 종합값만 제공합니다.\n\n**헤더** — `X-RateLimit-Limit/Remaining`(초당) · `X-Quota-Limit/Remaining/Reset/Period`(하루, 한국시간) · `X-Budget-Remaining`(이번 달 AI 비용 남은 USD) · `X-Ask-Remaining`(오늘 남은 질문 수).\n\n**MCP** — 원격 MCP 서버 `https://www.chickstockfi.com/openapi/pro/v1/mcp`로 Claude · ChatGPT · Cursor 같은 AI 도구에서 같은 키 · 플랜 · 한도로 씁니다. 인증은 PRO API 키 또는 OAuth 2.1(PKCE · 동적 클라이언트 등록). → [MCP 연결](https://openapi.chickstockfi.com/docs/mcp)\n\n**시작하기** — [빠른 시작](https://openapi.chickstockfi.com/docs/quickstart) · [오류 코드](https://openapi.chickstockfi.com/docs/errors) · [데이터 규약](https://openapi.chickstockfi.com/docs/conventions) · [변경 이력](https://openapi.chickstockfi.com/docs/changelog)\n\n**OpenAPI 명세** — 이 명세 JSON(https://openapi.chickstockfi.com/openapi-pro.json)을 openapi-generator · oapi-codegen 같은 OpenAPI 도구에 넣어 원하는 언어의 클라이언트를 만들 수 있습니다.\n" }, "servers": [ { "url": "https://api.chickstockfi.com/openapi/pro/v1", "description": "Production" }, { "url": "https://www.chickstockfi.com/openapi/pro/v1", "description": "Production (www)" } ], "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "PRO API 키(ck_pers_…). X-API-Key 헤더도 받습니다. /mcp는 OAuth 접근 토큰(ck_mcp_at_…)도 받습니다." } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "docs": { "type": "string" } } } } }, "Source": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string", "format": "uri" } } }, "Envelope": { "type": "object", "required": [ "data", "as_of", "sources", "disclaimer" ], "properties": { "data": {}, "as_of": { "type": "string", "format": "date-time" }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/Source" } }, "disclaimer": { "type": "string" }, "meta": { "type": "object" } } }, "AskAccepted": { "type": "object", "properties": { "job_id": { "type": "string", "format": "uuid" }, "status": { "const": "running" }, "overage": { "type": "boolean", "description": "이번 달 포함 횟수를 넘긴 질문(초과 1회 단가 적용 대상)" }, "poll": { "type": "string" } } }, "AskResult": { "type": "object", "properties": { "job_id": { "type": "string", "format": "uuid" }, "status": { "enum": [ "running", "done", "failed" ] }, "thread_id": { "type": [ "integer", "null" ] }, "message_id": { "type": [ "integer", "null" ] }, "question": { "type": [ "string", "null" ] }, "overage": { "type": "boolean" }, "error": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "as_of": { "type": [ "string", "null" ] }, "answer": { "type": [ "object", "null" ], "properties": { "markdown": { "type": "string" }, "table": { "type": [ "object", "null" ], "properties": { "title": { "type": "string" }, "unit": { "type": [ "string", "null" ] }, "columns": { "type": "array", "items": { "type": "string" } }, "rows": { "type": "array", "items": { "type": "array" } }, "note": { "type": [ "string", "null" ] } } }, "sources": { "type": "array", "items": { "type": "object", "properties": { "n": { "type": "integer" }, "tag": { "type": "string" }, "name": { "type": "string" }, "title": { "type": "string" }, "url": { "type": [ "string", "null" ] }, "date": { "type": [ "string", "null" ] }, "cited": { "type": "boolean" } } } }, "calc": { "type": "array", "items": { "type": "string" } }, "verification": { "type": "object", "properties": { "claims": { "type": "integer" }, "unverified": { "type": "array", "items": { "type": "integer" } } } }, "symbols": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "market": { "enum": [ "kr", "us" ] } } } }, "not_covered": { "type": [ "string", "null" ] }, "charts": { "type": "array", "description": "가격 차트(일봉·교차·이벤트)", "items": { "type": "object" } }, "short": { "type": [ "object", "null" ], "description": "공매도 카드" }, "fin_charts": { "type": "array", "description": "재무 차트 명세(미국 SEC 분기 원장 · 국내 DART 정기보고서 분기 값·잠정실적 — 기간·계열·표·각주·출처, 최대 6개)", "items": { "type": "object" } }, "revenue_mix": { "type": "array", "description": "매출 구성 표(국내 DART 사업보고서 · 미국 SEC 10-K — 회사 × 축(사업부문·제품·서비스·지역)마다 항목·비중(%)·금액, 각주에 기준 기간·분모·원천, 미국은 최근 분기 표 포함, 최대 12개)", "items": { "type": "object" } } } }, "disclaimer": { "type": "string" } } } } }, "paths": { "/": { "get": { "summary": "서비스 설명(키 없음)", "tags": [ "meta" ], "responses": { "200": { "description": "설명", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/openapi.json": { "get": { "summary": "이 명세(키 없음)", "tags": [ "meta" ], "responses": { "200": { "description": "OpenAPI JSON", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/me": { "get": { "summary": "내 플랜·오늘/이번 달 사용량(하루 호출 수에 넣지 않음)", "tags": [ "account" ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "플랜·사용량", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "키 없음·형식 오류(UNAUTHORIZED)·Data API 키(ck_live_) 사용(WRONG_KEY_SCOPE)·폐기된 키(INVALID_KEY)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "플랜 없음(PLAN_REQUIRED)·만료(PLAN_EXPIRED)·정지(PLAN_INACTIVE)·시작 전(PLAN_NOT_STARTED)·상품 없음(PRODUCT_REQUIRED)·PoC 기간 끝남(POC_ENDED)·계약 밖 시장(MARKET_NOT_ENTITLED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "초당 한도(RATE_LIMITED)·하루 호출 한도(DAILY_QUOTA_EXCEEDED). Retry-After(초) 포함", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/disclosures": { "get": { "summary": "국내 주요 공시 목록(분류된 DART 공시)", "tags": [ "data" ], "security": [ { "bearer": [] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "시작일(기본 30일 전)", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "끝일", "schema": { "type": "string", "format": "date" } }, { "name": "symbol", "in": "query", "required": false, "description": "6자리 종목코드", "schema": { "type": "string" } }, { "name": "group", "in": "query", "required": false, "description": "공시 묶음", "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "description": "공시 유형", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "최대 건수", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "건너뛸 건수", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "성공", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "잘못된 입력(BAD_REQUEST·BAD_SYMBOL)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "키 없음·형식 오류(UNAUTHORIZED)·Data API 키(ck_live_) 사용(WRONG_KEY_SCOPE)·폐기된 키(INVALID_KEY)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "플랜 없음(PLAN_REQUIRED)·만료(PLAN_EXPIRED)·정지(PLAN_INACTIVE)·시작 전(PLAN_NOT_STARTED)·상품 없음(PRODUCT_REQUIRED)·PoC 기간 끝남(POC_ENDED)·계약 밖 시장(MARKET_NOT_ENTITLED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "없음(NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "초당 한도(RATE_LIMITED)·하루 호출 한도(DAILY_QUOTA_EXCEEDED). Retry-After(초) 포함", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/disclosures/{rcept_no}": { "get": { "summary": "공시 1건(메타·저장된 AI 요약·원문 텍스트 선택)", "tags": [ "data" ], "security": [ { "bearer": [] } ], "parameters": [ { "name": "rcept_no", "in": "path", "required": true, "description": "DART 접수번호", "schema": { "type": "string", "pattern": "^\\d{14}$" } }, { "name": "include_text", "in": "query", "required": false, "description": "원문 텍스트(최대 2만 자) 포함", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "성공", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "잘못된 입력(BAD_REQUEST·BAD_SYMBOL)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "키 없음·형식 오류(UNAUTHORIZED)·Data API 키(ck_live_) 사용(WRONG_KEY_SCOPE)·폐기된 키(INVALID_KEY)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "플랜 없음(PLAN_REQUIRED)·만료(PLAN_EXPIRED)·정지(PLAN_INACTIVE)·시작 전(PLAN_NOT_STARTED)·상품 없음(PRODUCT_REQUIRED)·PoC 기간 끝남(POC_ENDED)·계약 밖 시장(MARKET_NOT_ENTITLED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "없음(NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "초당 한도(RATE_LIMITED)·하루 호출 한도(DAILY_QUOTA_EXCEEDED). Retry-After(초) 포함", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/disclosures/{rcept_no}/summary": { "get": { "summary": "AI 공시 요약 — 저장본은 무료, 없으면 즉석 생성(하루 생성 한도·월 비용 상한 포함)", "tags": [ "data" ], "security": [ { "bearer": [] } ], "parameters": [ { "name": "rcept_no", "in": "path", "required": true, "description": "DART 접수번호", "schema": { "type": "string", "pattern": "^\\d{14}$" } }, { "name": "generate", "in": "query", "required": false, "description": "false면 저장본만", "schema": { "type": "boolean", "default": true } } ], "responses": { "200": { "description": "성공", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "잘못된 입력(BAD_REQUEST·BAD_SYMBOL)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "키 없음·형식 오류(UNAUTHORIZED)·Data API 키(ck_live_) 사용(WRONG_KEY_SCOPE)·폐기된 키(INVALID_KEY)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "이번 달 AI 비용 상한(BUDGET_EXCEEDED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "플랜 없음(PLAN_REQUIRED)·만료(PLAN_EXPIRED)·정지(PLAN_INACTIVE)·시작 전(PLAN_NOT_STARTED)·상품 없음(PRODUCT_REQUIRED)·PoC 기간 끝남(POC_ENDED)·계약 밖 시장(MARKET_NOT_ENTITLED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "없음(NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "초당 한도(RATE_LIMITED)·하루 호출 한도(DAILY_QUOTA_EXCEEDED)·계정 월 AI 호출 한도(AI_MONTHLY_QUOTA_EXCEEDED)·계정 하루 AI 호출 한도(AI_QUOTA_EXCEEDED, 등급별; PoC-Launch 기본 20회). Retry-After(초) 포함", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "지금 만들 수 없음(UNAVAILABLE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/financials/{symbol}": { "get": { "summary": "재무제표 계정(국내 DART·미국 SEC, 최대 60행). 국내 종목에서 순이익·EPS 계열을 조회하면(또는 계정 생략) net_income_split을 함께 줍니다 — 기간마다 controlling_net_income(지배주주 순이익)·total_net_income(전체 연결 순이익)·nci_net_income(비지배지분 몫)·nci_share_pct(전체 대비 %, 부호가 다르면 null), 억원·연결 기준", "tags": [ "data" ], "security": [ { "bearer": [] } ], "parameters": [ { "name": "symbol", "in": "path", "required": true, "description": "국내 6자리 종목코드 또는 미국 티커", "schema": { "type": "string", "example": "005930" } }, { "name": "account", "in": "query", "required": false, "description": "계정(예: 매출액, 영업이익)", "schema": { "type": "string" } }, { "name": "period", "in": "query", "required": false, "description": "기간(예: 2025, 2026Q1)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "성공", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "잘못된 입력(BAD_REQUEST·BAD_SYMBOL)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "키 없음·형식 오류(UNAUTHORIZED)·Data API 키(ck_live_) 사용(WRONG_KEY_SCOPE)·폐기된 키(INVALID_KEY)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "플랜 없음(PLAN_REQUIRED)·만료(PLAN_EXPIRED)·정지(PLAN_INACTIVE)·시작 전(PLAN_NOT_STARTED)·상품 없음(PRODUCT_REQUIRED)·PoC 기간 끝남(POC_ENDED)·계약 밖 시장(MARKET_NOT_ENTITLED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "없음(NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "초당 한도(RATE_LIMITED)·하루 호출 한도(DAILY_QUOTA_EXCEEDED). Retry-After(초) 포함", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/earnings/{symbol}/variance": { "get": { "summary": "실적 차이표 — 한 회계 기간의 매출·영업이익·순이익·EPS 실제값(국내 DART 정기보고서·잠정실적 공시 / 미국 SEC 10-Q·10-K, 정기보고서 전에는 8-K 실적 발표 표의 매출·GAAP 희석 EPS를 잠정으로 — 접수번호·원문 링크)과 회사 가이던스(공시한 전망 숫자)·가이던스 대비(%). 발표 전 시장 컨센서스(증권사 추정 종합값, 발표일 이전 마지막 관측)와 서프라이즈(%)도 함께 줍니다. 기준(통화·분기/누적·연결/별도·지배/전체·EPS 기준)이 다르면 비교하지 않고 reasons에 사유", "tags": [ "data" ], "security": [ { "bearer": [] } ], "parameters": [ { "name": "symbol", "in": "path", "required": true, "description": "국내 6자리 종목코드 또는 미국 티커", "schema": { "type": "string", "example": "005930" } }, { "name": "period", "in": "query", "required": false, "description": "회계 기간 — \"FY2027Q2\", \"2026 3분기\", \"2026\"(연간), \"지난 분기\". 없으면 가장 최근 발표 기간", "schema": { "type": "string", "example": "2026 3분기" } } ], "responses": { "200": { "description": "성공", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "잘못된 입력(BAD_REQUEST·BAD_SYMBOL)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "키 없음·형식 오류(UNAUTHORIZED)·Data API 키(ck_live_) 사용(WRONG_KEY_SCOPE)·폐기된 키(INVALID_KEY)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "플랜 없음(PLAN_REQUIRED)·만료(PLAN_EXPIRED)·정지(PLAN_INACTIVE)·시작 전(PLAN_NOT_STARTED)·상품 없음(PRODUCT_REQUIRED)·PoC 기간 끝남(POC_ENDED)·계약 밖 시장(MARKET_NOT_ENTITLED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "없음(NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "초당 한도(RATE_LIMITED)·하루 호출 한도(DAILY_QUOTA_EXCEEDED). Retry-After(초) 포함", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/metrics/{symbol}": { "get": { "summary": "재무 비율(성장·수익성·효율·안정성·현금 품질)과 밸류에이션(시가총액·PER·PBR·PSR·EPS·BPS·ROE·배당, 시세 기준 as_of). 국내 EPS·PER·ROE는 지배주주 순이익 기준이고 valuation.eps_basis(controlling·total)·eps_shares(나눈 상장주식수)가 그 근거입니다. valuation은 기업 데이터 API·Phoenix AI 종목 화면과 같은 계산(같은 함수)이며 기준 칸 price·price_as_of(쓴 주가·날짜)·eps_period(순이익 기간)·shares_basis(common_listed = 상장 보통주, 우선주는 issuer_common_listed)·per_basis·market_cap_raw(원)·dividend.dps_basis(annual_current_share)·fiscal_year를 줍니다. 우선주는 EPS·BPS = 발행사 보통주 기준, PER = 우선주 주가 ÷ 그 EPS입니다. ratios.unit_scale(원래 금액 = 값 × 배율)·op_cf_raw(반올림 전 원·달러). 국내는 net_income_split(최근 연간·분기의 지배주주·전체 순이익·비지배지분 몫)도 줍니다", "tags": [ "data" ], "security": [ { "bearer": [] } ], "parameters": [ { "name": "symbol", "in": "path", "required": true, "description": "국내 6자리 종목코드 또는 미국 티커", "schema": { "type": "string", "example": "005930" } } ], "responses": { "200": { "description": "성공", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "잘못된 입력(BAD_REQUEST·BAD_SYMBOL)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "키 없음·형식 오류(UNAUTHORIZED)·Data API 키(ck_live_) 사용(WRONG_KEY_SCOPE)·폐기된 키(INVALID_KEY)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "플랜 없음(PLAN_REQUIRED)·만료(PLAN_EXPIRED)·정지(PLAN_INACTIVE)·시작 전(PLAN_NOT_STARTED)·상품 없음(PRODUCT_REQUIRED)·PoC 기간 끝남(POC_ENDED)·계약 밖 시장(MARKET_NOT_ENTITLED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "없음(NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "초당 한도(RATE_LIMITED)·하루 호출 한도(DAILY_QUOTA_EXCEEDED). Retry-After(초) 포함", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/quotes": { "get": { "summary": "여러 종목 지금 시세(국내·미국, 최대 20개) — 정규장 현재가/종가와 프리·애프터·데이마켓 체결가, 세션 표시", "tags": [ "data" ], "security": [ { "bearer": [] } ], "parameters": [ { "name": "symbols", "in": "query", "required": true, "description": "쉼표로 구분한 종목코드·티커", "schema": { "type": "string", "example": "005930,AAPL" } } ], "responses": { "200": { "description": "성공", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "잘못된 입력(BAD_REQUEST·BAD_SYMBOL)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "키 없음·형식 오류(UNAUTHORIZED)·Data API 키(ck_live_) 사용(WRONG_KEY_SCOPE)·폐기된 키(INVALID_KEY)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "플랜 없음(PLAN_REQUIRED)·만료(PLAN_EXPIRED)·정지(PLAN_INACTIVE)·시작 전(PLAN_NOT_STARTED)·상품 없음(PRODUCT_REQUIRED)·PoC 기간 끝남(POC_ENDED)·계약 밖 시장(MARKET_NOT_ENTITLED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "없음(NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "초당 한도(RATE_LIMITED)·하루 호출 한도(DAILY_QUOTA_EXCEEDED). Retry-After(초) 포함", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/quotes/{symbol}": { "get": { "summary": "한 종목 지금 시세(정규장 현재가/종가·확장 세션 체결가·세션·as_of)", "tags": [ "data" ], "security": [ { "bearer": [] } ], "parameters": [ { "name": "symbol", "in": "path", "required": true, "description": "국내 6자리 종목코드 또는 미국 티커", "schema": { "type": "string", "example": "005930" } } ], "responses": { "200": { "description": "성공", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "잘못된 입력(BAD_REQUEST·BAD_SYMBOL)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "키 없음·형식 오류(UNAUTHORIZED)·Data API 키(ck_live_) 사용(WRONG_KEY_SCOPE)·폐기된 키(INVALID_KEY)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "플랜 없음(PLAN_REQUIRED)·만료(PLAN_EXPIRED)·정지(PLAN_INACTIVE)·시작 전(PLAN_NOT_STARTED)·상품 없음(PRODUCT_REQUIRED)·PoC 기간 끝남(POC_ENDED)·계약 밖 시장(MARKET_NOT_ENTITLED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "없음(NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "초당 한도(RATE_LIMITED)·하루 호출 한도(DAILY_QUOTA_EXCEEDED). Retry-After(초) 포함", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/screener/{preset}": { "get": { "summary": "스크리너 프리셋 결과(재무·시세·이동평균·기술 지표 칸)", "tags": [ "data" ], "security": [ { "bearer": [] } ], "parameters": [ { "name": "preset", "in": "path", "required": true, "description": "프리셋", "schema": { "enum": [ "value-growth", "cheap-value", "quality-growth", "high-roe-cheap", "cash-cow", "steady-dividend", "golden-cross", "ma-turn", "rebound", "momentum" ] } }, { "name": "market", "in": "query", "required": false, "description": "시장 — 생략하면 kr(한 시장만 계약한 계정은 그 시장)", "schema": { "enum": [ "kr", "us" ] } }, { "name": "limit", "in": "query", "required": false, "description": "최대 건수", "schema": { "type": "integer", "minimum": 1, "maximum": 300, "default": 100 } } ], "responses": { "200": { "description": "성공", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "잘못된 입력(BAD_REQUEST·BAD_SYMBOL)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "키 없음·형식 오류(UNAUTHORIZED)·Data API 키(ck_live_) 사용(WRONG_KEY_SCOPE)·폐기된 키(INVALID_KEY)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "플랜 없음(PLAN_REQUIRED)·만료(PLAN_EXPIRED)·정지(PLAN_INACTIVE)·시작 전(PLAN_NOT_STARTED)·상품 없음(PRODUCT_REQUIRED)·PoC 기간 끝남(POC_ENDED)·계약 밖 시장(MARKET_NOT_ENTITLED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "없음(NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "초당 한도(RATE_LIMITED)·하루 호출 한도(DAILY_QUOTA_EXCEEDED). Retry-After(초) 포함", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "스크리너 데이터 준비 안 됨(UNAVAILABLE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/sectors": { "get": { "summary": "업종 목록과 종목 수", "tags": [ "data" ], "security": [ { "bearer": [] } ], "parameters": [ { "name": "market", "in": "query", "required": false, "description": "시장 — 생략하면 kr(한 시장만 계약한 계정은 그 시장)", "schema": { "enum": [ "kr", "us" ] } } ], "responses": { "200": { "description": "성공", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "잘못된 입력(BAD_REQUEST·BAD_SYMBOL)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "키 없음·형식 오류(UNAUTHORIZED)·Data API 키(ck_live_) 사용(WRONG_KEY_SCOPE)·폐기된 키(INVALID_KEY)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "플랜 없음(PLAN_REQUIRED)·만료(PLAN_EXPIRED)·정지(PLAN_INACTIVE)·시작 전(PLAN_NOT_STARTED)·상품 없음(PRODUCT_REQUIRED)·PoC 기간 끝남(POC_ENDED)·계약 밖 시장(MARKET_NOT_ENTITLED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "없음(NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "초당 한도(RATE_LIMITED)·하루 호출 한도(DAILY_QUOTA_EXCEEDED). Retry-After(초) 포함", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/sectors/ranking": { "get": { "summary": "업종·기업 재무 순위(최신 연간, 국내)", "tags": [ "data" ], "security": [ { "bearer": [] } ], "parameters": [ { "name": "account", "in": "query", "required": false, "description": "계정", "schema": { "enum": [ "매출액", "영업이익", "당기순이익", "자산총계", "자본총계", "부채총계", "영업활동현금흐름", "연구개발비" ], "default": "매출액" } }, { "name": "sector", "in": "query", "required": false, "description": "업종(없으면 업종별 합계 순위)", "schema": { "type": "string" } }, { "name": "order", "in": "query", "required": false, "description": "정렬", "schema": { "enum": [ "asc", "desc" ], "default": "desc" } }, { "name": "limit", "in": "query", "required": false, "description": "최대 건수", "schema": { "type": "integer", "minimum": 1, "maximum": 40, "default": 20 } } ], "responses": { "200": { "description": "성공", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "잘못된 입력(BAD_REQUEST·BAD_SYMBOL)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "키 없음·형식 오류(UNAUTHORIZED)·Data API 키(ck_live_) 사용(WRONG_KEY_SCOPE)·폐기된 키(INVALID_KEY)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "플랜 없음(PLAN_REQUIRED)·만료(PLAN_EXPIRED)·정지(PLAN_INACTIVE)·시작 전(PLAN_NOT_STARTED)·상품 없음(PRODUCT_REQUIRED)·PoC 기간 끝남(POC_ENDED)·계약 밖 시장(MARKET_NOT_ENTITLED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "없음(NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "초당 한도(RATE_LIMITED)·하루 호출 한도(DAILY_QUOTA_EXCEEDED). Retry-After(초) 포함", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/events": { "get": { "summary": "일정 — 배당·IR·공모(청약)·신규 상장·한국 경제 일정(예상치 없음)", "tags": [ "data" ], "security": [ { "bearer": [] } ], "parameters": [ { "name": "type", "in": "query", "required": true, "description": "종류", "schema": { "enum": [ "dividends", "ir", "ipo_offerings", "ipo_listings", "economic" ] } }, { "name": "from", "in": "query", "required": false, "description": "시작일", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "끝일", "schema": { "type": "string", "format": "date" } }, { "name": "symbol", "in": "query", "required": false, "description": "종목", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "최대 건수", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "성공", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "잘못된 입력(BAD_REQUEST·BAD_SYMBOL)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "키 없음·형식 오류(UNAUTHORIZED)·Data API 키(ck_live_) 사용(WRONG_KEY_SCOPE)·폐기된 키(INVALID_KEY)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "플랜 없음(PLAN_REQUIRED)·만료(PLAN_EXPIRED)·정지(PLAN_INACTIVE)·시작 전(PLAN_NOT_STARTED)·상품 없음(PRODUCT_REQUIRED)·PoC 기간 끝남(POC_ENDED)·계약 밖 시장(MARKET_NOT_ENTITLED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "없음(NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "초당 한도(RATE_LIMITED)·하루 호출 한도(DAILY_QUOTA_EXCEEDED). Retry-After(초) 포함", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/briefs/{symbol}": { "get": { "summary": "국내 종목 데일리 브리프(세션 첫 문장·가격·요약·핵심 이슈·본문·값 타일, 기사 목록 제외)", "tags": [ "data" ], "security": [ { "bearer": [] } ], "parameters": [ { "name": "symbol", "in": "path", "required": true, "description": "국내 6자리 종목코드", "schema": { "type": "string", "example": "005930" } }, { "name": "date", "in": "query", "required": false, "description": "기준일(없으면 최근 14일 안 최신)", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "성공", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "잘못된 입력(BAD_REQUEST·BAD_SYMBOL)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "키 없음·형식 오류(UNAUTHORIZED)·Data API 키(ck_live_) 사용(WRONG_KEY_SCOPE)·폐기된 키(INVALID_KEY)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "플랜 없음(PLAN_REQUIRED)·만료(PLAN_EXPIRED)·정지(PLAN_INACTIVE)·시작 전(PLAN_NOT_STARTED)·상품 없음(PRODUCT_REQUIRED)·PoC 기간 끝남(POC_ENDED)·계약 밖 시장(MARKET_NOT_ENTITLED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "없음(NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "초당 한도(RATE_LIMITED)·하루 호출 한도(DAILY_QUOTA_EXCEEDED). Retry-After(초) 포함", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/reports": { "get": { "summary": "마감 리포트 목록", "tags": [ "data" ], "security": [ { "bearer": [] } ], "parameters": [ { "name": "market", "in": "query", "required": false, "description": "시장 — 생략하면 kr(한 시장만 계약한 계정은 그 시장)", "schema": { "enum": [ "kr", "us" ] } }, { "name": "limit", "in": "query", "required": false, "description": "최대 건수", "schema": { "type": "integer", "minimum": 1, "maximum": 60, "default": 20 } } ], "responses": { "200": { "description": "성공", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "잘못된 입력(BAD_REQUEST·BAD_SYMBOL)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "키 없음·형식 오류(UNAUTHORIZED)·Data API 키(ck_live_) 사용(WRONG_KEY_SCOPE)·폐기된 키(INVALID_KEY)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "플랜 없음(PLAN_REQUIRED)·만료(PLAN_EXPIRED)·정지(PLAN_INACTIVE)·시작 전(PLAN_NOT_STARTED)·상품 없음(PRODUCT_REQUIRED)·PoC 기간 끝남(POC_ENDED)·계약 밖 시장(MARKET_NOT_ENTITLED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "없음(NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "초당 한도(RATE_LIMITED)·하루 호출 한도(DAILY_QUOTA_EXCEEDED). Retry-After(초) 포함", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/reports/{market}/{date}": { "get": { "summary": "마감 리포트 본문(지수 등락 칩·좌표 포함)", "tags": [ "data" ], "security": [ { "bearer": [] } ], "parameters": [ { "name": "market", "in": "path", "required": true, "description": "시장", "schema": { "enum": [ "kr", "us" ] } }, { "name": "date", "in": "path", "required": true, "description": "날짜", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "성공", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "잘못된 입력(BAD_REQUEST·BAD_SYMBOL)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "키 없음·형식 오류(UNAUTHORIZED)·Data API 키(ck_live_) 사용(WRONG_KEY_SCOPE)·폐기된 키(INVALID_KEY)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "플랜 없음(PLAN_REQUIRED)·만료(PLAN_EXPIRED)·정지(PLAN_INACTIVE)·시작 전(PLAN_NOT_STARTED)·상품 없음(PRODUCT_REQUIRED)·PoC 기간 끝남(POC_ENDED)·계약 밖 시장(MARKET_NOT_ENTITLED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "없음(NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "초당 한도(RATE_LIMITED)·하루 호출 한도(DAILY_QUOTA_EXCEEDED). Retry-After(초) 포함", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/analyses": { "get": { "summary": "분석 글 목록(SEC 공시 분석·IR 자료 분석·종목 분석) — 제목·날짜·Phoenix AI 페이지 링크", "tags": [ "data" ], "security": [ { "bearer": [] } ], "parameters": [ { "name": "kind", "in": "query", "required": false, "description": "종류", "schema": { "enum": [ "sec", "ir", "stock" ] } }, { "name": "symbol", "in": "query", "required": false, "description": "종목", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "최대 건수", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "offset", "in": "query", "required": false, "description": "건너뛸 건수", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "성공", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "잘못된 입력(BAD_REQUEST·BAD_SYMBOL)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "키 없음·형식 오류(UNAUTHORIZED)·Data API 키(ck_live_) 사용(WRONG_KEY_SCOPE)·폐기된 키(INVALID_KEY)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "플랜 없음(PLAN_REQUIRED)·만료(PLAN_EXPIRED)·정지(PLAN_INACTIVE)·시작 전(PLAN_NOT_STARTED)·상품 없음(PRODUCT_REQUIRED)·PoC 기간 끝남(POC_ENDED)·계약 밖 시장(MARKET_NOT_ENTITLED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "없음(NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "초당 한도(RATE_LIMITED)·하루 호출 한도(DAILY_QUOTA_EXCEEDED). Retry-After(초) 포함", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ask": { "post": { "summary": "Phoenix AI PRO에 질문(비동기) — 202와 job_id를 돌려준다. 하루 질문 수는 웹 PRO와 합산(계정별 한도)", "tags": [ "ask" ], "security": [ { "bearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "question" ], "properties": { "question": { "type": "string", "minLength": 2, "maxLength": 2000 }, "lang": { "enum": [ "auto", "ko", "en", "ja", "tr" ] }, "thread_id": { "type": "integer", "description": "이어 물을 대화" } } } } } }, "responses": { "202": { "description": "접수", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AskAccepted" } } } }, "400": { "description": "잘못된 입력", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "키 없음·형식 오류(UNAUTHORIZED)·Data API 키(ck_live_) 사용(WRONG_KEY_SCOPE)·폐기된 키(INVALID_KEY)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "이번 달 AI 비용 상한(BUDGET_EXCEEDED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "플랜 없음(PLAN_REQUIRED)·만료(PLAN_EXPIRED)·정지(PLAN_INACTIVE)·시작 전(PLAN_NOT_STARTED)·상품 없음(PRODUCT_REQUIRED)·PoC 기간 끝남(POC_ENDED)·계약 밖 시장(MARKET_NOT_ENTITLED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "thread_id 없음", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "진행 중인 질문 있음(ASK_IN_PROGRESS)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "초당 한도(RATE_LIMITED)·하루 호출 한도(DAILY_QUOTA_EXCEEDED)·계정 월 AI 호출 한도(AI_MONTHLY_QUOTA_EXCEEDED)·계정 하루 AI 호출 한도(AI_QUOTA_EXCEEDED, 등급별; PoC-Launch 기본 20회). Retry-After(초) 포함", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/mcp": { "post": { "summary": "원격 MCP 서버(JSON-RPC 2.0 over Streamable HTTP, stateless·JSON 응답) — initialize · tools/list · tools/call. 도구 호출 1번 = 하루 호출 1회(get_ask_result·get_account_usage 제외), 초당 한도는 REST와 같은 키 버킷", "tags": [ "mcp" ], "security": [ { "bearer": [] } ], "description": "Accept: application/json, text/event-stream · Content-Type: application/json. 인증은 PRO API 키 또는 OAuth 접근 토큰(ck_mcp_at_) — PRO 도구. Data API 키(ck_live_)도 받습니다 — Data API 도구(도구 호출 1번 = Data API 요청 1번, Data API의 한도·플랜·시장 판정). API 문서 세션 키(ck_docs_)는 401 WRONG_KEY_SCOPE. 401 응답의 WWW-Authenticate가 보호 자원 메타데이터(OAuth 발견)를 가리킵니다.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON-RPC 2.0 요청(예: {\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\"})" } } } }, "responses": { "200": { "description": "JSON-RPC 응답", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "알림 접수(본문 없음)" }, "400": { "description": "JSON 아님(-32700)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "키 없음·형식 오류(UNAUTHORIZED)·Data API 키(ck_live_) 사용(WRONG_KEY_SCOPE)·폐기된 키(INVALID_KEY)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "플랜 없음(PLAN_REQUIRED)·만료(PLAN_EXPIRED)·정지(PLAN_INACTIVE)·시작 전(PLAN_NOT_STARTED)·상품 없음(PRODUCT_REQUIRED)·PoC 기간 끝남(POC_ENDED)·계약 밖 시장(MARKET_NOT_ENTITLED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "본문 1MB 초과", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "초당 한도(RATE_LIMITED)·하루 호출 한도(DAILY_QUOTA_EXCEEDED). Retry-After(초) 포함", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "SSE 스트림 — 지원하지 않음(stateless, 405)", "tags": [ "mcp" ], "security": [ { "bearer": [] } ], "responses": { "401": { "description": "키 없음·형식 오류(UNAUTHORIZED)·Data API 키(ck_live_) 사용(WRONG_KEY_SCOPE)·폐기된 키(INVALID_KEY)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "플랜 없음(PLAN_REQUIRED)·만료(PLAN_EXPIRED)·정지(PLAN_INACTIVE)·시작 전(PLAN_NOT_STARTED)·상품 없음(PRODUCT_REQUIRED)·PoC 기간 끝남(POC_ENDED)·계약 밖 시장(MARKET_NOT_ENTITLED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "POST만", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "초당 한도(RATE_LIMITED)·하루 호출 한도(DAILY_QUOTA_EXCEEDED). Retry-After(초) 포함", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "세션 종료 — 지원하지 않음(stateless, 405)", "tags": [ "mcp" ], "security": [ { "bearer": [] } ], "responses": { "401": { "description": "키 없음·형식 오류(UNAUTHORIZED)·Data API 키(ck_live_) 사용(WRONG_KEY_SCOPE)·폐기된 키(INVALID_KEY)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "플랜 없음(PLAN_REQUIRED)·만료(PLAN_EXPIRED)·정지(PLAN_INACTIVE)·시작 전(PLAN_NOT_STARTED)·상품 없음(PRODUCT_REQUIRED)·PoC 기간 끝남(POC_ENDED)·계약 밖 시장(MARKET_NOT_ENTITLED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "POST만", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "초당 한도(RATE_LIMITED)·하루 호출 한도(DAILY_QUOTA_EXCEEDED). Retry-After(초) 포함", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ask/{job_id}": { "get": { "summary": "질문 작업 상태·답(하루 호출 수에 넣지 않음, 초당 한도는 적용)", "tags": [ "ask" ], "security": [ { "bearer": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "description": "작업 번호", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "상태·답", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AskResult" } } } }, "401": { "description": "키 없음·형식 오류(UNAUTHORIZED)·Data API 키(ck_live_) 사용(WRONG_KEY_SCOPE)·폐기된 키(INVALID_KEY)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "플랜 없음(PLAN_REQUIRED)·만료(PLAN_EXPIRED)·정지(PLAN_INACTIVE)·시작 전(PLAN_NOT_STARTED)·상품 없음(PRODUCT_REQUIRED)·PoC 기간 끝남(POC_ENDED)·계약 밖 시장(MARKET_NOT_ENTITLED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "없음", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "초당 한도(RATE_LIMITED)·하루 호출 한도(DAILY_QUOTA_EXCEEDED). Retry-After(초) 포함", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "tags": [ { "name": "meta", "x-displayName": "서비스 정보", "description": "서비스 설명과 이 명세. 키가 필요 없습니다." }, { "name": "account", "x-displayName": "계정", "description": "내 플랜과 오늘·이번 달 사용량." }, { "name": "data", "x-displayName": "데이터", "description": "공시·재무·시세·스크리너·업종·일정·브리프·리포트. Data 또는 Bundle 플랜." }, { "name": "ask", "x-displayName": "대화형 질문(Ask)", "description": "Phoenix AI PRO에 질문하고 답을 받습니다. Ask 또는 Bundle 플랜." }, { "name": "mcp", "x-displayName": "MCP", "description": "원격 MCP 서버(JSON-RPC 2.0 over Streamable HTTP)." } ] }