Agent API

Overview

The Agent API lets scripts and agents build voxel scenes with a declarative ops language (or a full ProjectJSON payload). Created scenes return an editUrl you can open in VOXIE STUDIO.

Authentication

CallerCredential
Agents / scriptsAuthorization: Bearer vx_live_… — Premium API key from Account
Editor browserShort-lived vx_at_… from POST /api/me/api-token on the app (any signed-in user, including free invitees)
Open-in-Studio links?token= read token returned at create (load-only)

Authorization

  • Scene owner must be Premium for writes (including co-creator edits).
  • Callers may mutate a scene only if they are the owner or an accepted co-creator (max 4 invitees).
  • API keys may edit only scenes the key owner can edit. Agents do not consume a co-creator seat.
  • Read tokens never grant write.

Create a scene

curl -sS https://api.voxie.studio/v1/scenes \
  -H "Authorization: Bearer vx_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Tiny House",
    "ops": [
      { "op": "color.set", "hex": "#c28569" },
      { "op": "shape.box", "from": [0,0,0], "to": [7,0,7] },
      { "op": "color.set", "hex": "#be4a2f" },
      { "op": "shape.box", "from": [1,1,1], "to": [6,4,6] }
    ]
  }'

The response includes editUrl — open it to load the scene in the editor. You can send a full project (ProjectJSON v2) instead of ops.

Endpoints

  • POST /v1/scenes — create from ops or ProjectJSON
  • GET /v1/scenes/{id} — fetch (owner, member, API key, or read token)
  • PATCH /v1/scenes/{id} — replace or append ops (membership + owner Premium)
  • DELETE /v1/scenes/{id} — delete a scene (owner only)
  • GET|POST /v1/cloud/scenes — list owned+shared / save cloud scenes

Live rooms

Co-create sessions use a Durable Object WebSocket room per scene. Mint a short-lived ticket, then connect:

curl -sS https://api.voxie.studio/v1/rooms/SCENE_ID/tickets \
  -H "Authorization: Bearer vx_at_OR_vx_live_…" \
  -X POST
# → { ticket, wsUrl, role, kind }
  • GET /v1/rooms/{sceneId}/ws?ticket= — WebSocket upgrade
  • Sequenced commit envelopes with attribution (displayName · label)
  • Debounced flush back to R2 + Neon metadata

Limits

  • Max ~80,000 voxels / 5 MB JSON (aligned with share)
  • Premium required for API keys and hosting cloud scenes
  • Co-create cap: 4 pending + accepted invitees per scene

Infrastructure

  • App: voxie.studio (Vercel)
  • API: api.voxie.studio → Cloudflare Worker + SceneRoom Durable Object
  • DB migration: drizzle/0001_co_create.sql
  • CORS allows https://voxie.studio and http://localhost:3000