0xDocs 0x.limo

Docs / REST API

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

text
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

LimitOn 0x.limo
Storage quota per developer (all sites and versions)2048 MiB
Largest file64 MiB
Files per version5000
Sites per developer20
Site name3 to 40 characters a-z 0-9 -, not starting or ending with -
Blocked file typesexe 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):

bashtested
curl -s https://api.0x.limo/v1/hosting/config
json
{"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/ and swarm/ (and the reserved 0x.json, 0x-sw.js, 0x/);
  • a version without index.html at 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.

RouteDoes
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/tokensyour 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/methe caller, via (publish_token or access_token), usage and limits
bashtested
curl -s https://api.0x.limo/v1/hosting/me -H "Authorization: Bearer $ZEROX_TOKEN"
json
{"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.

text
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

bash
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

bash
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"]}
}'
json
{"site": "neon-drift", "version": 3, "state": "pending", "resumed": false, "files": 2, "bytes": 89743,
 "missing": ["60303ae22b998861bce3b28f33eec1be758a213c86c93c076dbe9f558c11c752"]}
  • files lists 1 to 5000 entries, each with a relative path, the lowercase hex sha256 of its bytes and its size.
  • If a pending version with exactly the same files exists, it is resumed (resumed: true), so a failed upload can simply run again.
  • missing lists 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 gets 413.

#3. Upload the missing files

bash
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

bash
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.

json
{"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.
  • swarm counts the files and bytes the swarm manifest covers. boot: false means your index.html doesn'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

RouteAuthReturns
GET /v1/hosting/sitestokenyour sites, each with its versions
GET /v1/hosting/sites/{site}public{site, owner, name, created_at, latest, versions}
GET /v1/hosting/sites/{site}/versionspublic{site, owner, versions}
GET /v1/hosting/sites/{site}/versions/{n}publicone version: {version, state, origin, manifest_sha256, files, bytes, created_at, finalized_at, site, owner}
GET /v1/hosting/paid-sitespublicthe 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

RouteAuthReturns
GET /v1/hosting/sites/{site}/policytoken, your sitethe policy each version is served with
GET /v1/hosting/csp-reportstokenwhat the policy blocked (or would block) across your sites (?version=&days=30)
GET /v1/hosting/sites/{site}/csp-reportstoken, your sitethe same for one site
GET /v1/hosting/policy/{site}/{n}publicthat version's headers, as the front applies them

CSP reports and policy explains them.

#Errors

Statuserror
400site: 3-40 characters a-z, 0-9 and '-', ..., files: [{path, sha256, size}], bad version, blob name is its sha256 (64 lowercase hex digits)
401invalid or expired token
403sign in (0x login) to mint a publish token (minting with a publish token), at most 20 sites per developer
404no such site, no such site of yours, no such version, no such token, no such hosting route
409that 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
429too many publish tokens minted: try again later (+ retry_after_ms)
413a version has 1 to 5000 files, over your hosting quota (...)
422upload refused (+ problems), the site builder refused this version (+ findings)
503temporarily unavailable