본문 바로가기

REST API

사이트가 쓰는 API 입니다. 공개 읽기 API 는 인증 없이 호출할 수 있고, 내 계정에 대한 API 는 마이페이지에서 발급한 개인 API 토큰으로 호출합니다. 응답은 모두 JSON(UTF-8)이며 CORS 가 열려 있습니다. 관리자 기능은 싣지 않습니다.

공개 읽기 · 인증 불필요계정 API · Bearer 토큰JSON · CORS60 요청/분/IP

기본 규칙

Base URL
https://dpplugins.com
오류 응답
{ "error": "메시지" } 와 HTTP 상태 코드(400·404·429·500)
레이트 리밋
IP 당 분당 60회. 넘으면 429. 목록·검색 같은 공개 GET 과 모든 쓰기 요청에 적용
시각
ISO 8601 UTC 문자열 (2026-11-10T03:21:00.000Z)

응답 필드는 사이트와 함께 바뀔 수 있습니다. 모르는 필드는 무시하고, 없는 필드는 null 로 처리하세요.

인증 — 개인 API 토큰

마이페이지 → API 토큰 에서 발급합니다. 토큰은 dpp_ 로 시작하는 52자 문자열이고, 발급 직후 한 번만 보이므로 바로 복사해 두세요. 계정당 활성 토큰 10개까지.

bash
curl -H "Authorization: Bearer dpp_xxxxxxxx…" https://dpplugins.com/api/auth/me
권한
계정 본인과 같습니다. 내 리소스 게시·수정·삭제, 릴리스·스크린샷, 즐겨찾기, 알림 조회 등
쓸 수 없는 곳
관리자 경로(/api/admin/*, /api/official/admin/*, /api/hub/admin/*)와 토큰 관리(/api/tokens). 403 으로 거부됩니다
CSRF
토큰 요청은 쿠키를 쓰지 않으므로 Origin 헤더가 필요 없습니다. 쿠키 세션으로 변경 요청을 보낼 때만 Origin 검사가 걸립니다
실패
해제됐거나 모르는 토큰은 익명으로 처리되어 인증 필요 경로에서 401 이 납니다. 차단된 계정의 토큰도 같습니다

토큰이 노출됐다면 마이페이지에서 즉시 해제하세요. 해제는 되돌릴 수 없고, 그 토큰을 쓰던 도구는 바로 401 을 받습니다.

계정 API (토큰 필요)

아래 경로는 모두 Authorization: Bearer <token> 헤더가 필요합니다. 없으면 401. 변경 요청의 본문은 JSON 입니다.

내 정보

GET/api/auth/me토큰 뒤의 계정. { user: {id, username, globalName, nickname, avatarUrl, title, …} }. 토큰이 없으면 { user: null }.
GET/api/notifications내 알림 목록(최신순). 리소스 업데이트·댓글·좋아요 알림이 포함됩니다.
GET/api/servers/my내가 등록한 서버 (인증 대기 포함).
GET/api/skins/my내가 올린 스킨.

즐겨찾기

GET/api/favorites즐겨찾은 리소스 목록. 목록 API 와 같은 카드 필드.
GET/api/published-plugins/{projectId}/favorite이 리소스를 즐겨찾았는지. { favorited, count }
POST/api/published-plugins/{projectId}/favorite즐겨찾기 토글. 본문 없음. 같은 응답 모양.

내 리소스 게시

GET/api/published-plugins/my내가 게시한 리소스 전체(비공개 포함). 응답은 목록 API 와 같습니다.
GET/api/published-plugins/check-slug슬러그 사용 가능 여부. { available, slug }
이름위치설명
slugquery3~50자, 소문자·숫자·하이픈
POST/api/published-plugin-files파일 업로드(multipart/form-data). 릴리스 파일은 25 MB, 아이콘 2 MB, 스크린샷 5 MB 까지. 응답의 url 을 아래 요청들의 downloadUrl·iconUrl·url 로 넘깁니다. 릴리스 파일은 SHA-256 이 계산되어 함께 돌아옵니다.
이름위치설명
fileform파일. 릴리스: .jar .zip .sk .mcpack .mcaddon / 이미지: .png .jpg .jpeg .webp .gif
kindformfile (기본) · icon · gallery
bash
curl -H "Authorization: Bearer $TOKEN" \
  -F "file=@build/libs/MyPlugin-1.2.0.jar" \
  https://dpplugins.com/api/published-plugin-files
# → { "url": "/api/published-plugin-files/plugin-uploads/…", "size": 182331, "sha256": "…" }
POST/api/published-plugins새 리소스 게시. 첫 릴리스를 함께 만듭니다. 성공 시 201 과 { project }.
json
{
  "name": "MyPlugin",                 // 필수, 60자
  "slug": "my-plugin",                // 필수, 3~50자, 전역 유일
  "summary": "한 줄 요약",              // 필수, 280자
  "bodyMd": "## 소개\n…",              // 필수, 마크다운
  "resourceType": "plugin",           // plugin · mod · script · datapack · resourcepack · addon
  "categories": ["utility"],          // 필수 1~5개
  "platforms": ["Paper", "Folia"],    // 필수 1~6개 (plugin: Spigot Paper Purpur Leaf Plazma Bukkit Folia Velocity BungeeCord)
  "iconUrl": "/api/published-plugin-files/plugin-icons/…",   // 선택, kind=icon 으로 올린 경로
  "licenseName": "MIT",               // 선택
  "aiUsage": "human",                 // human · ai_assisted · ai_generated · unspecified
  "workOrigin": "original",           // original · derivative · port
  "modes": ["survival"],              // 선택
  "requirements": ["Java 21"],        // 선택, 20개·120자
  "dependencies": [{ "name": "Vault", "required": true, "url": null }],   // 선택, 20개
  "websiteUrl": null, "sourceUrl": null, "discordUrl": null,
  "requiresCore": false,
  "initialVersion": "1.0.0",          // 필수
  "initialChannel": "release",        // release · beta · alpha
  "initialDownloadUrl": "/api/published-plugin-files/plugin-uploads/…",   // 필수. 업로드 경로 또는 https URL
  "initialSupportedVersions": ["1.21.4", "1.21.5"],
  "initialChangelogMd": "- 첫 공개"
}
PUT/api/published-plugins/{projectId}리소스 정보 수정. 위와 같은 본문에서 initial* 필드를 뺀 것. 내 리소스만.
DELETE/api/published-plugins/{projectId}리소스와 모든 릴리스·파일 삭제. 되돌릴 수 없습니다.
POST/api/published-plugins/{projectId}/versions릴리스 추가. 즐겨찾은 사용자에게 알림이 갑니다. 같은 버전 문자열이 있으면 409.
json
{
  "version": "1.2.0",
  "channel": "release",
  "downloadUrl": "/api/published-plugin-files/plugin-uploads/…",
  "supportedVersions": ["1.21.4"],
  "changelogMd": "- 버그 수정"
}
DELETE/api/published-plugins/{projectId}/versions/{versionId}릴리스 삭제. 업로드된 파일도 함께 지웁니다.
POST/api/published-plugins/{projectId}/images스크린샷 추가. kind=gallery 로 올린 url 만 받습니다. 최대 10장. { url, caption }
DELETE/api/published-plugins/{projectId}/images/{imageId}스크린샷 삭제.
GET/api/published-plugins/{projectId}/stats내 리소스 통계. 30일 일별 조회·다운로드, 리뷰 분포, 합계.

토큰 관리 (세션 전용)

아래 세 경로는 사이트 로그인 세션(쿠키)으로만 호출할 수 있습니다. 토큰으로 토큰을 만들 수는 없습니다.

GET/api/tokens내 토큰 목록 { tokens[{id, name, hint, createdAt, lastUsedAt, requestCount}], max }. 원본은 포함되지 않습니다.
POST/api/tokens발급. { name } → 201 { token, created, tokens }. token 은 이 응답에서만 보입니다.
DELETE/api/tokens/{id}해제.
GET/api/tokens/{id}/stats토큰 사용 통계. 최근 30일 일별 요청 수(빈 날은 0), 합계, 많이 쓴 엔드포인트 상위 8개. 엔드포인트는 식별자를 {id}·{slug}·{key} 자리표시자로 묶어 셉니다.
필드타입설명
tokenobject{id, name, hint, createdAt, lastUsedAt, requestCount}
days[]array{day(YYYY-MM-DD, UTC), count} 30개. 오래된 날부터
last30dnumber최근 30일 합계
endpoints[]array{endpoint, count}. 예: "POST /api/published-plugins/{id}/versions"

리소스 (플러그인·모드·스크립트·데이터팩·리소스팩·애드온)

커뮤니티 제작자가 게시한 공개 리소스입니다. 비공개 리소스는 어떤 응답에도 나타나지 않습니다.

GET/api/published-plugins공개 리소스 목록. 본문(bodyMd)은 싣지 않습니다. 필터가 없는 요청은 엣지에서 2분 캐시됩니다.
이름위치설명
typequeryplugin · mod · script · datapack · resourcepack · addon · model. 생략하면 plugin, all 이면 전체
categoryquery카테고리 슬러그 하나 (economy, utility …)
searchquery이름·슬러그·요약·작성자 부분 일치
bash
curl "https://dpplugins.com/api/published-plugins?type=plugin&category=economy"
필드타입설명
projects[]array리소스 배열. 최신 릴리스 순
projects[].slugstring상세 경로에 쓰는 식별자 (/plugin/{slug})
projects[].name · summarystring이름과 한 줄 요약
projects[].resourceTypestringplugin · mod · script · datapack · resourcepack · addon · model
projects[].categories · platformsstring[]카테고리 슬러그, 지원 플랫폼(Paper, Folia …)
projects[].latestVersion · latestDownloadUrlstring최신 릴리스 버전과 다운로드 경로
projects[].latestSupportedVersionsstring[]최신 릴리스가 지원하는 Minecraft 버전
projects[].downloadCount · versionCountnumber누적 다운로드, 릴리스 수
projects[].iconUrl · coverUrlstring|null아이콘, 첫 스크린샷
projects[].licenseName · aiUsage · workOriginstring라이선스, AI 사용(human·ai_assisted·ai_generated·unspecified), 원작 구분(original·derivative·port)
projects[].ownerobject게시자 {id, username, globalName, nickname, avatarUrl}
projects[].isOfficialboolean운영자 계정이 게시한 리소스인지
GET/api/published-plugins/slug/{slug}리소스 상세. 본문, 모든 릴리스, 스크린샷, 비슷한 리소스, 연결된 위키 문서를 함께 돌려줍니다.
bash
curl "https://dpplugins.com/api/published-plugins/slug/dp-guishop"
필드타입설명
projectobject목록과 같은 필드 + bodyMd, requirements, dependencies, reviewCount, reviewAverage, wiki
project.dependencies[]array{name, projectId, url, required, link}. link 는 사이트 안 리소스일 때 {resourceType, slug}
project.wikiobject|null{slug, name, url, articles[{slug, title}]}
versions[]array최신순 릴리스
versions[].version · channelstring버전 문자열, 채널(release · beta · alpha)
versions[].downloadUrlstring다운로드 경로. 사이트 업로드면 /api/published-plugin-files/… 로 시작
versions[].supportedVersionsstring[]지원 Minecraft 버전
versions[].sizeBytes · sha256number|null · string|null사이트에 올린 파일이면 크기와 SHA-256
versions[].downloadCountnumber이 버전의 다운로드 수
versions[].changelogMdstring변경 로그(마크다운)
images[]array스크린샷 {id, url, caption, sortOrder}
similar[]array카테고리가 겹치는 같은 종류의 리소스 (최대 6개, sharedTags 포함)
GET/api/published-plugin-files/{key}사이트에 업로드된 릴리스 파일·아이콘·스크린샷. downloadUrl 에 들어 있는 경로를 그대로 쓰면 됩니다. 릴리스 파일은 다운로드 수에 집계되고 Content-Disposition: attachment 로 내려옵니다. HEAD 도 받습니다.

공식 배포

DP-Plugins 가 직접 만들고 배포하는 자료입니다. 공개(public) 자료는 누구나 받을 수 있고, 판매(paid) 자료는 권한이 부여된 계정만 받을 수 있습니다. 권한 확인에는 아래 PluginHub 기기 토큰(Authorization: Bearer)이나 사이트 로그인 세션을 씁니다.

GET/api/official/projects공개 목록에 올라온 공식 자료.
필드타입설명
projects[].slug · name · summary · iconUrl · resourceTypestring기본 정보
projects[].distributionstringpublic · paid
projects[].canDownloadboolean요청한 사람이 받을 수 있는지. 익명은 public 만 true
projects[].purchaseUrlstring|nullpaid 자료의 구매 문의 링크
projects[].latestVersion · latestVersionId · latestVersionAtstring최신 버전과 다운로드에 쓰는 버전 id
GET/api/official/projects/{slug}공식 자료 상세. bodyMd, wikiUrl, 그리고 내려진(yanked) 것을 뺀 모든 버전을 돌려줍니다.
필드타입설명
versions[].idstring다운로드 경로에 쓰는 UUID
versions[].version · changelogMd · supportedVersionsstring · string · string[]버전 정보
versions[].fileName · sizeBytes · sha256string · number · string파일 정보. 받은 뒤 SHA-256 을 비교하세요
versions[].publishedAtstring게시 시각
GET/api/official/feed새 버전 피드. 업데이트 확인용으로 주기적으로 호출합니다. 마지막 serverTime 을 since 로 넘기면 그 뒤 것만 옵니다. 최대 50개.
이름위치설명
sincequeryISO 8601 시각. 생략하면 전체
bash
curl "https://dpplugins.com/api/official/feed?since=2026-11-01T00:00:00.000Z"
필드타입설명
updates[]array{slug, name, iconUrl, versionId, version, distribution, createdAt, publishedAt}
serverTimestring다음 호출의 since 로 쓸 서버 시각
GET/api/official/download/{versionId}파일 다운로드. 받을 권한이 없거나 없는 버전은 모두 404 입니다. 응답 헤더 x-content-sha256 으로 무결성을 확인할 수 있습니다. Range 요청은 지원하지 않습니다.
bash
curl -L -o plugin.jar "https://dpplugins.com/api/official/download/4f2c…"
# 판매 자료는 기기 토큰과 함께
curl -H "Authorization: Bearer <token>" -o plugin.jar "https://dpplugins.com/api/official/download/4f2c…"

PluginHub 기기 API

데스크톱 다운로더(DP-PluginHub)가 쓰는 API 입니다. 토큰 없이도 공개 자료를 읽을 수 있고, 기기를 계정에 연결하면 그 계정에 배정된 비공개 납품물까지 보입니다. 못 쓰는 토큰(해제된 기기 등)은 오류가 아니라 익명으로 처리됩니다.

기기 연결 (Device Code 방식)

POST/api/hub/device/start연결 코드를 발급받습니다. 요청 본문은 JSON 입니다.
json
// 요청
{ "deviceName": "내 PC" }

// 응답
{
  "userCode": "ABCD-1234",
  "deviceCode": "…",
  "deviceName": "내 PC",
  "verifyUrl": "https://dpplugins.com/link",
  "expiresIn": 600,
  "pollInterval": 2
}

사용자는 verifyUrl 에 로그인한 뒤 userCode 를 입력해 승인합니다.

POST/api/hub/device/pollpollInterval 초마다 호출합니다. 승인 전에는 202, 승인되면 200 과 함께 기기 토큰이 한 번 발급되고 코드는 소멸합니다. 만료·잘못된 코드는 404.
json
// 요청
{ "deviceCode": "…", "deviceName": "내 PC" }

// 202
{ "status": "pending" }

// 200
{ "status": "linked", "token": "64자리 hex" }

읽기

아래 경로는 모두 선택적으로 Authorization: Bearer <token> 헤더를 받습니다.

GET/api/hub/me토큰 뒤의 계정. 토큰이 없거나 못 쓰면 401 이 아니라 { linked: false, user: null }.
필드타입설명
linkedboolean연결 여부
userobject|null{id, username, …}
GET/api/hub/catalog이 기기가 볼 수 있는 리소스 카탈로그(공개 + 배정된 비공개).
필드타입설명
projects[]array{id, slug, name, summary, resourceType, iconUrl, isPrivate, updatedAt, latestVersion, latestVersionId, latestVersionAt}
serverTimestring서버 시각
GET/api/hub/projects/{slug}리소스 상세와 전체 버전 목록. 볼 수 없는 리소스는 404.
필드타입설명
bodyMdstring본문
versions[]array{id, version, changelogMd, supportedVersions, createdAt}
GET/api/hub/feed새 버전 피드. 공식 배포 피드와 같은 모양이며 since 를 받습니다. 최대 50개.
이름위치설명
sincequeryISO 8601 시각
GET/api/hub/download/{versionId}버전 파일 다운로드. 볼 수 없는 버전은 404. Content-Disposition: attachment; filename="{slug}-{version}.jar". Range 미지원.

서버 리스트

GET/api/servers인증된 서버 목록. 페이지당 10개.
이름위치설명
editionqueryjava · bedrock · both · all (기본 all)
searchquery이름·설명 부분 일치
onlinequery1 이면 온라인 서버만
versionqueryMC 버전. 여러 번 지정 가능(최대 5), 서버의 지원 범위에 포함되면 매칭
genrequery장르 슬러그. 여러 번 지정 가능(최대 5)
pagequery1부터
bash
curl "https://dpplugins.com/api/servers?edition=java&online=1&genre=survival&page=1"
필드타입설명
servers[]array서버 배열
servers[].id · name · edition · host · portstring · number기본 정보
servers[].genres · versionMin · versionMaxstring[] · string장르와 지원 버전 범위
servers[].description · website · discord · bannerUrl · iconUrlstring|null소개와 링크
servers[].statusobject|null{online, playersOnline, playersMax, motd, motdClean, motdHtml, favicon, versionName, software, updatedAt}
servers[].voteCount · lastRefreshAt · createdAtnumber · string추천 수, 마지막 갱신·등록 시각
servers[].ownerobject등록자 {id, username, globalName, nickname, avatarUrl}
total · page · pageSize · totalPagesnumber페이지 정보
GET/api/servers/recent-refreshes최근 상태가 갱신된 서버.
이름위치설명
limitquery개수
GET/api/servers/{id}서버 하나. 목록 항목과 같은 필드를 객체 하나로 돌려줍니다. detail 은 마크다운 상세 소개입니다.

커뮤니티

GET/api/community/boards게시판 목록. 관리자 전용 게시판은 제외됩니다.
필드타입설명
boards[]array{id, slug, name, description, category, categoryLabel, sortOrder, postCount, isAdminOnly}
GET/api/community/posts글 목록. 페이지당 15개, 본문은 싣지 않습니다.
이름위치설명
boardquery게시판 슬러그
searchquery제목·본문 부분 일치
sortquerylatest · likes · comments (기본 latest)
hashtagquery해시태그 하나
pagequery1부터
필드타입설명
posts[]array{id, title, viewCount, likeCount, commentCount, isPinned, hashtags[], createdAt, updatedAt, board{slug,name,category}, author{…}}
total · page · pageSize · totalPagesnumber페이지 정보
GET/api/community/comments/recent최근 댓글.

위키

GET/api/wiki/plugins공개 위키 목록.
이름위치설명
spacequerypublic (기본). custom 은 로그인·권한 필요
필드타입설명
plugins[]array{id, space, slug, name, summary, icon_url}
GET/api/wiki/plugins/{slug}위키 한 권과 문서 전체(본문 HTML 포함).
이름위치설명
spacequerypublic (기본)
필드타입설명
pluginobject{id, space, slug, name, summary, icon_url}
articles[]array{id, slug, title, body_html, sort_order}. body_html 은 서버에서 정화된 HTML

스킨

GET/api/skins공개 스킨 목록(최대 200).
이름위치설명
searchquery이름·설명·작성자
tagsquery태그 슬러그, 쉼표로 여러 개
필드타입설명
skins[]array{id, slug, name, description, skinUrl, model(classic·slim), license, tags[], createdAt, owner}
GET/api/skins/slug/{slug}스킨 하나.
GET/api/skins/user/{userId}한 사용자의 스킨.

기타

GET/api/tags사이트가 쓰는 태그 정의. kind 별로 묶여 있습니다 (server_genre, plugin_category, mod_category …).
필드타입설명
tagsobject{ [kind]: [{slug, labelKo, labelEn, sortOrder}] }
GET/api/points/ranking활동 포인트 랭킹. 페이지당 10명.
이름위치설명
pagequery1부터
GET/api/published-plugins/user/{userId}한 사용자가 게시한 공개 리소스 전체(모든 종류).
GET/sitemap.xml사이트맵. 모든 리소스 상세 페이지를 포함합니다.
GET/.well-known/agent-skills/index.jsonAI 에이전트용 스킬 인덱스. 릴리스 카탈로그(GitHub releases.json)와 사이트맵 위치를 알려줍니다.