Wprowadzenie

Bird API to ujednolicone REST API do wszystkiego, co platforma oferuje. Ta dokumentacja referencyjna opisuje każdy publiczny endpoint i jest generowana z tej samej specyfikacji OpenAPI, która napędza oficjalne SDK, więc kształty żądań i odpowiedzi tutaj są dokładnie tym, co przechodzi przez sieć.

Pasek boczny dokumentacji grupuje najczęściej używane zasoby według produktu: Email, SMS, WhatsApp, Apple Messages, Voice, eSIM, Realtime, Verify, Preferences, Numbers, Lookup, Workspace oraz narzędzia deweloperskie (Webhooks i Documentation, API wyszukiwania w dokumentacji). Domeny wysyłkowe, poczta przychodząca oraz kontakty i grupy odbiorców mają strony referencyjne bez wpisu na pasku bocznym. Zacznij od Utwórz domenę wysyłkową, Utwórz adres przychodzący, Utwórz kontakt i Utwórz grupę odbiorców albo od przewodników: Domeny wysyłkowe, Odbieranie e-maili, Kontakty i Grupy odbiorców. Sekcja Voice obejmuje połączenia, logi odcinków, trunki, numery, identyfikatory dzwoniącego, miejsca docelowe i dane uwierzytelniające sesji SIP. Statystyki Voice są nadal dostępne przez dashboard i CLI. Ustawienia obszaru roboczego, klucze API i dedykowane adresy IP są zarządzane w dashboardzie, a nie w publicznym API.

Strony zasobów są linkowane bezpośrednio z przewodników: gdy przewodnik wspomina endpoint, link prowadzi do jego wpisu w dokumentacji referencyjnej.

Dla agentów kodujących

Skieruj agenta na te źródła odczytywalne maszynowo:

• Specyfikacja OpenAPI: każdy publiczny endpoint, schemat i kod błędu, dostępna też jako YAML. SDK są generowane z tego samego pliku.
• Indeks API: przewodniki API, dokumentacja referencyjna każdej operacji i publiczne błędy, pogrupowane według produktu z linkami do stron Markdown.
• Indeks dokumentacji: każda opublikowana anglojęzyczna strona dokumentacji, pogrupowana według sekcji i produktu.
• Indeks witryny: produkty, szybkie starty i narzędzia agentowe w całym bird.com.
• MCP server: hostowane narzędzia pod adresem mcp.bird.com, które działają na twoim obszarze roboczym po zalogowaniu w przeglądarce.
• Bird CLI: API z terminala. CLI for agents opisuje jego wyjście JSON i kody zakończenia.
• Strony Markdown: dołącz .md do dowolnego URL-a dokumentacji, np. https://bird.com/docs/api.md, lub wyślij Accept: text/markdown.

Mapa produktów

Każda tabela wymienia wywołania, które wykonuje integracja, w kolejności, z linkiem do strony referencyjnej każdego wywołania i do przewodników produktu.

Email

SMS

Verify

Inne produkty

Konwencje

Każdy endpoint stosuje te same konwencje. Są opisane tutaj raz, zamiast powtarzać je na każdej stronie.

• Ścieżka bazowa: wszystkie endpointy znajdują się pod /v1 na regionalnym hoście, np. https://us1.platform.bird.com. Zobacz Bazowe URL-e i regiony.
• Uwierzytelnianie: żądania przekazują klucz API jako bearer token: Authorization: Bearer bk_us1_.... Zobacz Uwierzytelnianie.
• JSON, snake_case: ciała żądań i odpowiedzi są w formacie JSON z nazwami pól w konwencji snake_case (created_at, workspace_id), a żądania muszą ustawiać Content-Type: application/json.
• Znaczniki czasu: wszystkie znaczniki czasu to ciągi RFC 3339 w UTC, w polach z sufiksem _at (created_at, delivered_at). Znaczniki czasu zasobów, takie jak created_at, są przypisywane przez serwer i tylko do odczytu. Kilka pól żądania, np. scheduled_at, to znaczniki czasu podawane przez ciebie.
• Typowane ID zasobów: każde ID zawiera prefiks typu: em_ dla wiadomości e-mail, dom_ dla domen wysyłkowych, whk_ dla endpointów webhook, sup_ dla suppresji itd. Prefiks sprawia, że ID jest samoopisujące się w logach i zapobiega przekazaniu ID jednego zasobu tam, gdzie oczekiwane jest ID innego.
• Częściowe aktualizacje używają PATCH: żądanie PATCH zmienia tylko pola, które uwzględnisz, a pominięte pola pozostają bez zmian. Kilka podzasobów adresowanych po nazwie w URL-u zapisuje się za pomocą PUT, co zastępuje dany podzasób w całości.
• Parametry zapytania są ścisłe: żądanie zawierające parametr zapytania, którego endpoint nie dokumentuje, jest odrzucane z kodem 422 (E01029), a nie ignorowane. Sprawdź pisownię względem listy parametrów endpointu.
• Błędy: każda odpowiedź z błędem ma tę samą strukturę, zawierającą type do ogólnego rozgałęziania, stabilny code, czytelny dla człowieka message oraz request_id do podania przy kontakcie ze wsparciem. Zobacz Odpowiedzi z błędem.
• Paginacja: endpointy listowe używają paginacji opartej na kursorach ze współdzielonym zestawem parametrów. Zobacz Paginacja.
• Idempotentność: endpointy modyfikujące przyjmują nagłówek Idempotency-Key, dzięki czemu ponowne próby są bezpieczne. Zobacz Nagłówek Idempotency-Key.
• Wycofywanie: zmienione pole nadal działa pod starą nazwą, a odpowiedź sygnalizuje to nagłówkiem Deprecation. Zobacz Wycofywanie.

Zalecani klienci

Możesz wywoływać API dowolnym klientem HTTP, ale oficjalni klienci obsługują uwierzytelnianie, wybór regionu, ponowne próby i paginację za ciebie:

• Oficjalne SDK dla TypeScript, Go i Python: typowane metody na kurowanej powierzchni publicznej
• Bird CLI: API z twojego terminala, odpowiedni również do skryptów i agentów

Uruchom w Postmanie

Całe API jest też kolekcją Postman, skonwertowaną z tej samej specyfikacji, z przykładowym żądaniem i odpowiedzią dla każdego endpointu. Zaimportuj środowisko dla swojego regionu, ustaw apiKey na klucz API obszaru roboczego i wyślij dowolne żądanie.

Możesz też pobrać kolekcję oraz środowisko dla us1 lub eu1 bezpośrednio.

Czytaj dalej

• Uwierzytelnianie: jak żądania uwierzytelniają się na poziomie sieci
• Bazowe URL-e i regiony: hosty regionalne i model regionów
• Paginacja: kursory, rozmiary stron i sortowanie
• Nagłówek Idempotency-Key: bezpieczne ponowne próby dla żądań modyfikujących
• Odpowiedzi z błędem: odpowiedź z błędem i pełny katalog błędów
• Wycofywanie: co zastąpiona nazwa pola nadal robi i jak z niej zmigrować