HTTP API reference

Conventions & authentication

All paths start with /api. Reads use GET; mutations use POST with Content-Type: application/json. JSON bodies are capped at20KB. Responses are JSON with Cache-Control: no-store, except the ZIP download. Errors include an error string.

Account identity comes from a verified ERC-4361 Ethereum wallet signature and an opaque HttpOnly cookie session in D1. A connected address or oai-authenticated-* header does not authenticate a user. Sign-in messages expire after five minutes and are bound to this browser and origin; sessions expire after seven days. Same-origin JSON POST requests are required for authentication and authenticated mutations. The run bearer token works only for that run’s read/action paths.

const r = await fetch("/api/worlds/return-terminal/runs", {
  method: "POST",
  headers: {"Content-Type":"application/json"},
  body: JSON.stringify({nonce: crypto.randomUUID()})
});
const {run, agentToken} = await r.json();
// Call from an authenticated same-origin session. Store capability privately.

Endpoint map

World creation body

{
  "name":"My Returns World",
  "description":"Tests return windows and untrusted customer notes.",
  "nonce":"A_NEW_UUID",
  "spec":{
    "version":1,"template":"returns","brand":"Orbit Supply",
    "returnDays":30,"scenarios":6,"difficulty":"adversarial","seed":42
  }
}

Errors, limits & retries

Creating a run with the same nonce returns its existing run. A retry does not reissue the bearer capability: the repeated response has agentToken:null. Public high-volume operation needs additional edge rate limits.