Base URL X-API-Key: <발급받은 키> 헤더. 키는 위 "API 키" 에서 발급 (권한 x, 시간당 호출 한도 적용, 초과 시 429).
응답 형식 항상 JSON. 성공 {"ok": true, ...}, 실패 {"ok": false, "error": "<코드>", "message": "<설명>"}. 모든 호출은 "REST API 호출 로그" 에 기록됩니다.
1. 계정 등록 POST /api/v1/x/accounts
한 번에 1개. 이미 등록된 handle 이면 409 duplicate 로 거부되고 (드롭), 로그에 남습니다.
curl -X POST "$BASE/api/v1/x/accounts" \
-H "X-API-Key: hue_xxxxxxxx" -H "Content-Type: application/json" \
-d '{"handle": "@illit_official", "entity": "아일릿", "note": "공식 계정", "priority": 5, "recheck_days": 30}'
| 필드 | 필수 | 설명 |
|---|
| handle | O | @handle / handle / x.com/handle URL. 영문·숫자·_ 1~15자. 소문자로 저장 |
| entity | - | 연결할 HUE 엔티티 canonical_name 또는 UUID. 없으면 404 entity_not_found |
| note | - | 메모 |
| priority | - | 수집 우선순위 (높을수록 먼저, 기본 0) |
| recheck_days | - | 재수집 주기 일수 (0=1회만, 기본 30) |
응답 201 {"ok": true, "account": {...}} / 409 {"ok": false, "error": "duplicate", "handle": "...", "existing": {"id", "handle", "active", "last_status", "created_at"}} / 422 invalid_handle / 401 키 없음·무효 / 429 한도 초과
2. 계정 목록 조회 GET /api/v1/x/accounts
curl "$BASE/api/v1/x/accounts?status=ok&q=illit&page=1&per_page=100" -H "X-API-Key: hue_xxxxxxxx"
| 파라미터 | 기본 | 설명 |
|---|
| status | all | all 전체 / pending 대기(미수집) / ok 수집 완료 / failed 실패 / inactive 비활성 |
| q | - | handle · 연결 엔티티명 · 표시명 부분 일치 검색 |
| entity | - | 특정 엔티티(canonical_name/UUID)에 연결된 계정만 |
| page / per_page | 1 / 100 | per_page 최대 100 |
| sort | created_desc | created_desc created_asc handle checked_desc |
응답
{"ok": true, "status": "ok", "q": "illit", "page": 1, "per_page": 100, "total": 3, "pages": 1,
"items": [{
"id": 123, "handle": "illit_official", "url": "https://x.com/illit_official/about",
"status": "ok", "active": true, "last_status": "ok", "last_error": null,
"entity_id": "ca2f111a-...", "entity_name": "아일릿", "note": "공식 계정",
"priority": 5, "recheck_days": 30, "added_by": "api:partner", "created_at": "2026-09-15T02:10:00+00:00", "last_checked_at": "...",
"about": {"fetched_at": "...", "display_name": "ILLIT", "joined": "2023년 12월", "based_in": "South Korea",
"verified_since": "2024년 3월", "username_changes": "사용자 아이디 1회 변경 / 마지막 날짜: ...", "connected_via": "Korea App Store", "parse_ok": true}
}]}
about 는 아직 수집 전이면 null. status 는 pending|ok|failed|inactive 로 정규화된 값.
3. 계정 단건 조회 GET /api/v1/x/accounts/{handle}
curl "$BASE/api/v1/x/accounts/illit_official?history=5" -H "X-API-Key: hue_xxxxxxxx"
history=N (최대 50) 이면 최근 N회 수집 이력이 history 배열로 추가. 미등록이면 404 not_found.
4. X 계정 등록 (아이디만) POST /api/v1/x/register
HUE 엔티티와 무관하게 X 아이디 하나만 등록합니다. @blackout_kr, blackout_kr, https://x.com/blackout_kr 모두 허용.
curl -X POST "$BASE/api/v1/x/register" -H "X-API-Key: hue_xxxxxxxx" -H "Content-Type: application/json" \
-d '{"handle": "@blackout_kr"}'
응답 201 {"ok": true, "handle": "blackout_kr", "result": "created", "id": 123, "url": "https://x.com/blackout_kr"} / 409 {"ok": false, "error": "duplicate", "handle": "...", "existing": {...}} / 422 invalid
5. X 계정 개별 일괄 등록 (수동 목록 또는 CSV) POST /api/v1/x/register/batch
여러 계정을 건별로 등록합니다. 한 건이 중복/오류여도 나머지는 등록되고, 건별 결과가 돌아옵니다 (최대 5000개).
# 수동 목록 (JSON)
curl -X POST "$BASE/api/v1/x/register/batch" -H "X-API-Key: hue_xxxxxxxx" -H "Content-Type: application/json" \
-d '{"handles": ["@blackout_kr", "illit_official", "https://x.com/nasa"]}'
# CSV/TXT 파일 (헤더 handle / user_id / username 열이 있으면 그 열, 없으면 첫 열. 줄바꿈·쉼표·공백 구분도 허용)
curl -X POST "$BASE/api/v1/x/register/batch" -H "X-API-Key: hue_xxxxxxxx" -F "file=@accounts.csv"
{"ok": true, "source": "json", "total": 3, "created": 2, "duplicate": 1, "invalid": 0,
"items": [{"handle": "blackout_kr", "result": "created", "id": 124, "url": "https://x.com/blackout_kr"},
{"handle": "illit_official", "result": "duplicate", "id": 123, "message": "이미 등록된 계정", "existing": {...}},
{"handle": "nasa", "result": "created", "id": 125, "url": "https://x.com/nasa"}]}
result: created 등록됨 / duplicate 이미 등록(또는 요청 안 중복) / invalid 형식 오류. 등록된 계정은 X 계정 탭 목록에 "대기" 로 나타나고 크롤러가 순서대로 수집합니다.
오류 코드
| HTTP | error | 의미 |
|---|
| 401 | - | X-API-Key 없음 또는 무효/비활성 |
| 404 | entity_not_found / not_found | 엔티티 또는 계정 없음 |
| 409 | duplicate | 이미 등록된 handle (등록 안 됨) |
| 422 | invalid_handle | handle 형식 오류 (본문 검증 실패 시 FastAPI 기본 422 형식) |
| 429 | - | 키의 시간당 호출 한도 초과 |