Ringkasan API

Ini adalah dokumentasi API publik dari cloud Capgo. API memungkinkan Anda mengelola resource Capgo secara terprogram, termasuk organisasi, perangkat, channel, dan bundle. API ini dirancang secara RESTful dan menggunakan metode HTTP standar.

Autentikasi

Semua endpoint API memerlukan autentikasi. Untuk mengautentikasi request Anda, tambahkan API key Anda di x-api-key header, atau kirimkan sebagai Authorization: Bearer YOUR_API_KEY.

Contoh:

curl -H "x-api-key: YOUR_API_KEY" https://api.capgo.app/organization/

Dapatkan API key Generate API key Anda di Capgo dashboard

Panduan authorization header dengan raw key (tanpa Bearer prefix) masih diterima untuk integrasi legacy, tetapi x-api-key adalah header yang direkomendasikan untuk semua tipe key, termasuk secure hashed keys.

AI agent dan OAuth client lainnya dapat mendapatkan key melalui OAuth 2.0 (authorization code dengan PKCE dan dynamic client registration). Issuer-nya adalah https://capgo.app, dengan metadata di https://capgo.app/.well-known/oauth-authorization-server. Pengguna memilih organisasi mana yang diberi akses, dan access token adalah kunci Capgo API yang dikirim sebagai Bearer token.

Versioning

API di-version berdasarkan tanggal. Pin versi tertentu dengan capgo_api header permintaan:

curl -H "x-api-key: YOUR_API_KEY" -H "capgo_api: 2025-10-01" https://api.capgo.app/organization/

Tanpa header tersebut, Anda akan mendapatkan versi default, saat ini 2025-10-01. Perubahan dalam satu versi bersifat aditif: endpoint baru, parameter opsional baru, dan field response baru. Breaking change dirilis sebagai versi bertanggal baru, dan client yang di-pin ke tanggal lama tetap memakai perilaku lama. Versi yang tidak dikenal atau malformed akan mengembalikan 400 unsupported_capgo_api_version atau 400 invalid_capgo_api_version.

Menghapus operasi atau field adalah breaking change, jadi itu hanya terjadi di versi bertanggal baru. Saat ini belum ada yang deprecated. Jika nanti ada, operasi tersebut akan ditandai deprecated: true di dalam Spec OpenAPI, responsnya akan menyertakan Deprecation header (RFC 9745) dan Sunset header (RFC 8594) berisi tanggal berakhirnya perilaku lama, dan perubahan ini akan diumumkan di catatan rilis.

Pembatasan Laju (Rate Limiting)

API menerapkan rate limiting untuk memastikan penggunaan yang adil. Batas saat ini adalah:

• 2.000 request per menit per key API
• 20.000 request per menit per key API pada route bundle upload
• 20 key API tidak valid per alamat IP dalam 15 menit, setelah itu IP diblokir selama 15 menit

Setiap response melaporkan kuota melalui RateLimit-Policy dan RateLimit header (Draf IETF):

RateLimit-Policy: "apikey";q=2000;w=60
RateLimit: "apikey";r=1995;t=42

q adalah kuota, w adalah window dalam detik, r adalah sisa request dan t jumlah detik hingga jendela reset. Jika Anda melampaui batas, Anda akan menerima respons 429 (Too Many Requests) dengan Retry-After header dalam detik.

Perubahan channel perangkat

Perubahan channel device menggunakan plugin API dan memiliki limit pencegahan penyalahgunaan terpisah yang berlaku untuk semua plan, termasuk trial:

• Satu device dapat melakukan hingga 5 request per detik untuk setiap operasi channel (set, get, delete, atau list). Limit ini berlaku per app, device, dan operasi.
• Mengatur device yang sama ke channel yang sama lebih dari sekali dalam 60 detik akan menghasilkan respons 429. Berpindah ke channel lain diperbolehkan setelah limit per detik di-reset.
• Limit tambahan sebesar 1000 request channel per menit berlaku untuk setiap app dan alamat IP.

Limit ini tidak berlaku untuk seluruh akun. Jika channel switcher Anda dapat kembali ke channel yang baru saja dipilih, tunggu retryAfterSeconds durasi pada respons 429 sebelum mencoba lagi.

Format Response

Semua respons menggunakan format JSON. Respons yang berhasil biasanya menyertakan data objek atau status field. Respons error menyertakan format yang dapat dibaca mesin error code, yang mudah dibaca manusia messagemudah dibaca manusia, dan moreInfo detailnya.

Contoh respons sukses:

{
  "status": "ok",
  "data": { ... }
}

Contoh respons error:

{
  "error": "invalid_apikey",
  "message": "Invalid apikey",
  "moreInfo": {}
}

Endpoint yang Tersedia

Organisasi Buat dan kelola organisasi, perbarui pengaturan, serta tangani konfigurasi tingkat organisasi

Kunci API Buat, tampilkan, dan cabut kunci API untuk akses aman ke Capgo API

Anggota Kelola anggota, role, dan permission organisasi

Statistik Akses analitik terperinci tentang penggunaan app, storage, dan konsumsi bandwidth

Channel Kontrol channel update app, bundle (versi), dan kebijakan update

Perangkat Pantau dan kelola perangkat yang menjalankan aplikasi Anda, termasuk penugasan bundle (versi) dan channel

Bundle Kelola app bundle, termasuk upload, list, dan manajemen bundle (versi)

Praktik Terbaik

1. Penanganan error: Selalu cek respons error dan tangani dengan tepat
2. Pembatasan Laju (Rate Limiting): Implementasikan exponential backoff saat terkena rate limit
3. Caching: Cache respons jika diperlukan untuk mengurangi panggilan API
4. Versioning: Pantau perubahan API lewat changelog kami

Lanjut dari API Overview

Jika Anda menggunakan Ringkasan API untuk merencanakan alur autentikasi dan akun, hubungkan dengan @capgo/capacitor-social-login untuk detail implementasi di @capgo/capacitor-social-login, @capgo/capacitor-passkey untuk detail implementasi di @capgo/capacitor-passkey, @capgo/capacitor-native-biometric untuk detail implementasi di @capgo/capacitor-native-biometric, Autentikasi dua faktor untuk detail implementasi pada Two-factor authentication, dan SSO (Enterprise) untuk detail implementasi pada SSO (Enterprise).