baekjoon-bot/docs/API.md

API Reference

Base URL

http://localhost:8000

인증

Admin API(/admin/*)는 X-Admin-Password 헤더가 필요하다. 서버의 ADMIN_PASSWORD 환경변수와 일치해야 하며, 미설정 시 500 에러를 반환한다.

---

GET /

헬스체크.

응답: {"status": "ok"}

---

GET /today

오늘의 추천 문제를 반환한다. Search 모드와 Workbook 모드를 지원한다.

공통 파라미터

파라미터	타입	설명	기본값
source_mode	string	search 또는 workbook	SOURCE_MODE_DEFAULT or search

Search 모드 파라미터

파라미터	타입	설명	기본값
difficulty_mode	string	easy/hard/all	DIFFICULTY_MODE_DEFAULT or easy
tag_mode	string	easy/hard/all	TAG_MODE_DEFAULT or easy
difficulty	string	난이도 범위 (예: 6..10). 지정 시 difficulty_mode보다 우선	-
tags	string	태그 (예: dp,graphs). 지정 시 tag_mode보다 우선	-
lang	string	언어 필터: ko/en/ko,en/all	LANG_DEFAULT or all

Workbook 모드 파라미터

파라미터	타입	설명	기본값
workbook_id	int	문제집 ID	WORKBOOK_ID_DEFAULT
workbook_pick	string	random 또는 level_asc	level_asc

응답 (Search 모드)

{
  "source_mode": "search",
  "difficulty_mode": "easy",
  "tag_mode": "easy",
  "lang": "all",
  "difficulty": "6..10",
  "tags": ["dp"],
  "query": "*6..10 (tag:dp)",
  "problemId": 1234,
  "title": "문제 제목",
  "level": 8,
  "problemUrl": "https://www.acmicpc.net/problem/1234",
  "solvedUrl": "https://solved.ac/problems/id/1234",
  "discordPayload": { "embeds": [...] }
}

응답 (Workbook 모드)

{
  "source_mode": "workbook",
  "workbook_id": 12345,
  "problemId": 1234,
  "title": "문제 제목",
  "level": 8,
  "problemUrl": "https://www.acmicpc.net/problem/1234",
  "solvedUrl": "https://solved.ac/problems/id/1234",
  "discordPayload": { "embeds": [...] }
}

에러

상태 코드	조건
400	difficulty_mode/tag_mode 값이 유효하지 않음
400	Workbook 모드에서 workbook_id를 확정할 수 없음
409	Workbook에서 더 이상 뽑을 문제가 없음 (no_more_problems_in_workbook)
503	Search 모드에서 solved.ac 조회 실패 (failed_to_fetch_problem)

---

POST /admin/workbooks/{workbook_id}/enrich

문제집에 포함된 문제들의 메타데이터(제목, 난이도, 태그)를 solved.ac API로 채운다.

파라미터

파라미터	타입	설명	기본값
only_missing	bool	true면 NULL 필드만 채움, false면 전체 덮어씀	true
commit_every	int (1~500)	DB 커밋 배치 크기	50
sleep_sec	float (0.0~2.0)	solved.ac 호출 간 대기 시간	0.12

요청 예시

curl -s -X POST \
  -H "X-Admin-Password: change-me" \
  "http://localhost:8000/admin/workbooks/12345/enrich?only_missing=true"

응답

{
  "status": "ok",
  "result": {
    "workbook_id": 12345,
    "target_count": 100,
    "updated": 95,
    "skipped": 3,
    "failed": 2,
    "only_missing": true,
    "commit_every": 50,
    "sleep_sec": 0.12,
    "message": "enrich done"
  }
}

---

DELETE /admin/workbooks/{workbook_id}/reset

문제집의 발송 기록(workbook_sends)을 초기화하여 모든 문제를 다시 추천받을 수 있게 한다.

요청 예시

curl -s -X DELETE \
  -H "X-Admin-Password: change-me" \
  "http://localhost:8000/admin/workbooks/12345/reset"

응답

{
  "status": "ok",
  "workbook_id": 12345,
  "deleted_sends": 42,
  "message": "workbook progress reset (problems can be picked again)"
}