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.
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
qparameter 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 | Scope | What it allows |
|---|---|
library:read | Your logbook: GET /me/library and GET /hacks/{slug}/tracking, with your dates and notes. |
profile:read | Your account: GET /me. Never your e-mail address. |
| no scope | Only 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 itplaying: you are playing itdropped: you gave upbeaten: 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
| What | Limit |
|---|---|
| Open reads without a key | 300 per 10 minutes per address |
| Searching | 300 per hour per member |
| Everything with a key | 1800 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/v1stays 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 }, plusfieldsfor invalid parameters. - If you show Spinjump’s data, please credit Spinjump and link back. Downloading a patch counts as a download.