Mulai dengan satu casa

Panduan ini menggunakan REST API dengan curl. Setiap langkah bekerja dengan cara sama melalui MCP, karena keduanya dihasilkan dari satu katalog operasi dan melewati pemeriksaan izin yang sama dengan aplikasi.

Buat koneksi

Masuk, buka Pengembang di dasbor (khusus pemilik dan admin ruang kerja), lalu pilih Koneksi baru. Pilih REST API, pertahankan bawaan hanya baca (workspaces:read, catalog:read, worlds:read), dan untuk panduan ini tambahkan worlds:write serta worlds:publish. Token hanya ditampilkan sekali, jadi segera salin ke tempat penyimpanan rahasia Anda.

Kartu Referensi pada halaman yang sama menampilkan URL dasar REST, endpoint MCP, dan kontrak OpenAPI Anda.

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

Temukan ruang kerja Anda

Satu token hanya dimiliki tepat satu ruang kerja. Tampilkan daftarnya untuk mendapatkan id dan peran Anda:

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

Lalu tanyakan kemampuan ruang kerja saat ini. Setiap kemampuan menjelaskan apakah sudah diimplementasikan, disimulasikan, terhalang kredensial yang belum tersedia, atau menunggu keputusan:

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

Buat draf casa

Pilih desain dari katalog (GET /catalog/templates), lalu buat draf. Setiap penulisan memerlukan Idempotency-Key sepanjang 16 hingga 128 karakter; mengulangi permintaan dengan kunci dan isi yang sama mengembalikan hasil asli, bukan membuat casa kedua.

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

Sunting dengan aman

Baca casa terlebih dahulu. Respons memuat header ETag; kirim kembali sebagai If-Match bersama perubahan. Jika seseorang menyunting draf sementara itu, Anda menerima 412 revision_conflict dan tidak ada yang berubah.

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

Terbitkan dan tunggu pekerjaan

Penerbitan menggunakan draft_revision_id dan draft_digest persis dari pembacaan terakhir, sehingga Anda menerbitkan apa yang sudah diperiksa. Respons berupa 202 beserta pekerjaan; versi sebelumnya tetap aktif sampai pembangunan baru berhasil.

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"

Jangan lakukan polling lebih cepat daripada next_poll_after_seconds. Pekerjaan completed mengembalikan canonical_url halaman aktif. Utamakan webhook daripada polling setelah Anda memiliki lebih dari beberapa pekerjaan.

Langkah berikutnya

• Autentikasi dan cakupan: izin yang diperlukan setiap operasi.
• MCP: hubungkan klien agen ke operasi yang sama.
• Referensi API: konvensi, kesalahan, dan kontrak OpenAPI.