ZUKU API Wiki

인터랙티브 UGC 미디어 플랫폼 ZUKU(즈쿠) 의 REST API 개발자 가이드입니다.

얇은 OpenAPI 스펙과 별도로, 인증·콘텐츠·피드·소셜·미디어·오류·예제를 위키 형태로 정리합니다.

> 구현 기준: _shizuku_local/backend/rs/src/router.rs

> 사이트: /docs/api (Next.js 미리보기)

> OpenAPI(얇은 계약): docs/20-developer-console/openapi.yaml, Jump용 public-jump-repos/zuku-api/openapi/

Base URL

환경	URL
프로덕션	`https://zuzunza.com/api/v1`
로컬 백엔드	`http://localhost:3001/api/v1` (또는 게이트 리라이트 `/api/v1`)

버전 접두사 v1은 URL에 항상 포함합니다. 응답 헤더 X-API-Version: v1 · 봉투 meta.version과 동일 세대입니다.

문서 목차

문서	설명
Getting Started	봉투, 헤더, 빠른 시작, Rate Limits, Versioning
Authentication	가입·로그인·세션·Captcha·개발자 API 키
Captcha	PoW 챌린지·검증·가입/로그인 게이트
Contents	Hype / Swipe / Jump 콘텐츠 CRUD·추천
Feeds	미디어 피드 · 커뮤니티 `feed` · posts
Social	좋아요·북마크·팔로우·댓글·알림·DM
Media	업로드 · Jump play/stream/swf
Game Cloud	Economy · Vars · Saves · Pay · Functions
Developer Console	앱 · API 키 · 웹훅
Examples	curl · JS/TS 실전 시나리오
Errors	에러 봉투 · HTTP · 코드 표
Changelog	v1 변경 이력 · 호환 정책

공통 응답 봉투

{
  "success": true,
  "data": { },
  "meta": {
    "request_id": "…",
    "timestamp": "2026-08-22T00:00:00Z",
    "version": "v1"
  }
}

실패 시 success: false와 error: { code, message, details? }입니다. 상세는 Errors.

인증 한줄 요약

방식	헤더	대표 용도
Bearer 세션	`Authorization: Bearer <access_token>`	대부분의 쓰기·프로필·소셜
API 키	`X-API-Key: sk_live_…`	서버-투-서버 콘텐츠 생성 등

엔드포인트 맵 (요약)

/auth/*          가입·로그인·me·sessions
/captcha/*       PoW 챌린지·검증
/developer/keys  API 키 발급·목록·폐기
/feeds[/*]       hype·swipe·jump 피드
/feed            커뮤니티 타임라인
/posts/*         커뮤니티 글·답글
/contents/*      미디어 콘텐츠·댓글·좋아요
/uploads         multipart 업로드
/jump/games/*    Jump 목록·재생·스트림
/cloud/*         Game Cloud (Economy·Vars·Saves·Pay·Functions)
/devconsole/*    개발자 콘솔 (앱·키·웹훅)
/notifications/* 알림
/dm/*            DM
/users/me/*      내 좋아요 컬렉션
/admin/users/*   관리자