Satu kontrak untuk casa Anda

Kontrak yang dapat dibaca mesin

GET /api/v1/openapi.json mengembalikan dokumen OpenAPI 3.1 tentang apa yang diimplementasikan deployment ini secara persis: setiap jalur, skema, cakupan wajib, dan respons, beserta peristiwa webhook. Dokumen dihasilkan dari katalog operasi yang sedang berjalan, katalog sama yang menghasilkan alat MCP, sehingga REST dan MCP tidak pernah menyimpang satu sama lain.

curl -s "https://<your host>/api/v1/openapi.json"

Antarmuka mencakup casa dan draf, revisi dan penerbitan, tulisan, katalog templat, impor, portofolio dan proses massal, domain dan rencana DNS, penerusan email, pengaturan pendaftaran dan kontak, sumber sosial, analitik, promosi, penagihan, anggota tim, serta webhook. GET /workspaces/{id}/capabilities memberi tahu mana yang aktif, disimulasikan, atau menunggu kredensial dalam ruang kerja Anda.

Pengulangan dilakukan dengan sengaja

• Setiap perubahan memerlukan header Idempotency-Key sepanjang 16 hingga 128 karakter. Mengulangi permintaan dengan kunci dan isi yang sama mengembalikan hasil asli dengan Idempotent-Replayed: true. Kunci yang sama dengan isi berbeda menghasilkan 409 idempotency_key_reused.
• Penyuntingan casa memerlukan If-Match dengan ETag dari pembacaan terakhir. Nilai usang menghasilkan 412 revision_conflict dan tidak ada yang berubah.
• Penerbitan menggunakan revision_id dan expected_digest persis yang Anda baca, sehingga Anda menerbitkan apa yang sudah diperiksa.

Pekerjaan panjang menjadi job

Penerbitan, proses massal, dan operasi lambat lain menjawab 202 beserta pekerjaan. Lakukan polling pada GET /workspaces/{id}/jobs/{job_id} tidak lebih cepat daripada next_poll_after_seconds, atau berlangganan webhook job.updated. Diterima bukan berarti selesai: baca state, jumlah, dan error pekerjaan sebelum melaporkan keberhasilan.

Kesalahan berupa detail masalah

Kesalahan menggunakan application/problem+json dengan code yang stabil, title yang dilokalkan, request_id, dan retryable. Tentukan percabangan berdasarkan code, jangan berdasarkan teks judul.

{
  "type": "https://<your host>/problems/insufficient_scope",
  "title": "This token does not include the permission this action needs.",
  "status": 403,
  "code": "insufficient_scope",
  "request_id": "01M5...",
  "retryable": false,
  "context": { "required_scope": "account:read" }
}

Daftar dan batas

• Endpoint daftar menerima limit (hingga 100) dan cursor dari halaman sebelumnya.
• Setiap token ruang kerja dapat melakukan 120 pembacaan dan 30 penulisan per menit. Jika melampaui batas, Anda menerima 429 dengan header Retry-After.
• Pertahankan kolom respons yang tidak dikenal: kolom baru dapat muncul tanpa perubahan versi.