Developers · API v1

The PacksMC API

Browse and repost the PacksMC catalog — full pack metadata, screenshots, credits, and stats. Free for every account. The only catch: every download link points back to packsmc.com.

Get an API key Quickstart

Language

Introduction

The PacksMC API is a read-first catalog surface. Use it to feature our packs on your own site, Discord bot, or browser extension — you get the same information a visitor sees on a pack's detail page.

The golden rule: the download link always goes to packsmc.com. Every pack carries a download_url pointing at its page on our site. The API never returns a raw file URL — so download counts, creator attribution and earnings, link lockers, and Packs+ gates all keep working when your users download.

Base URL: https://packsmc.com
Auth: Authorization: Bearer pmc_…
Format: JSON · UTF-8
CORS: Open (*) — callable from the browser

Quickstart

Sign in — any account works, no Packs+ required.
Open API Access and create a key. The pmc_… secret is shown once.
Send it as a Bearer token on every request:

cURL

curl "https://packsmc.com/api/v1/packs?limit=5" \
  -H "Authorization: Bearer pmc_YOUR_KEY"

Authentication

Every request needs a bearer token. Keys are hashed at rest — we can't recover a lost secret, so store it securely. You can hold several keys and revoke any of them from the API Access page.

Authorization: Bearer pmc_YOUR_KEY

Rate limits & quotas

Catalog access is free for every account. Packs+ raises the daily quota and unlocks the converter.

Limit	Free	Packs+
Per-key burst	60 / min	60 / min
Per-IP burst	120 / min	120 / min
Daily quota (per key)	1,000 / 24h	50,000 / 24h
POST /convert	✗	✓ · 10/min · 600 MB

Over a limit returns HTTP 429 with a Retry-After header (seconds). The per-IP cap applies no matter how many keys you rotate through. Every call is logged; mirroring the whole catalog or stripping creator attribution can get a key revoked.

Errors

All errors share one shape:

JSON

{ "error": { "code": "rate_limited", "message": "Rate limit exceeded (60 req / 60s)" } }

HTTP	code	Meaning
400	invalid_sort	Unknown sort value
401	unauthenticated	Missing / invalid / revoked key
403	packs_plus_required	Endpoint needs an active Packs+ subscription
404	not_found	Pack doesn't exist, is private, or isn't published
429	rate_limited · ip_rate_limit · daily_quota	Back off for Retry-After seconds
500	db_error	Transient — retry with backoff

Endpoints

GET/api/v1/me

Your identity

Confirms your key works and reports your tier, limits, and capabilities. A good health check.

Request

cURL

curl "https://packsmc.com/api/v1/me" \
  -H "Authorization: Bearer pmc_YOUR_KEY"

Response

JSON

{
  "id": "5a1f...",
  "username": "Steve",
  "display_name": "Steve",
  "verified": true,
  "packs_plus": false,
  "tier": "free",
  "limits": { "daily_quota": 1000, "per_minute": 60, "per_ip_per_minute": 120 },
  "counts": { "total_packs": 12, "total_downloads": 8421 },
  "can": {
    "list_packs": true,
    "view_pack_metadata": true,
    "get_pack_web_urls": true,
    "submit_conversions": false
  }
}

GET/api/v1/packs

List packs

Paginated catalog of public, ready packs — full display metadata for each so you can repost them. Every item carries a download_url pointing at its packsmc.com page.

Param	Type	Description
limit	integer	1–100 (default 25)
cursor	string	next_cursor from the previous page (sort=recent only)
q	string	Full-text search over name + description + category (min 2 chars)
resolution	string	Exact match, e.g. 16x
author	string	Filter to one creator by Minecraft username
sort	string	recent (default) · downloads · likes

Request

cURL

curl "https://packsmc.com/api/v1/packs?sort=downloads&limit=10" \
  -H "Authorization: Bearer pmc_YOUR_KEY"

Response

JSON

{
  "data": [
    {
      "id": "f1d...",
      "slug": "blood-default-1-9",
      "name": "Blood Default 1.9",
      "resolution": "16x",
      "gamemodes": ["PVP_UHC"],
      "mc_versions": ["1.8.9", "1.21.4"],
      "thumbnail_url": "https://...",
      "gallery": ["https://.../1.webp", "https://.../2.webp"],
      "downloads": 8421,
      "likes": 312,
      "views": 40233,
      "file_size_bytes": 2118041,
      "license": { "code": "CREDIT_REQUIRED", "requires_credit": true },
      "author": { "username": "Steve", "verified": true },
      "download_url": "https://packsmc.com/pack/blood-default-1-9"
    }
  ],
  "next_cursor": "2026-05-04T12:01:00.000Z"
}

GET/api/v1/packs/{id}

Pack details

Everything on a pack's detail page — by UUID or slug. Description, credited creators, tags, the full screenshot gallery, per-version availability, license terms, community, and stats.

Request

cURL

curl "https://packsmc.com/api/v1/packs/blood-default-1-9" \
  -H "Authorization: Bearer pmc_YOUR_KEY"

Response

JSON

{
  "id": "f1d...",
  "slug": "blood-default-1-9",
  "name": "Blood Default 1.9",
  "description": "Clean red PvP edit...",
  "resolution": "16x",
  "gamemodes": ["PVP_UHC"],
  "gallery": ["https://.../1.webp", "https://.../2.webp"],
  "tags": ["red", "clean", "uhc"],
  "credits": [{ "username": "Alex", "role": "collaborator", "verified": false }],
  "license": { "code": "CREDIT_REQUIRED", "requires_credit": true, "allows_redistribution": true },
  "downloads": 8421, "likes": 312, "views": 40233,
  "is_exclusive": false,
  "versions": [
    { "mc_version": "1.21.4", "verified_safe": true, "created_at": "2026-04-01T00:00:00.000Z" }
  ],
  "author": { "username": "Steve", "display_name": "Steve", "verified": true },
  "download_url": "https://packsmc.com/pack/blood-default-1-9"
}

GET/api/v1/packs/{id}/download

Download link

Returns the canonical download link. You rarely need this — download_url is already on every pack object — but it's here for a direct lookup.

Request

cURL

curl "https://packsmc.com/api/v1/packs/f1d.../download" \
  -H "Authorization: Bearer pmc_YOUR_KEY"

Response

JSON

{
  "pack_id": "f1d...",
  "download_url": "https://packsmc.com/pack/blood-default-1-9",
  "web_url": "https://packsmc.com/pack/blood-default-1-9",
  "requires_packs_plus": false,
  "instructions": "Send the user to download_url. Downloads must flow through the PacksMC site - the API does not issue file URLs."
}

POST/api/v1/convertPacks+

Convert a pack

Convert a Java .zip to another Minecraft version (or Bedrock). We host the result on a one-hour download page instead of streaming the file back. Packs+ keys only; 10 req/min; 600 MB max.

Param	Type	Description
file*	file	Source .zip (max 600 MB)
target_version*	string	MC version (e.g. 1.21.4) or bedrock

Request

cURL

curl "https://packsmc.com/api/v1/convert" \
  -H "Authorization: Bearer pmc_YOUR_KEY" \
  -F "file=@my_pack.zip" \
  -F "target_version=1.21.4"

Response

JSON

{
  "job_id": "9af7c3b1...",
  "download_page": "https://packsmc.com/api-convert/9af7c3b1...",
  "filename": "my_pack_1.21.4.zip",
  "size_bytes": 4823100,
  "target_version": "1.21.4",
  "expires_at": "2026-05-11T13:42:00.000Z"
}

Objects

Pack object

Returned by the list (summary) and detail (adds the ★ fields) endpoints.

Field	Type	Notes
id	string	Pack UUID
slug	string	SEO slug — use in URLs
name	string	Pack name
description	string	Creator description (may contain markdown)
resolution	string	e.g. 16x
gamemodes	string[]	Category split into clean tags
mc_versions	string[]	Author-declared versions (we auto-convert to others)
thumbnail_url	string	Card image
gallery	string[]	Ordered screenshot URLs. Exclusive packs → thumbnail only
video_url	string	YouTube / social link, if any
downloads / likes / views	number	Lifetime counts
file_size_bytes	number	Pack size in bytes
license	object	The creator's stated terms — see License object
is_exclusive	boolean	Packs+-exclusive or in early access
trending_award	object	{ peak_rank, achieved_at } — best rank ever reached, or null
colors	object	{ accent, name, tags[] } palette, or null
author	object	{ username, display_name, avatar_url, verified }
download_url	string	The packsmc.com page — send users here to download
tags ★	string[]	Free-form creator tags
credits ★	object[]	{ username, display_name, verified, role }
community ★	object	{ name, slug, icon_url } or null
versions ★	object[]	{ mc_version, verified_safe, created_at } per build
features ★	string[]	Detected feature tags (optifine sky, custom GUI…)

License object

Field	Type	Notes
code	string	ALL_RIGHTS_RESERVED · CREDIT_REQUIRED · FREE_TO_USE · FREE_NO_REDIST · CUSTOM
label	string	Human-readable label
description	string	Full terms blurb
allows_redistribution	boolean	null for CUSTOM (read description)
requires_credit	boolean	null for CUSTOM

Reposting & licensing

This API is the licensed way to feature PacksMC packs elsewhere. You may display the metadata it returns and link each pack — as long as the download goes to download_url.

Re-hosting the pack files on another server is not authorized unless the creator'slicense permits it. Unauthorized copies are subject to DMCA takedown under PacksMC Protection. Check license before you rehost, and keep author / credits intact.

Need an endpoint that isn't here? Tell us what you'd build.