HTTP API

The platform exposes a small JSON API under /api. Read routes are public and keyless; write routes rely on wallet signatures rather than accounts.

Overview#

Library#

Returns the whole asset catalogue as produced by the pipeline. The route is static (force-static): it is computed at build time and served from cache.

{
  assets: {
    id: string
    name: string
    category: 'characters' | 'creatures' | 'vehicles' | 'architecture' | 'nature'
            | 'weapons' | 'furniture' | 'props' | 'textures' | 'hdri' | 'effects' | 'audio'
    style: 'realistic' | 'stylized' | 'cartoon' | 'lowpoly' | 'voxel'
    tags: string[]
    source: string
    author: string
    sourceUrl: string
    license: 'CC0' | 'CC-BY' | 'CC-BY-SA' | 'MIT' | 'Other'
    attributionRequired: boolean
    attribution: string
    url: string            // GLB, texture set, .hdr or audio file
    thumb: string
    turntable?: string
    polycount?: number
    bytes: number
    rigged: boolean
    animations: string[]
    size: [number, number, number]
    height: number
    importedAt: string
    featured?: boolean
    maps?: Record<string, string>   // textures only
  }[]
}

curl https://buildsandbox.app/api/library

const { assets } = await fetch('https://buildsandbox.app/api/library').then((r) => r.json())
const rigged = assets.filter((a) => a.rigged && a.license === 'CC0')

Games#

List games#

Published games followed by the templates, each with its play statistics.

{
  live: boolean            // false in draft mode (no storage)
  games: {
    id: string             // on-chain id, "d-<hash prefix>" in draft registry, or "tpl-*"
    title: string
    description: string
    mode: GameMode
    creator: string        // address, or "sandbox" for templates
    cover: string | null
    uri: string            // where the document lives
    hash: string           // keccak256 of the canonical document
    version: number
    publishedAt: number    // ms
    updatedAt: number      // ms
    hidden: boolean
    onchain: boolean       // true once registered in Sandbox.sol
    tx?: string
    remixOf?: string
    plays: number
    players: number
  }[]
}

curl https://buildsandbox.app/api/games?mode=race&sort=played

const res = await fetch('https://buildsandbox.app/api/games?mode=race&sort=played')
const { games } = await res.json()
console.log(games[0].title, games[0].plays)

Get a game#

{
  card: GameCard & { plays: number; players: number; anon: number }
  doc: SandboxGame | null
  board: { address: string; score: number; at: number }[]   // best score per wallet, top 20
}

Answers 404 when the game does not exist, or when ?doc=1 is asked and the document is missing. The document format is described in Scene format.

curl https://buildsandbox.app/api/games/tpl-hunt?doc=1

const doc = await fetch('https://buildsandbox.app/api/games/tpl-hunt?doc=1').then((r) => r.json())
console.log(doc.meta.mode, doc.entities.length)

Likes#

{ "likes": { "tpl-race": 12, "qt-t-rex": 4 } }

Counts come from a single storage listing, kept 30 seconds in memory and served with cache-control: public, max-age=20.

Body { id, address? }. One like per visitor and target: the wallet address when given, otherwise a salted hash of the IP. Answers { ok: true }, or 400 for a bad id.

Season and rewards#

The current epoch (a 24-hour window), the standings of the current and previous epochs, the settlements already posted and, when the contract is deployed, its treasury state.

{
  live: boolean
  epoch: number
  start: number            // ms
  end: number              // ms
  current: Standing[]      // sorted by weight
  previous: Standing[]
  settlements: {
    epoch: number
    amountWei: string
    totalWeight: number
    rows: { id, title, creator, weight, players, plays }[]
    tx: string
    at: number
  }[]
  treasury: { balance: string; reserved: string; epoch: number } | null
}

interface Standing {
  id: string; title: string; creator: string; mode: GameMode
  cover: string | null; weight: number; players: number; plays: number
}

Weight is expressed in hundredths (a weight of 1 is 100). The formula is explained in Epoch rewards.

Publishing#

Publishing takes two calls. The studio chains them for you; they are documented here for third-party tools.

1. Upload the document#

Body { doc, cover? }, where cover is a PNG data URL of 2 MB at most. The document is validated, hashed and stored under its hash. Response { hash, uri, cover }.

2. Register the card#

Makes the game visible on the platform. Two paths depending on whether the on-chain registry is deployed.

Sandbox publish
title: <title>
hash: <0x…>

The publishing flow in the studio

Plays#

Sent at the end of every run. Tied to a wallet — by the sitting’s session signature or by the signature of the run itself — it counts fully toward the game’s weight for the current 24-hour epoch; only the run signature can improve the wallet’s best score on the board. Anonymous, it counts a tenth.

Sandbox session
game: <id>
at: <at>

Sandbox play
game: <id>
score: <score>
at: <at>

{ "ok": true, "live": true, "signed": true, "ranked": true, "improved": false }

Errors: 400 malformed or stale play, 401 bad signature or stale session, 404 unknown game. In draft mode the route answers { ok: false, live: false }.

AI 3D generation#

Body { kind, prompt?, imageUrl?, quality?, textured?, rig?, provider?, address, payTx }. payTx is the token transfer to the treasury; it is checked on-chain and works once. Response { job, quota }.

Lists a wallet’s jobs and returns { jobs, providers, quota, limit, open }: which providers have a key, the quota used and whether generation is open.

Polls the provider while the job runs, then returns { job } with status (queued, running, done, failed), progress from 0 to 100 and, when done, result.url pointing at the GLB copied into our storage. 404 not_found for an unknown id.

Reference image for image-to-3D: multipart (field file) or JSON { data: "data:image/png;base64,…" }. PNG, JPEG or WebP, 8 MB max. Response { url, id, bytes }; errors 400 file_required, 413 too_large, 415 unsupported_type.