공시한입 Docs

Appearance

Admin API ​

모든 admin 엔드포인트는 X-Admin-Key 헤더로 인증한다. JWT 불필요.

bash
# 로컬
export ADMIN_KEY=dartbrief-admin-dev

# prod (~/.config/cloud-tokens/ 또는 Railway 환경변수에서 확인)
export ADMIN_KEY=<prod-admin-key>

App Check 미들웨어 적용 제외 — 직접 curl 호출 가능.

GET /api/v1/admin/scheduler/status ​

의도 ​

AI 분석 스케줄러 상태 조회.

응답 ​

json
{ "status": "running", "activeThreads": 0, "concurrency": 20, "totalSuccess": 1234, "totalFailed": 5 }

curl 예제 ​

bash
curl -s -H "X-Admin-Key: $ADMIN_KEY" \
  https://api.dartbrief.com/api/v1/admin/scheduler/status | jq
curl -s -H "X-Admin-Key: $ADMIN_KEY" \
  http://localhost:8000/api/v1/admin/scheduler/status | jq

POST /api/v1/admin/scheduler/pause ​

POST /api/v1/admin/scheduler/resume ​

의도 ​

스케줄러 일시정지 / 재개.

curl 예제 ​

bash
curl -s -X POST -H "X-Admin-Key: $ADMIN_KEY" \
  https://api.dartbrief.com/api/v1/admin/scheduler/pause | jq

curl -s -X POST -H "X-Admin-Key: $ADMIN_KEY" \
  https://api.dartbrief.com/api/v1/admin/scheduler/resume | jq

POST /api/v1/admin/backfill ​

의도 ​

특정 날짜 범위의 공시를 DART에서 가져와 AI 분석 큐에 enqueue.

입력 ​

  • Query: fromDate — YYYYMMDD
  • Query: toDate — YYYYMMDD
  • Query: delayMs — 공시 건당 딜레이 (optional, default 300ms)

응답 ​

202 Accepted — 백필 시작 ​

json
{ "message": "백필 시작", "fromDate": "20260401", "toDate": "20260430" }

400 Bad Request — 날짜 누락 또는 이미 진행 중 ​

curl 예제 ​

bash
curl -s -X POST -H "X-Admin-Key: $ADMIN_KEY" \
  "https://api.dartbrief.com/api/v1/admin/backfill?fromDate=20260401&toDate=20260430" | jq

GET /api/v1/admin/backfill/status ​

curl 예제 ​

bash
curl -s -H "X-Admin-Key: $ADMIN_KEY" \
  https://api.dartbrief.com/api/v1/admin/backfill/status | jq

POST /api/v1/admin/stocks/sync ​

의도 ​

종목 마스터 동기화 (DART → DB).

입력 ​

  • Query: mode — incremental(기본, 신규 corp_code만) 또는 bootstrap(전량 재동기화)

curl 예제 ​

bash
# 증분 동기화 (기본)
curl -s -X POST -H "X-Admin-Key: $ADMIN_KEY" \
  https://api.dartbrief.com/api/v1/admin/stocks/sync | jq

# 전량 재동기화
curl -s -X POST -H "X-Admin-Key: $ADMIN_KEY" \
  "https://api.dartbrief.com/api/v1/admin/stocks/sync?mode=bootstrap" | jq

GET /api/v1/admin/stocks/sync/status ​

curl 예제 ​

bash
curl -s -H "X-Admin-Key: $ADMIN_KEY" \
  https://api.dartbrief.com/api/v1/admin/stocks/sync/status | jq

POST /api/v1/admin/disclosures/fetch ​

의도 ​

DART OpenAPI 를 한 페이지 동기 호출 → SaveBatch (ON CONFLICT DO NOTHING) 후 결과를 즉시 반환. 디버깅 / 응답 모양 확인용. 대량 백필은 비동기 진행률 추적이 있는 /admin/backfill 사용.

입력 ​

  • Query: beginDate — YYYYMMDD (필수)
  • Query: endDate — YYYYMMDD (필수)
  • Query: corpCode — 특정 회사 corp_code (optional). 없으면 corp_cls=Y (유가증권/KOSPI) 로 조회.
  • Query: pageNo — 페이지 번호 (optional, default 1)
  • Query: pageCount — 페이지당 건수 (optional, default 20)

응답 ​

201 Created — 수집 결과 ​

json
{ "fetched": 20, "saved": 18, "disclosures": [ ... ] }

resp.List 가 없으면 빈 배열 [] 을 201 로 반환.

400 Bad Request — beginDate 또는 endDate 누락 ​

json
{ "message": "beginDate, endDate가 필요합니다." }

500 Internal Server Error — DART API 호출 실패 또는 DB 저장 실패 ​

curl 예제 ​

bash
curl -s -X POST -H "X-Admin-Key: $ADMIN_KEY" \
  "https://api.dartbrief.com/api/v1/admin/disclosures/fetch?beginDate=20260401&endDate=20260401&pageCount=20" | jq