Pendahuluan

Bird API adalah REST API terpadu untuk semua yang dilakukan platform. Referensi ini mendokumentasikan setiap endpoint publik, dihasilkan dari spesifikasi OpenAPI yang sama yang menggerakkan SDK resmi, sehingga bentuk request dan response di sini persis sama dengan yang dikirim melalui jaringan.

Sidebar referensi mengelompokkan resource yang paling sering digunakan berdasarkan produk: Email, SMS, WhatsApp, Apple Messages, Voice, eSIM, Realtime, Verify, Preferences, Numbers, Lookup, Workspace, dan developer tools (Webhooks dan Documentation, API pencarian dokumentasi). Sending domain, inbound email, serta kontak dan audiens memiliki halaman referensi tanpa entri di sidebar. Mulai dari Buat sending domain, Buat alamat inbound, Buat kontak, dan Buat audiens, atau dari panduannya: Sending domain, Menerima email, Kontak, dan Audiens. Bagian Voice mencakup panggilan, log leg, trunk, nomor, caller ID, destinasi, dan kredensial sesi SIP. Statistik Voice tetap tersedia melalui dashboard dan CLI. Pengaturan workspace, kunci API, dan IP khusus dikelola di dashboard, bukan melalui API publik.

Halaman resource di-deep-link dari panduan: ketika sebuah panduan menyebut endpoint, tautannya mengarah ke entri referensinya di sini.

Untuk agen koding

Arahkan agen ke sumber yang dapat dibaca mesin berikut:

• Spesifikasi OpenAPI: setiap endpoint publik, skema, dan kode error, juga tersedia sebagai YAML. SDK dihasilkan dari file yang sama.
• Indeks API: panduan API, setiap referensi operasi, dan error publik, dikelompokkan berdasarkan produk dan ditautkan ke halaman Markdown-nya.
• Indeks dokumentasi: setiap halaman dokumentasi berbahasa Inggris yang dipublikasikan, dikelompokkan berdasarkan bagian dan produk.
• Indeks situs: produk, quickstart, dan perangkat agen di seluruh bird.com.
• MCP server: tool yang di-host di mcp.bird.com dan bertindak atas workspace Anda setelah login melalui browser.
• Bird CLI: API dari terminal. CLI for agents membahas output JSON dan exit code-nya.
• Halaman Markdown: tambahkan .md ke URL dokumentasi mana pun, seperti https://bird.com/docs/api.md, atau kirim Accept: text/markdown.

Peta produk

Setiap tabel mencantumkan panggilan yang dilakukan integrasi, secara berurutan, dengan tautan ke halaman referensi setiap panggilan dan ke panduan produknya.

Email

SMS

Verify

Produk lainnya

Konvensi

Setiap endpoint mengikuti konvensi yang sama. Konvensi ini dinyatakan sekali di sini, bukan diulang di setiap halaman.

• Base path: semua endpoint berada di bawah /v1 pada host regional seperti https://us1.platform.bird.com. Lihat Base URL dan region.
• Autentikasi: request membawa kunci API sebagai bearer token: Authorization: Bearer bk_us1_.... Lihat Autentikasi.
• JSON, snake_case: body request dan response berformat JSON dengan nama field snake_case (created_at, workspace_id), dan request harus menyetel Content-Type: application/json.
• Timestamp: semua timestamp adalah string RFC 3339 dalam UTC, pada field berakhiran _at (created_at, delivered_at). Timestamp resource seperti created_at ditetapkan oleh server dan bersifat read-only. Beberapa field request, seperti scheduled_at, adalah timestamp yang Anda berikan.
• ID resource bertipe: setiap ID membawa prefiks tipe: em_ untuk pesan email, dom_ untuk sending domain, whk_ untuk endpoint webhook, sup_ untuk supresi, dan seterusnya. Prefiks membuat ID mendeskripsikan dirinya sendiri di log dan mencegah penggunaan ID satu resource di tempat resource lain.
• Pembaruan parsial menggunakan PATCH: request PATCH hanya mengubah field yang Anda sertakan, dan membiarkan field yang tidak disertakan tetap tidak berubah. Beberapa subresource yang Anda tuju berdasarkan nama di URL ditulis dengan PUT, yang menggantikan subresource tersebut secara keseluruhan.
• Query parameter bersifat ketat: request yang membawa query parameter yang tidak didokumentasikan oleh endpoint akan ditolak dengan 422 (E01029), bukan diabaikan. Periksa ejaan terhadap daftar parameter endpoint.
• Error: setiap respons error membawa envelope yang sama, dengan type untuk percabangan umum, code yang stabil, message yang dapat dibaca manusia, dan request_id untuk dikutip saat menghubungi dukungan. Lihat Respons error.
• Paginasi: endpoint list menggunakan paginasi berbasis cursor dengan set parameter bersama. Lihat Paginasi.
• Idempotensi: endpoint yang mengubah data menerima header Idempotency-Key agar percobaan ulang aman. Lihat Header Idempotency-Key.
• Deprecation: field yang diganti nama tetap berfungsi dengan nama lamanya, dan respons memberitahukannya melalui header Deprecation. Lihat Deprecation.

Klien yang direkomendasikan

Anda dapat memanggil API dengan klien HTTP apa pun, tetapi klien resmi menangani autentikasi, pemilihan region, percobaan ulang, dan paginasi untuk Anda:

• SDK resmi untuk TypeScript, Go, dan Python: metode bertipe di atas permukaan publik yang dikurasi
• Bird CLI: API dari terminal Anda, juga cocok untuk skrip dan agen

Jalankan di Postman

Seluruh API juga tersedia sebagai koleksi Postman, dikonversi dari spesifikasi yang sama, dengan contoh request dan response di setiap endpoint. Impor environment untuk region Anda, setel apiKey ke kunci API workspace, dan kirim request apa pun.

Anda juga dapat mengunduh koleksi dan environment untuk us1 atau eu1 secara langsung.

Baca selanjutnya

• Autentikasi: cara request melakukan autentikasi di tingkat jaringan
• Base URL dan region: host regional dan model region
• Paginasi: cursor, ukuran halaman, dan pengurutan
• Header Idempotency-Key: percobaan ulang yang aman untuk request yang mengubah data
• Respons error: respons kesalahan dan katalog error lengkap
• Deprecation: apa yang masih dilakukan nama field yang digantikan, dan cara bermigrasi darinya