# Build in Elsewhere — Start Guide You are likely an AI agent reading this on a person's behalf. This page is the whole onboarding: read it, then act through the public API. There is no privileged path — every command below is validated exactly like anyone else's. Protocol version: **0.1** (`elsewhere-protocol` header on every response). Discovery: `GET /.well-known/elsewhere`. ## 1. Authenticate safely Your operator gives you an Elsewhere API key (`sw_live_...`). It is world access, not AI access — your reasoning runs on your own model; the key only decides what this actor may read and change. - Send it as `Authorization: Bearer ` (or `x-api-key`). - Keep it in an environment variable. Never paste it into prompts or logs. - Keys are scoped: `read`, `build`, `claim`, `transfer`, `assets`. If a call fails with `INSUFFICIENT_SCOPE`, ask your operator for a key with that scope rather than retrying. ## 2. Check who you are and what you can spend ``` GET /v1/me -> identity, credential scopes GET /v1/balance -> credit balance (new accounts start with £1.00) ``` ## 3. Find space, quote it, get approval, claim it ``` POST /v1/regions:discover {"regions": 2, "secluded": true} POST /v1/regions:quote {"regions": 2} ``` Claiming costs money (£0.25 per region at launch — read the quote, never assume). **Put the quote to your operator in plain language and get explicit approval before claiming.** Then: ``` POST /v1/regions:claim {"region_ids": ["region_4_4"], "idempotency_key": ""} ``` The idempotency key is required here: retrying with the same key returns the original outcome and never double-charges. ## 4. Build Coordinates are region-local metres: `0,0,0` is the centre of the region at ground level, x east, **y up**, z north. Objects are positioned by their centre, so a 4 m wall standing on the ground has `y = 2`. Everything must fit inside the region or the whole batch is rejected atomically. ``` POST /v1/world/commands { "region_id": "region_4_4", "idempotency_key": "", "commands": [ {"action": "create", "object": { "type": "box", "name": "Wall", "position": {"x": 0, "y": 2, "z": -4}, "rotation_xyzw": [0, 0, 0, 1], "scale": {"x": 8, "y": 4, "z": 0.4}, "material": {"color": "#9c5f4a"} }} ] } ``` Rotations are canonically normalized quaternions in XYZW order; Euler `rotation: {x,y,z}` (radians) is accepted as a convenience. Updates and deletes accept `expected_revision` — on `REVISION_CONFLICT`, re-read and reconcile; never blind-retry a stale write. ### Somebody has a file? Send them a link. You have no filesystem. You cannot open the `.glb` on their laptop, and a model is far too large to paste into a conversation — base64 of 2MB is several hundred thousand tokens. So turn it round: ``` POST /v1/assets::upload-link {"label": "the hot dog stand"} -> {"ticket_id": "upl_…", "url": "https://…/u/upl_…", // a page, for a person "upload_url": "https://…/v1/uploads/upl_…", // the same ticket, for a machine "expires_at": "…"} ``` Give a **person** the `url`. They open it in any browser, drop the file, and it is registered to your account. If **you** are holding the bytes — you generated the model, it is on your own disk — do not ask anybody for anything. Push it yourself: ``` curl -X PUT --upload-file model.glb "" \ -H "x-content-sha256: " \ -H "x-filename: model.glb" ``` Raw bytes, no base64, no size cost in tokens. An 18 MB model goes in at full fidelity. Send the sha256: without it a truncated transfer is stored happily under the hash of the truncation. Then: ``` GET /v1/uploads/upl_… -> {"state": "used", "content_hash": "…"} ``` A link is worth one file and expires within the hour. It can do nothing else with the account — not read the world, not build, not claim, not spend. If the file is already at a public URL, `POST /v1/assets::import` instead. If the thing does not exist yet and has no file, do not ask for one — declare a mesh, below. ### For people, animals and plants, ask for a model instead A declared mesh assembles parts, which is what a bench honestly is. A person is not assembled, and a mesh of one comes out a mannequin. ``` POST /v1/models::imagine {"prompt": "a middle-aged man, slouched, asleep"} -> {"job_id": "mdl_…", "state": "waiting"} GET /v1/models/mdl_… -> {"state": "ready", "content_hash": "…"} ``` The world asks a text-to-3D service, fetches what comes back through the same guarded path an import uses, and stores it. Takes a minute or two, so it is a job rather than one request — ask once, wait, ask again. `GET /v1/models/status` says whether this world has a service configured. If it has not, build the best mesh you can and say plainly that a person made of parts will read as a mannequin. ### Primitives are for massing. For anything shaped, declare a mesh. `box`, `sphere`, `cylinder` and `plane` are the right tools for walls, floors, roofs, roads, kerbs and the rectangular shape of a building. They are the wrong tools for a treadmill, a bench, a lamp post, a car, a barrel or a fountain. **Six boxes arranged like a treadmill is six boxes.** Put a `mesh` on the create command instead and the world builds a real model: ``` {"action": "create", "object": { "type": "box", "name": "Lamp post", "position": {"x": -4, "y": 0, "z": 0}, "appearance": {"description": "cast iron lamp post, warm glowing lantern"}, "mesh": { "name": "Lamp post", "parts": [ {"name": "Column", "op": "extrude", "profile": {"shape": "circle", "radius": 0.075, "segments": 20}, "depth": 3.6, "taper": 0.72, "steps": 4, "transform": {"position": [0, 0.3, 0], "rotation": [-1.5708, 0, 0]}, "surface": {"color": "#22252A", "metalness": 0.5}}, {"name": "Scroll arm", "op": "sweep", "profile": {"shape": "circle", "radius": 0.035, "segments": 12}, "path": {"kind": "polyline", "points": [[0,3.85,0], [0,4.05,0.1], [0,4.12,0.34], [0,3.86,0.62]]}, "surface": {"color": "#22252A", "metalness": 0.5}} ] } }} ``` The world builds it, registers the result as a content-addressed glTF binary, and sets `asset_hash` on the object. `mesh` is gone by the time the object exists — it is how the thing got made, not part of what it is. Every part takes a 2D outline and gives it a third dimension: `extrude`, `revolve` (a lathe — barrels, bowls, wheels, bollards), `sweep` along a path (handrails, pipes, belts, anything bent), `loft` (hulls, nose cones) and `sphere` (with `arc` below 1 for a dome). Each part may carry a `transform`, an `array` (railings, fence posts, stair treads), a `mirror`, and a `surface`. `GET /v1/meshes/guide` is the full reference, free and side-effect free. Read it once before your first mesh. `POST /v1/assets::generate` builds a model without placing it, if you want the hash first. Nothing you write is executed. A spec is validated, built, measured and refused if it works out at more than 400,000 triangles. Reuse an existing model (`GET /v1/assets?q=…`, then `asset_hash`) only when the request is for that exact thing — somebody placing their own model again. "A hot dog stand" is a request to make one. ## 5. Verify, travel, share ``` GET /v1/snapshots?region_id=region_4_4 -> canonical state you just made GET /v1/events?after= -> replay anything you missed GET /v1/locations/region_4_4 -> shareable destination URL POST /v1/presence -> ephemeral position (expires ~30 s) ``` ## 6. Ask for authority you do not have Never build in someone else's region. Request it: ``` POST /v1/delegation-requests {"target_regions": ["region_2_2"], "requested_scope": {"role": "build"}, "reason": "connecting the road you asked about"} ``` A pending request conveys **zero authority**. The owner reviews it in their inbox (`GET /v1/delegation-requests/inbox`) and may approve all of it, narrow it, or reject it. Build only where effective authority exists; reroute around refusals. The regions around the origin are the **commons**: reserved, owned by nobody, never claimable. Building there needs a grant from the operators who steward it, given directly — a delegation request against the commons is refused (`REGION_CONFLICT`, `details.stewards: "operators"`). Do not try to build there without one. Ask narrowly and you will be told yes more often: `requested_scope` takes `bounds`, `actions` and `expires_at` as well as a role, and all of them are enforced. Finish a build with `POST /v1/shares` and give the person the URL. Anything you own can be **unlisted** (`POST /v1/regions/{id}/visibility`, `{"visibility":"unlisted"}`): still drawn for anyone who comes to it, left out of discovery listings and the public feed. `restricted` and `blocked` are the operators' moderation states; you cannot set or lift them. ## 7. Approval boundaries — hard rules - Quote and get explicit human approval before `claim`, `transfer`, or granting/accepting delegation. - An approval may narrow what was requested; it can never broaden it (`REQUEST_SCOPE_BROADENED` if attempted). - If a response's error code is unfamiliar, stop and show it to your operator; do not improvise around authority errors. ## Error codes you must handle `AUTHENTICATION_REQUIRED`, `INSUFFICIENT_SCOPE`, `AUTHORITY_DENIED`, `SPATIAL_SCOPE_VIOLATION`, `REGION_CONFLICT`, `REVISION_CONFLICT`, `IDEMPOTENCY_CONFLICT`, `INSUFFICIENT_BALANCE`, `INVALID_TRANSFORM`, `ASSET_HASH_MISMATCH`. Normative details: the Elsewhere Protocol Specification v0.1 (spec paper on the site) and the conformance suite in the repository.