Start with one little world

This walk-through uses the REST API with curl. Every step works the same way over MCP, because both are generated from one operation catalogue and go through the same permission checks as the app.

Create a connection

Sign in, open Developers in the dashboard (workspace owners and admins only) and choose New connection. Pick REST API, keep the read-only defaults (workspaces:read, catalog:read, worlds:read) and, for this walk-through, add worlds:write and worlds:publish. The token is shown once, so copy it into your secret store straight away.

The Reference card on the same page shows your REST base URL, MCP endpoint and OpenAPI contract.

export BASE="https://<your host>/api/v1"
export TOKEN="sw_rest_..."

Find your workspace

A token belongs to exactly one workspace. List it to get its id and your role:

curl -s -H "Authorization: Bearer $TOKEN" "$BASE/workspaces"
export WS="<data[0].id>"

Then ask what this workspace can do right now. Each capability says whether it is implemented, simulated, blocked by missing credentials or waiting for a decision:

curl -s -H "Authorization: Bearer $TOKEN" "$BASE/workspaces/$WS/capabilities"

Make a draft casa

Pick a design from the catalogue (GET /catalog/templates), then create a draft. Every write needs an Idempotency-Key of 16 to 128 characters; retrying with the same key and body returns the original result instead of a second casa.

curl -s -X POST "$BASE/workspaces/$WS/worlds" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $(openssl rand -hex 16)" \
  -H "Content-Type: application/json" \
  -d '{"handle":"my-first-casa","template_id":"pizza",
       "profile":{"display_name":"My first casa","bio":"Hello from the API.","content_language":"en"}}'

Edit it safely

Read the casa first. The response carries an ETag header; send it back as If-Match with your change. If someone edited the draft in the meantime you get 412 revision_conflict and nothing changes.

curl -s -i -H "Authorization: Bearer $TOKEN" "$BASE/workspaces/$WS/worlds/$WORLD"

curl -s -X PATCH "$BASE/workspaces/$WS/worlds/$WORLD" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $(openssl rand -hex 16)" \
  -H 'If-Match: W/"<etag>"' \
  -H "Content-Type: application/json" \
  -d '{"profile":{"bio":"Edited over the API."}}'

Publish and wait for the job

Publishing takes the exact draft_revision_id and draft_digest from the latest read, so you publish what you checked. It answers 202 with a job; the previous version stays live until the new build succeeds.

curl -s -X POST "$BASE/workspaces/$WS/worlds/$WORLD/publications" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $(openssl rand -hex 16)" \
  -H "Content-Type: application/json" \
  -d '{"revision_id":"<draft_revision_id>","expected_digest":"<draft_digest>"}'

curl -s -H "Authorization: Bearer $TOKEN" "$BASE/workspaces/$WS/jobs/$JOB"

Poll no faster than next_poll_after_seconds. A completed job returns the canonical_url of the live page. Prefer a webhook to polling once you have more than a few jobs.

Where to go next

• Authentication and scopes: which permissions each operation needs.
• MCP: connect an agent client to the same operations.
• API reference: conventions, errors and the OpenAPI contract.