StackedHost API — Public Endpoints

Public API

Read-only access to launcher content — instances, files and news — for the StackedHost custom Minecraft launcher platform. These endpoints need no authentication and return a filtered, public-safe projection of the data.

✓ No auth required Base URL https://stackedhost-d1.<subdomain>.workers.dev

Response format

// collections
{ "success": true, "results": [ /* ... */ ] }
// single resource
{ "success": true, "data": { /* ... */ } }
// errors
{ "success": false, "error": "message" }

Public instance shape

{
  "id": "8-byte-hex", "launcher_id": "lns", "slug": "pack", "title": "Pack",
  "minecraft_version": "1.20.1", "server": "mc.example",
  "loader": { "type": "fabric", "build": "latest", "enabled": true },
  "downloads": 42, "locked": false,
  "java_version": 17, "suggested_ram": 4096,
  "icon": "lns/instance/<id>/resource/icon.png",
  "landscape": null, "poster": null, "animation": null
}

iPrivate fields (code, hide, whitelists, file lists, timestamps) and hidden instances are never exposed publicly.

GET /launchers/:lid/instances

List the visible (non-hidden) instances of a launcher.

Query parameters

Param	Default	Description
`limit`	20	Page size, 1–100.
`offset`	0	Items to skip.
`sort_by`	title	One of `title`, `slug`, `downloads`.
`order`	ASC	`ASC` or `DESC`.

Example

curl "https://stackedhost-d1.example.workers.dev/launchers/lns/instances?limit=2&sort_by=downloads&order=DESC"

{ "success": true, "results": [ /* public instance objects */ ] }

GET /launchers/:lid/instances/:idOrSlug

Fetch a single instance of a launcher by its id or slug.

Example

curl "https://stackedhost-d1.example.workers.dev/launchers/lns/instances/pack"

{ "success": true, "data": { /* public instance */ } }

iReturns 404 if the instance does not exist or is hidden.

GET /instances/:id

Fetch a single instance by id without knowing its launcher.

Example

curl "https://stackedhost-d1.example.workers.dev/instances/cbe020da111b0cde"

POST /instances/resolve

Resolve an access code only among the supplied launchers. Returns public fields, including for hidden instances and authenticated callers.

{ "code": "SECRET", "launcher_ids": ["lns", "another-launcher"] }

Send Content-Type: application/json. Supply 1–20 launcher IDs. Multiple matches return 409 Ambiguous code. Fetch files separately using the returned launcher and instance IDs plus the code.

Persistent D1 quotas: 30 attempts/IP and 120 attempts/launcher per 60-second window. Every distinct supplied ID is charged. Temporary blocks return 429 with Retry-After; blocked requests do not extend the window. Public billing restrictions always apply.

See complete validation and failure behavior. The previous launcher-scoped GET resolver is removed.

GET /launchers/:lid/instances/:id/files

List the downloadable files declared on an instance.

Query parameters

Param	Required	Description
`code`	locked only	Access code — required when the instance is `locked`.

Example

curl "https://stackedhost-d1.example.workers.dev/launchers/lns/instances/inst1/files?code=SECRET"

{ "success": true, "results": [
  { "name": "core", "downloads": [ "lns/instance/inst1/file/a.zip" ] }
] }

iFor locked instances, a missing or wrong code returns 401.

POST /instances/:id/downloads

Example

curl -X POST "https://stackedhost-d1.example.workers.dev/instances/inst1/downloads"

{ "success": true, "data": { "downloads": 43 } }

GET /launchers/:lid/news

List a launcher's published news, newest first.

Example

curl "https://stackedhost-d1.example.workers.dev/launchers/lns/news"

{ "success": true, "results": [
  { "id": "lns-news-0", "launcher_id": "lns", "title": "Hello",
    "body": "Body text", "published": true, "created_at": 1750000000 }
] }

iOnly published news is visible to the public; unpublished drafts require authentication.