API for developers

Read the public data of Spinjump from your own apps, scripts and websites, and, with a personal key, your own logbook: what you have played and what not.

OpenAPI file (YAML)

The short version

  • The API lives at https://spring.uber.space/api/v1. It speaks JSON. The complete description is the OpenAPI file: open it in Swagger UI, Postman or Insomnia, or let a generator write a client from it.
  • Public data needs no key: lists of hacks and resources, a single hack, ratings, profiles, news. Please be kind: there is a limit per address.
  • Searching needs a key: the q parameter and the rating filters are the expensive part, so they have a key and a limit.
  • Your own data needs a key with a scope. You make keys yourself, they can only read, and you can delete them any time.

Try it, without a key

curl "https://spring.uber.space/api/v1/hacks?category=Kaizo&sort=fun"
curl "https://spring.uber.space/api/v1/hacks/gearwork-gardens"

A list has items, page and total. Every hack has fun and difficulty (averages from 1 to 10), the number of downloads, screenshots and the versions with their patch addresses. Spinjump only hosts patches, never ROMs.

Get a key

Sign in, open your settings and create a key under “API keys”. It is shown once, so copy it then. Send it in a header:

Authorization: Bearer rh_YOUR_KEY
ScopeWhat it allows
library:readYour logbook: GET /me/library and GET /hacks/{slug}/tracking, with your dates and notes.
profile:readYour account: GET /me. Never your e-mail address.
no scopeOnly searching.

Treat a key like a password. Anything that has it can read what its scopes allow. You can have five keys, one per app is a good habit, and deleting a key stops it at once.

Search

curl -H "Authorization: Bearer rh_YOUR_KEY" "https://spring.uber.space/api/v1/hacks?q=gear"

Without a key you get 401 with the code key_required. Searching works on /hacks, /resources and /announcements. On /hacks you can also filter by rating (minFun, maxFun, minDifficulty, maxDifficulty).

Example: what have I played?

Make a key with library:read. Every hack has one of four states in your logbook:

  • want: you want to play it
  • playing: you are playing it
  • dropped: you gave up
  • beaten: you finished it
curl -H "Authorization: Bearer rh_YOUR_KEY" "https://spring.uber.space/api/v1/me/library?state=beaten"
const res = await fetch("https://spring.uber.space/api/v1/me/library?state=beaten", {
  headers: { Authorization: "Bearer " + key }
});
const beaten = await res.json();
console.log(beaten.map((entry) => entry.hack.title));

The answer is a list of entries like this one, newest change first:

{
  "hack": { "slug": "gearwork-gardens", "title": "Gearwork Gardens", "fun": 8.3, "difficulty": 2.3, "downloads": 40, "…": "…" },
  "state": "beaten",
  "startedOn": "2026-10-02",
  "finishedOn": "2026-10-14",
  "note": "The last level is worth the wait."
}

Add ?state=playing (or want, dropped, beaten) to filter. For one hack, GET /hacks/{slug}/tracking answers with the same fields; without an entry state is null.

Limits

WhatLimit
Open reads without a key300 per 10 minutes per address
Searching300 per hour per member
Everything with a key1800 per hour per member

Over a limit the answer is 429 with retryAfter (seconds) and a Retry-After header. Open answers carry an ETag and may be cached for a minute: ask again with If-None-Match and you get a short 304 when nothing changed. That is the friendliest way to poll.

From a web page

Any website may call the API from a browser (CORS is open for reading, and cookies are never sent). Do not put a key into a page other people open: everyone who opens it can read the key. For your own use, a script on your own computer or a server is the place for it.

What is never available

E-mail addresses, who follows whom, which hacks someone dropped, other people’s notes and dates, anonymous ratings with a name, and everything about moderation. Only public data leaves Spinjump, or your own data with your own key.

Good to know

  • /api/v1 stays compatible: new fields and paths may appear, nothing is removed or renamed. A change that breaks this gets a new version.
  • Errors are always { code, message }, plus fields for invalid parameters.
  • If you show Spinjump’s data, please credit Spinjump and link back. Downloading a patch counts as a download.
Spinjump · Super Mario World hacks Patches only. Spinjump never hosts ROMs. API for developers