Beginne mit einer casa

Diese Anleitung nutzt die REST-API mit curl. Jeder Schritt funktioniert über MCP genauso, denn beide werden aus einem Vorgangskatalog erzeugt und durchlaufen dieselben Berechtigungsprüfungen wie die App.

Eine Verbindung erstellen

Melde dich an, öffne Entwickler in der Übersicht (nur für Arbeitsbereichsinhaber und Administratoren) und wähle Neue Verbindung. Wähle REST-API, behalte die schreibgeschützten Standardwerte (workspaces:read, catalog:read, worlds:read) und ergänze für diese Anleitung worlds:write und worlds:publish. Das Token wird einmal angezeigt. Kopiere es daher sofort in deinen Geheimnisspeicher.

Die Karte Referenz auf derselben Seite zeigt REST-Basis-URL, MCP-Endpunkt und OpenAPI-Vertrag.

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

Deinen Arbeitsbereich finden

Ein Token gehört genau einem Arbeitsbereich. Liste ihn auf, um seine Kennung und deine Rolle zu erhalten:

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

Frage dann ab, was der Arbeitsbereich derzeit kann. Jede Fähigkeit zeigt, ob sie implementiert, simuliert, durch fehlende Zugangsdaten blockiert oder auf eine Entscheidung wartend ist:

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

Einen casa-Entwurf erstellen

Wähle ein Design aus dem Katalog (GET /catalog/templates) und erstelle einen Entwurf. Jeder Schreibvorgang braucht einen Idempotency-Key mit 16 bis 128 Zeichen. Eine Wiederholung mit demselben Schlüssel und Inhalt liefert das ursprüngliche Ergebnis statt einer zweiten 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"}}'

Sicher bearbeiten

Lies zuerst die casa. Die Antwort enthält einen ETag-Header. Sende ihn mit deiner Änderung als If-Match zurück. Wurde der Entwurf inzwischen bearbeitet, erhältst du 412 revision_conflict, und nichts ändert sich.

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."}}'

Veröffentlichen und auf den Auftrag warten

Die Veröffentlichung nimmt genau draft_revision_id und draft_digest aus dem letzten Lesevorgang. So veröffentlichst du das Geprüfte. Sie antwortet mit 202 und einem Auftrag. Die vorherige Version bleibt online, bis der neue Build erfolgreich ist.

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"

Frage nicht schneller ab als next_poll_after_seconds. Ein Auftrag mit Status completed liefert die canonical_url der veröffentlichten Seite. Nutze lieber einen Webhook statt Abfragen, sobald du mehr als wenige Aufträge hast.

Wie es weitergeht

• Authentifizierung und Berechtigungsbereiche: welche Rechte jeder Vorgang braucht.
• MCP: einen Agentenclient mit denselben Vorgängen verbinden.
• API-Referenz: Konventionen, Fehler und OpenAPI-Vertrag.