공시한입 Docs

Appearance

GET /api/v1/watchlist ​

의도 ​

내 관심 종목 목록 조회.

인증 ​

Bearer JWT 필수

응답 ​

200 OK ​

json
[
  {
    "id": 42,
    "corp_code": "00126380",
    "corp_name": "삼성전자",
    "stock_code": "005930",
    "notify_enabled": true,
    "created_at": "2026-04-01T12:00:00Z"
  }
]

stock_code 는 종목코드 미보유 시 null.

curl 예제 ​

bash
curl -s -H "Authorization: Bearer $TOKEN" \
  https://api.dartbrief.com/api/v1/watchlist | jq

GET /api/v1/watchlist/capacity ​

의도 ​

슬롯 용량 상태 조회.

인증 ​

Bearer JWT 필수

응답 ​

200 OK ​

json
{ "capacity": 3, "used": 3, "remaining": 0 }

capacity 는 구독 티어별: 무료 3 / PRO 30 / MAX 100 (entitlement.Tier.SlotCapacity(), 활성 티어는 users.premium_tier + premium_until). domain-subscription

curl 예제 ​

bash
curl -s -H "Authorization: Bearer $TOKEN" \
  https://api.dartbrief.com/api/v1/watchlist/capacity | jq

POST /api/v1/watchlist ​

의도 ​

관심 종목 추가.

인증 ​

Bearer JWT 필수

입력 ​

json
{ "corp_code": "00126380" }

응답 ​

201 Created — 추가 성공 (추가된 종목 정보 반환) ​

json
{
  "id": 42,
  "corp_code": "00126380",
  "corp_name": "삼성전자",
  "stock_code": "005930",
  "notify_enabled": true,
  "created_at": "2026-04-01T12:00:00Z"
}

이미 등록된 종목을 다시 호출해도 동일 페이로드로 201 반환 (idempotent — 핸들러가 Has 로 사전 확인 후 capacity 검사를 건너뜀, repo 의 INSERT ... ON CONFLICT DO UPDATE SET corp_code = EXCLUDED.corp_code RETURNING ... 으로 기존 row 반환).

409 Conflict — 관심종목 한도 초과 (신규 추가에만 적용) ​

json
{ "message": "관심종목 한도에 도달했어요. 종목을 빼거나 구독으로 한도를 늘리세요.", "capacity": 3, "used": 3 }

클라이언트는 이 409 (한도 초과) 를 페이월 트리거로 사용 (source: watchlist_full). screen-paywall

capacity 가득 찬 사용자가 이미 보유한 종목을 재요청하면 409 가 아니라 201 (idempotent no-op). lazy auth 게이트 흐름에서 게이트 통과 직후 자동 add 가 발동될 때 사용자 의도와 결과가 어긋나지 않게 하려는 정책 (2026-05-08, PR #57).

curl 예제 ​

bash
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"corp_code":"00126380"}' \
  https://api.dartbrief.com/api/v1/watchlist | jq

DELETE /api/v1/watchlist/ ​

의도 ​

관심 종목 제거.

인증 ​

Bearer JWT 필수

응답 ​

204 No Content — 삭제 성공 ​

404 Not Found — 없는 종목 ​

curl 예제 ​

bash
curl -s -X DELETE -H "Authorization: Bearer $TOKEN" \
  https://api.dartbrief.com/api/v1/watchlist/00126380

PATCH /api/v1/watchlist/{corpCode}/notify ​

의도 ​

종목별 알림 on/off 설정.

인증 ​

Bearer JWT 필수

입력 ​

json
{ "enabled": true }

응답 ​

200 OK — 업데이트된 상태 반환 ​

curl 예제 ​

bash
curl -s -X PATCH -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled":false}' \
  https://api.dartbrief.com/api/v1/watchlist/00126380/notify | jq

비즈니스 메모 ​

  • 슬롯 정책: capacity only — 자유 add/remove, cooldown/카운터 없음
  • capacity 는 구독 티어로부터 파생 — 무료 3 / PRO 30 / MAX 100 (entitlement.Tier.SlotCapacity()). 폐기된 users.slot_capacity 컬럼은 migration 00018 에서 제거