Hosting and versions
The /v1/hosting API behind 0x publish — sites, immutable versions, content-addressed uploads, finalize, quota and limits, publish tokens and the security policy of each version.
Hosting turns a folder with a built web game into an immutable, swarm-enabled site version at
https://<site>-play.0x.limo/sites/<site>/<version>/Each site gets its own origin (<site>-play.0x.limo), so one game can't read another's storage,
cookies or frames. 0x publish and the upload page at https://api.0x.limo/hosting/ use this API.
You can also call it yourself, from CI for example.
Note
This page is the guide: limits, auth and the publish flow step by step. Every /v1/hosting route, with its parameters and responses, is in the generated REST reference: Content and depots.
#Limits
| Limit | On 0x.limo |
|---|---|
| Storage quota per developer (all sites and versions) | 2048 MiB |
| Largest file | 64 MiB |
| Files per version | 5000 |
| Sites per developer | 20 |
| Site name | 3 to 40 characters a-z 0-9 -, not starting or ending with - |
| Blocked file types | exe dll com scr msi msix bat cmd ps1 vbs lnk reg so dylib app dmg pkg deb rpm appimage apk ipa jar sh |
Every other file type is published as it is, game data and assets of every format included.
GET /v1/hosting/config returns the live numbers (public):
curl -s https://api.0x.limo/v1/hosting/config{"sites_url": "https://{site}-play.0x.limo/sites/", "tracker": "wss://play.0x.limo/p2p/tracker",
"limits": {"quota_bytes": 2147483648, "max_file_bytes": 67108864, "max_files": 5000, "max_sites": 20,
"blocked_extensions": ["exe", "dll", "..."]}}Some paths are refused:
- hidden files (any path segment starting with
.); - paths that 0x writes into every version itself:
x1.json,x1-sw.js,x1/andswarm/(and the reserved0x.json,0x-sw.js,0x/); - a version without
index.htmlat the top.
Some site names are reserved for 0x's own hosts (api, play, docs, store, admin and others).
Creating a site with one of them gets 409 that site name is reserved.
#Auth
Every write takes either an access token or a 0xpub_ publish token. Publish tokens are
long-lived and valid on hosting, listings and script packages only, so use them in CI. Creators manage
them at Developer › Tokens (/dev/tokens), which calls these routes.
| Route | Does |
|---|---|
POST /v1/hosting/tokens {name} | mint a publish token (needs an access token). The token appears once in the response, with scopes. At most 25 live per account (409); rate-limited per account (429, retry_after_ms) |
GET /v1/hosting/tokens | your tokens: id, name, created_at, last_used_at, revoked_at, scopes (hosting, listings, scripts); active_max |
DELETE /v1/hosting/tokens/{id} | revoke one → {revoked: true} |
GET /v1/hosting/me | the caller, via (publish_token or access_token), usage and limits |
curl -s https://api.0x.limo/v1/hosting/me -H "Authorization: Bearer $ZEROX_TOKEN"{"steamid": "76561197960287930", "persona_name": "alice", "via": "access_token",
"usage": {"bytes": 18874368, "sites": 2},
"limits": {"quota_bytes": 2147483648, "max_file_bytes": 67108864, "max_files": 5000, "max_sites": 20}}#The publish flow
Publishing is content-addressed. You send the list of files with their SHA-256 hashes, upload only the files the service doesn't already have, then finalize.
POST /v1/hosting/sites create the site (once)
POST /v1/hosting/sites/{site}/versions open version n: {files} -> {version, missing}
PUT /v1/hosting/blobs/{sha256} (raw bytes) upload each missing file
POST /v1/hosting/sites/{site}/versions/{n}/finalize build and publish (immutable)#1. Create a site
curl -s https://api.0x.limo/v1/hosting/sites -H "Authorization: Bearer $ZEROX_PUBLISH_TOKEN" \
-H 'Content-Type: application/json' -d '{"site": "neon-drift", "name": "Neon Drift"}'201 returns the site record. Errors: 409 that site name is taken, 409 that site name is reserved,
403 at most 20 sites per developer and 400 for a bad name.
#2. Open a version
curl -s https://api.0x.limo/v1/hosting/sites/neon-drift/versions \
-H "Authorization: Bearer $ZEROX_PUBLISH_TOKEN" -H 'Content-Type: application/json' -d '{
"files": [
{"path": "index.html", "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "size": 1532},
{"path": "game.js", "sha256": "60303ae22b998861bce3b28f33eec1be758a213c86c93c076dbe9f558c11c752", "size": 88211}
],
"csp": {"connect": ["wss://rt.example.com"], "img": ["https://*.cdn.example.com"]}
}'{"site": "neon-drift", "version": 3, "state": "pending", "resumed": false, "files": 2, "bytes": 89743,
"missing": ["60303ae22b998861bce3b28f33eec1be758a213c86c93c076dbe9f558c11c752"]}fileslists 1 to 5000 entries, each with a relativepath, the lowercase hexsha256of its bytes and itssize.- If a pending version with exactly the same files exists, it is resumed (
resumed: true), so a failed upload can simply run again. missinglists the hashes you still have to upload. Files any version already stored are not sent again, so a new version that changes one file uploads one file.csp(optional) declares what the game loads from outside its origin; see CSP reports and policy.- A list that breaks the rules gets
422 {"error": "upload refused", "problems": [...]}(at most 50 problems). Going over the quota gets413.
#3. Upload the missing files
curl -s -X PUT https://api.0x.limo/v1/hosting/blobs/60303ae22b998861bce3b28f33eec1be758a213c86c93c076dbe9f558c11c752 \
-H "Authorization: Bearer $ZEROX_PUBLISH_TOKEN" --data-binary @game.js
# {"sha256": "60303ae2...", "stored": true}The service checks the size and the hash against the bytes. Errors: 400 size ... does not match,
400 sha256 does not match the bytes, and 404 that hash is in none of your pending versions.
A blob that is already stored answers stored: false. Uploads may run in parallel.
#4. Finalize
curl -s -X POST https://api.0x.limo/v1/hosting/sites/neon-drift/versions/3/finalize \
-H "Authorization: Bearer $ZEROX_PUBLISH_TOKEN"Finalize assembles the version and adds the 0x runtime (x1.json, the x1-sw.js service worker and
x1/). It also builds the swarm manifest, so players can fetch the files from each other, hashes the
inline scripts and styles for the security policy, and publishes the version. A published version
never changes.
{"site": "neon-drift", "version": 3, "origin": "https://neon-drift-play.0x.limo/sites/neon-drift/3/",
"manifest_sha256": "c0ffee...", "swarm": {"files": 2, "bytes": 89743}, "warnings": [], "boot": true, "origin_only": false,
"csp": {"mode": "enforce", "declared": {"connect": ["wss://rt.example.com"]}, "warnings": [],
"inline_hashes": {"script": 1, "style": 0},
"content_security_policy": "default-src 'self'; ...", "report_only": "...", "permissions_policy": "..."}}409 {"error": "files still to upload", "missing": [...]}: upload those first.422 {"error": "the site builder refused this version", "findings": [...]}: fix the files and open a new version.swarmcounts the files and bytes the swarm manifest covers.boot: falsemeans yourindex.htmldoesn't load./x1/boot.js, so the page loads everything from the origin and players don't share it. Add<script src="./x1/boot.js"></script>to turn the swarm on.- Finalizing a version that is already final answers
{already_final: true, version}. origin_only: true: the site belongs to a paid game. Its versions get no swarm manifest, so nothing of it is shared player to player, and only owners are let in.
#Reading sites and versions
| Route | Auth | Returns |
|---|---|---|
GET /v1/hosting/sites | token | your sites, each with its versions |
GET /v1/hosting/sites/{site} | public | {site, owner, name, created_at, latest, versions} |
GET /v1/hosting/sites/{site}/versions | public | {site, owner, versions} |
GET /v1/hosting/sites/{site}/versions/{n} | public | one version: {version, state, origin, manifest_sha256, files, bytes, created_at, finalized_at, site, owner} |
GET /v1/hosting/paid-sites | public | the sites of paid games: {sites: {"<site>": {appid, id, name, subscription?}}, at} |
A version's state is pending until it is finalized and final afterwards. Only final versions
have an origin.
#Security policy routes
| Route | Auth | Returns |
|---|---|---|
GET /v1/hosting/sites/{site}/policy | token, your site | the policy each version is served with |
GET /v1/hosting/csp-reports | token | what the policy blocked (or would block) across your sites (?version=&days=30) |
GET /v1/hosting/sites/{site}/csp-reports | token, your site | the same for one site |
GET /v1/hosting/policy/{site}/{n} | public | that version's headers, as the front applies them |
CSP reports and policy explains them.
#Errors
| Status | error |
|---|---|
| 400 | site: 3-40 characters a-z, 0-9 and '-', ..., files: [{path, sha256, size}], bad version, blob name is its sha256 (64 lowercase hex digits) |
| 401 | invalid or expired token |
| 403 | sign in (0x login) to mint a publish token (minting with a publish token), at most 20 sites per developer |
| 404 | no such site, no such site of yours, no such version, no such token, no such hosting route |
| 409 | that site name is taken, that site name is reserved, files still to upload, N publish tokens are live (at most 25): revoke one you no longer use first |
| 429 | too many publish tokens minted: try again later (+ retry_after_ms) |
| 413 | a version has 1 to 5000 files, over your hosting quota (...) |
| 422 | upload refused (+ problems), the site builder refused this version (+ findings) |
| 503 | temporarily unavailable |
