Public API
Everything public on Sonic PHP can also be read as JSON, with no account and no key: the levels (and their content, block by block), the tiles and their collisions, the sprites, the musics and sound effects, the players, the games played and the history of each creation. Enough to make a gallery of levels, a bot, statistics, a music player, another editor…
It is read only and only gives what a visitor sees on the site: never a private creation or one in a trash, nor an e-mail address.
Documentation
Swagger UI ReDoc Scalar OpenAPI (JSON)
Every route, field and parameter is described there, with examples. "Try it out" in Swagger UI calls the API for real.
Get started
curl
curl -H "Accept: application/json" "https://sonic.mimichat.fr/api/public/levels?order=created&itemsPerPage=5"
JavaScript (from any web page)
const levels = await fetch('https://sonic.mimichat.fr/api/public/levels', { headers: { Accept: 'application/json' } }).then(r => r.json());
for (const level of levels) console.log(level.name, level.authorName, level.links.play);
Python
import requests
level = requests.get('https://sonic.mimichat.fr/api/public/levels/12', headers={'Accept': 'application/json'}).json()
grid = requests.get('https://sonic.mimichat.fr/api/public' + level['links']['map'].removeprefix('/api/public'), headers={'Accept': 'application/json'}).json()
print(level['name'], len(grid['blocks']), 'x', len(grid['blocks'][0]))
What is in it
| Address | What |
|---|---|
/levels | The public levels (filters: author, tileset, name, order) |
/levels/{id} | A level: tiles, sprites, music, sound effects, size, start, rings, links (page, play, thumbnail) |
/levels/{id}/map | Its content: the grid of blocks, the objects, the start |
/tilesets | The 7 zones of the game and the public tiles (filters: author, zone) |
/tilesets/{id}/blocks | Each block: place in the image, collision, behaviour |
/sprites | The public sprites (the redrawn sheets, as PNG) |
/sounds | The public musics and sound effects (filter: kind), the score and the WAV |
/players | The players, as their public profile |
/replays | The games played (filters: player, kind, level), to watch in the game |
/levels/{id}/history | The history of a creation (also /tilesets, /sprites, /sounds) |
The rules
- Formats: JSON-LD / Hydra by default (
Accept: application/ld+json: with the total and the links of the pages), or plain JSON (Accept: application/json). Links between resources are addresses of the API, like/api/public/players/SONIC; pictures and sounds are addresses of the site, inlinks. - Pages:
?page=2&itemsPerPage=50(30 by default, 100 at most). - Errors as Problem Details: 404 (unknown or not public), 422 (wrong parameter:
detailsays which), 429 (too many requests). - Limit per IP address: 600 requests at once at most, then one a second. Beyond: 429 and the
Retry-Afterheader (in seconds). - CORS open, no cookie; answers may be cached for 60 seconds.
- These are the players' creations: credit their author (
authorName) and link to their page (links.page).
To make levels on one's account with an AI (writing, with a key), see the MCP server.