一つのcasaから始めよう

この手順では、curlでREST APIを使います。MCPでも各手順は同じように動作します。どちらも一つの操作カタログから生成され、アプリと同じ権限チェックを通るためです。

接続を作る

サインインし、ダッシュボードの開発者を開いて（ワークスペースのオーナーと管理者のみ）、新しい接続を選びます。REST APIを選び、読み取り専用の初期設定（workspaces:read、catalog:read、worlds:read）をそのままにし、この手順のためにworlds:writeとworlds:publishを追加します。トークンは一度だけ表示されるので、すぐにシークレットの保管先へコピーしてください。

同じページのリファレンスカードには、RESTのベースURL、MCPエンドポイント、OpenAPI契約が表示されます。

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

ワークスペースを見つける

トークンは必ず一つのワークスペースに属します。一覧を取得し、そのIDとあなたのロールを確認します。

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

次に、このワークスペースで今できることを問い合わせます。各機能には、実装済みか、シミュレーションか、認証情報がないために利用できないか、判断待ちかが示されます。

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

casaの下書きを作る

カタログ（GET /catalog/templates）からデザインを選び、下書きを作ります。どの書き込みにも16～128文字のIdempotency-Keyが必要です。同じキーと本文で再試行すると、二つ目の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"}}'

安全に編集する

まずcasaを読み取ります。レスポンスにはETagヘッダーがあるので、変更時にIf-Matchとして送り返します。その間に誰かが下書きを編集していた場合は、412 revision_conflictが返り、何も変更されません。

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

公開し、ジョブを待つ

公開には、最新の読み取りで得た正確なdraft_revision_idとdraft_digestを渡します。これで、確認したものを公開できます。ジョブを伴う202が返り、新しいビルドが成功するまで前の版が公開されたままになります。

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"

ポーリングの間隔はnext_poll_after_secondsより短くしないでください。completedのジョブは、公開ページのcanonical_urlを返します。ジョブが数件を超えたら、ポーリングよりWebhookをおすすめします。

次に進むには

• 認証とスコープ：各操作に必要な権限。
• MCP：エージェントクライアントを同じ操作につなぐ方法。
• APIリファレンス：規約、エラー、OpenAPI契約。