{"openapi":"3.1.0","info":{"title":"public-api","description":"SEC 공시(Form 4 · Form 144 · Schedule 13D/13G) API. 무인증(free) 또는 `X-API-Key`(basic/pro)로 쓴다. free 는 `known_at` 기준 24시간 지연된 데이터만 노출한다.\n\n### 인증\n`X-API-Key` 헤더 없음 = free 티어(기본값). 유효한 키 = 24시간 게이트 우회 + tenant 가 소유한 basic/pro 한도. 키가 있는데 무효·폐기면 401(조용히 free 로 강등하지 않는다).\n\n### 레이트리밋\nfree: IP 당 분당 60 · 일당 2,000. basic: 키 당 분당 120 · 일당 10,000. pro: 키 당 분당 300 · 일당 50,000(IP 가 아니라 키 버킷). 초과하면 429 와 함께 `X-RateLimit-*` 헤더가 돌아온다(한도는 티어별로 다른 값을 반영).\n\n### 라이선스\n가격(yfinance)에서 파생된 값은 티어와 무관하게 이 API 에 없다 — DB role 권한 자체가 그 테이블을 못 본다.","version":"0.1.0"},"paths":{"/health":{"get":{"tags":["health"],"summary":" Health","operationId":"_health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/v1/events":{"get":{"tags":["events"],"summary":"이벤트 피드 — Form 4, 무료 티어(known_at 24시간 지연)","operationId":"list_events_v1_events_get","parameters":[{"name":"ticker","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"발행사 티커(대소문자 무관).","title":"Ticker"},"description":"발행사 티커(대소문자 무관)."},{"name":"event_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"`economic_event.event_type` 값.","title":"Event Type"},"description":"`economic_event.event_type` 값."},{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"recorded_at(=economic_event.created_at) 이 이 시각 이상인 것만.","title":"Since"},"description":"recorded_at(=economic_event.created_at) 이 이 시각 이상인 것만."},{"name":"min_value","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"trade_value(=COALESCE(cash_purchase_value, cash_sale_value)) 최소값.","title":"Min Value"},"description":"trade_value(=COALESCE(cash_purchase_value, cash_sale_value)) 최소값."},{"name":"quality_status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"CLEAN/INVARIANT_VIOLATION/SOURCE_INCOMPLETE/REVIEW_REQUIRED.","title":"Quality Status"},"description":"CLEAN/INVARIANT_VIOLATION/SOURCE_INCOMPLETE/REVIEW_REQUIRED."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"이전 응답의 next_cursor. 불투명 토큰.","title":"Cursor"},"description":"이전 응답의 next_cursor. 불투명 토큰."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"description":"한 페이지 최대 행 수.","default":50,"title":"Limit"},"description":"한 페이지 최대 행 수."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventsResponse"}}}},"400":{"description":"cursor 토큰이 깨졌다."},"503":{"description":"DB 에 붙지 못했다."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/companies/{ticker}/insider-flow":{"get":{"tags":["companies"],"summary":"인사이더 플로우 롤링 집계 — 매수 OPEN_MARKET_BUY 한정, 무료 티어(known_at 24시간 지연)","operationId":"company_insider_flow_v1_companies__ticker__insider_flow_get","parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","description":"발행사 티커(대소문자 무관).","title":"Ticker"},"description":"발행사 티커(대소문자 무관)."},{"name":"window","in":"query","required":false,"schema":{"type":"integer","description":"롤링 윈도우(일). (7, 30) 중 하나.","default":30,"title":"Window"},"description":"롤링 윈도우(일). (7, 30) 중 하나."},{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"이 날짜(as_of_date) 이상만.","title":"Since"},"description":"이 날짜(as_of_date) 이상만."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":365,"minimum":1,"description":"돌려줄 최근 행 수 상한.","default":60,"title":"Limit"},"description":"돌려줄 최근 행 수 상한."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InsiderFlowResponse"}}}},"422":{"description":"window 이 (7, 30) 밖이다."},"503":{"description":"DB 에 붙지 못했다."}}}},"/v1/companies/{ticker}/timeline":{"get":{"tags":["companies"],"summary":"발행사 통합 타임라인 — Form4 + 13D/G + 144, 무료 티어(known_at 24시간 지연)","operationId":"company_timeline_v1_companies__ticker__timeline_get","parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","description":"발행사 티커(대소문자 무관).","title":"Ticker"},"description":"발행사 티커(대소문자 무관)."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":300,"minimum":1,"description":"출처별 상한 — 세 출처를 합친 뒤 이 값으로 다시 자른다.","default":100,"title":"Limit"},"description":"출처별 상한 — 세 출처를 합친 뒤 이 값으로 다시 자른다."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimelineResponse"}}}},"404":{"description":"인식하지 못하는 티커."},"503":{"description":"DB 에 붙지 못했다."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"EventItem":{"properties":{"event_id":{"type":"string","title":"Event Id"},"event_revision":{"type":"integer","title":"Event Revision"},"event_type":{"type":"string","title":"Event Type"},"quality_status":{"type":"string","title":"Quality Status"},"rule_10b5_1_status":{"type":"string","title":"Rule 10B5 1 Status"},"transaction_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Transaction Date"},"issuer_cik":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Issuer Cik"},"ticker":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ticker","description":"null = 대표 티커 미확정."},"issuer_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Issuer Name"},"owner_cik":{"type":"string","title":"Owner Cik"},"owner_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Owner Name"},"gross_acquired_shares":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Gross Acquired Shares"},"gross_disposed_shares":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Gross Disposed Shares"},"net_share_change":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Net Share Change"},"cash_purchase_value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cash Purchase Value"},"cash_sale_value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cash Sale Value"},"trade_value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Trade Value","description":"COALESCE(cash_purchase_value, cash_sale_value) — `min_value` 필터가 비교하는 값."},"holding_change_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Holding Change Pct"},"accession_no":{"type":"string","title":"Accession No","description":"이 이벤트의 앵커 공시."},"known_at":{"type":"string","format":"date-time","title":"Known At","description":"공시 접수 시각(UTC). 무료 티어 24시간 지연 게이트의 기준."},"recorded_at":{"type":"string","format":"date-time","title":"Recorded At","description":"우리 시스템이 이 이벤트를 기록한 시각. known_at 과 다를 수 있다(처리 지연)."}},"additionalProperties":false,"type":"object","required":["event_id","event_revision","event_type","quality_status","rule_10b5_1_status","owner_cik","accession_no","known_at","recorded_at"],"title":"EventItem","description":"`GET /v1/events` 행 1건 — Form 4 해석 이벤트.\n\n**공통 계약**(#303): `event_revision`·`known_at`·`accession_no` 는 모든 행에 있다.\n가격에서 파생된 값은 여기 없다(라이선스 — README 참조)."},"EventsResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/EventItem"},"type":"array","title":"Items"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"다음 페이지의 `cursor` 파라미터. null = 마지막 페이지."},"limitations":{"additionalProperties":{"type":"string"},"type":"object","title":"Limitations"}},"additionalProperties":false,"type":"object","required":["items","limitations"],"title":"EventsResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"HealthResponse":{"properties":{"status":{"type":"string","const":"ok","title":"Status","examples":["ok"]},"service":{"type":"string","title":"Service","examples":["public-api"]},"version":{"type":"string","title":"Version","examples":["0.1.0"]},"db":{"type":"string","enum":["ok","unavailable"],"title":"Db","description":"DB 접속 가능 여부. **unavailable 이어도 200** 이다(fail-open).","examples":["ok"]}},"additionalProperties":false,"type":"object","required":["status","service","version","db"],"title":"HealthResponse"},"InsiderFlowItem":{"properties":{"issuer_cik":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Issuer Cik"},"ticker":{"type":"string","title":"Ticker"},"as_of_date":{"type":"string","format":"date","title":"As Of Date"},"window_days":{"type":"integer","title":"Window Days"},"buy_count":{"type":"integer","title":"Buy Count"},"buy_shares":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Buy Shares"},"buy_value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Buy Value"},"distinct_buyers":{"type":"integer","title":"Distinct Buyers"},"sell_count_discretionary":{"type":"integer","title":"Sell Count Discretionary"},"sell_value_discretionary":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Sell Value Discretionary"},"sell_count_planned":{"type":"integer","title":"Sell Count Planned"},"sell_value_planned":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Sell Value Planned"},"distinct_sellers":{"type":"integer","title":"Distinct Sellers"},"known_at_cut":{"type":"string","format":"date-time","title":"Known At Cut","description":"PIT 컷 — 이 행이 계산될 때 본 세상의 시각. PIT 재현의 근거."},"computed_at":{"type":"string","format":"date-time","title":"Computed At","description":"이 행이 실제로 계산·저장된 시각(known_at_cut 과 다를 수 있다)."}},"additionalProperties":false,"type":"object","required":["ticker","as_of_date","window_days","buy_count","distinct_buyers","sell_count_discretionary","sell_count_planned","distinct_sellers","known_at_cut","computed_at"],"title":"InsiderFlowItem","description":"`GET /v1/companies/{ticker}/insider-flow` 행 1건 — `sec.insider_flow_daily` 그대로.\n\n**매수는 `OPEN_MARKET_BUY` 한정.** 계획 매도(`sell_count_planned`)는\n`rule_10b5_1_status='REPORTED_TRUE'` 기준(#312 문서 레벨 파싱 이후 사실 등급) —\n공동제출(joint filing) 184건은 아직 `NOT_REPORTED` 로 남아 재량 매도로 세어진다\n(`#318` 로 추적 중, `limitations.insider_flow_sell_grading` 참조)."},"InsiderFlowResponse":{"properties":{"ticker":{"type":"string","title":"Ticker"},"window_days":{"type":"integer","title":"Window Days"},"items":{"items":{"$ref":"#/components/schemas/InsiderFlowItem"},"type":"array","title":"Items"},"items_truncated":{"type":"boolean","title":"Items Truncated","description":"`limit` 을 넘는 행이 더 있었는가."},"limitations":{"additionalProperties":{"type":"string"},"type":"object","title":"Limitations"}},"additionalProperties":false,"type":"object","required":["ticker","window_days","items","items_truncated","limitations"],"title":"InsiderFlowResponse"},"TimelineItem":{"properties":{"source_form":{"type":"string","enum":["form4","sc13","form144"],"title":"Source Form"},"accession_no":{"type":"string","title":"Accession No"},"known_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Known At"},"event_revision":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Event Revision"}},"additionalProperties":true,"type":"object","required":["source_form","accession_no"],"title":"TimelineItem","description":"`GET /v1/companies/{ticker}/timeline` 행 1건 — Form4 · 13D/G · 144 통합.\n\n출처마다 그 다음 필드가 다르다(`extra=\"allow\"`) — 공통 계약은 `source_form`·\n`accession_no`·`known_at`·`event_revision` 뿐이다. **13D/G·144 는 revision\n개념이 없어 `event_revision` 이 항상 null** — 결측이 아니라 그 폼의 사실이다\n(`product/timeline.py` 참조)."},"TimelineResponse":{"properties":{"ticker":{"type":"string","title":"Ticker"},"issuer_cik":{"type":"string","title":"Issuer Cik"},"items":{"items":{"$ref":"#/components/schemas/TimelineItem"},"type":"array","title":"Items"},"limitations":{"additionalProperties":{"type":"string"},"type":"object","title":"Limitations"}},"additionalProperties":false,"type":"object","required":["ticker","issuer_cik","items","limitations"],"title":"TimelineResponse"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"tags":[{"name":"health","description":"기동 확인. 레이트리밋·usage 로깅 면제."},{"name":"events","description":"무료 티어 이벤트 피드."},{"name":"companies","description":"발행사 단위 통합 타임라인."}]}