> ## Documentation Index > Fetch the complete documentation index at: https://docs.brosbots.com/llms.txt > Use this file to discover all available pages before exploring further. # Wprowadzenie do API > Uwierzytelnij się i wykonaj pierwsze żądanie do API Brosbots Publiczne REST API Brosbots pozwala programistycznie robić wszystko to, co panel: budować i zarządzać agentami, uruchamiać kampanie wychodzące, odczytywać rozmowy i zużycie oraz zarządzać numerami, narzędziami, bazami wiedzy i integracjami. ## Adres bazowy ```text theme={null} https://app.brosbots.com/api/v1 ``` ## Uwierzytelnianie Każde żądanie musi zawierać klucz API organizacji w nagłówku `X-API-Key`. Klucze tworzysz i unieważniasz w panelu: kliknij swoje konto w lewym dolnym rogu paska bocznego, a potem **Brosbots API**. ```bash theme={null} curl https://app.brosbots.com/api/v1/agents/summary \ -H "X-API-Key: bb_live_..." ``` Traktuj klucze API jak hasła: nie commituj ich do repozytoriów i nie umieszczaj w kodzie frontendowym. Jeśli klucz wycieknie - natychmiast go unieważnij. ## ID agenta Wszędzie, gdzie ścieżka zawiera `{agent_id}`, możesz podać publiczne ID agenta, np. `agent_7fK2mQ9xLp3RtV8wYb1N` (znajdziesz je w edytorze agenta, obok jego nazwy - kliknięcie kopiuje), albo jego numer. Oba wskazują tego samego agenta. W odpowiedziach pole `workflow_id` jest numerem. Adresy z tej dokumentacji (`/agents`, `/campaigns`, `/integrations`, `/triggers`, `/usage`, `/reports`) zastąpiły wcześniejsze, np. `/workflow/{workflow_id}/calls` czy `/organizations/usage/...`. Wcześniejsze adresy nadal działają bez zmian, więc istniejące integracje nie wymagają poprawek. Nowe buduj na adresach z tej dokumentacji. Nazwy pól w treści żądań i odpowiedzi (np. `workflow_id`, `workflow_run_id`) się nie zmieniły. ## Szybki start: wywołaj połączenie Rozpocznij połączenie wychodzące istniejącym agentem. `phone_number` i `initial_context` to pola obok siebie; zmienne z `initial_context` agent widzi w promptach jako `{{initial_context.}}`. ```bash theme={null} curl -X POST "https://app.brosbots.com/api/v1/agents/{agent_id}/calls" \ -H "X-API-Key: bb_live_..." \ -H "Content-Type: application/json" \ -d '{ "phone_number": "+48123456789", "initial_context": { "first_name": "Jan" } }' ``` ```json theme={null} { "status": "initiated", "workflow_run_id": 580, "workflow_run_name": "WR-API-4821" } ``` `POST /agents/{agent_id}/conversations` **nie dzwoni**. Tworzy tylko rekord przebiegu dla rozmowy w przeglądarce (`mode`: `webrtc`, `smallwebrtc`) albo czatu (`chat`). ## Odczyt rozmowy Po zakończeniu rozmowy pobierz przebieg (zebrane dane, czas trwania, koszt, SMS-y, linki do plików): ```bash theme={null} curl "https://app.brosbots.com/api/v1/agents/{agent_id}/conversations/{conversation_id}" \ -H "X-API-Key: bb_live_..." ``` | Pole | Znaczenie | | - | - | | `duration_seconds` | Czas trwania w pełnych sekundach; `null`, dopóki rozmowa trwa | | `gathered_context` | Dane zebrane przez agenta, w tym `call_disposition` | | `recording_download_url` / `transcript_download_url` | Podpisane linki HTTPS do nagrania (WAV) i transkrypcji (tekst). Nie wymagają klucza API | | `download_urls_expire_at` | Kiedy linki wygasają (1 h od zapytania). Po nowe linki pobierz przebieg ponownie | | `recording_url` / `transcript_url` | Klucze plików w magazynie (np. `recordings/580.wav`), **nie adresy URL**. Zostają dla zgodności z istniejącymi integracjami | Lista `GET /agents/{agent_id}/conversations` zwraca dla każdej rozmowy `initial_context`, `gathered_context` i `duration_seconds`, więc nie musisz dociągać szczegółów każdej z nich. Linki do pobrania, logi i SMS-y zwraca tylko widok pojedynczej rozmowy. ### Transkrypcja ```bash theme={null} curl "https://app.brosbots.com/api/v1/agents/{agent_id}/conversations/{conversation_id}/transcript" \ -H "X-API-Key: bb_live_..." ``` ```json theme={null} { "run_id": 580, "segments": [ { "role": "assistant", "text": "Dzień dobry, tu przychodnia.", "start": "2026-10-05T10:00:01+00:00", "end": "2026-10-05T10:00:02+00:00" }, { "role": "user", "text": "Chciałam się umówić.", "start": "2026-10-05T10:00:05+00:00", "end": "2026-10-05T10:00:05+00:00" } ], "download_url": "https://...", "expires_at": "2026-10-05T11:00:00+00:00" } ``` `role` to `user` (rozmówca) albo `assistant` (agent). Kolejne fragmenty tego samego mówcy są połączone w jedną wypowiedź; `start` i `end` to znaczniki czasu jej pierwszego i ostatniego fragmentu (plik nie zapisuje końca wypowiedzi). `download_url` prowadzi do surowego pliku tekstowego, w którym każdy fragment to osobna linia: ```text theme={null} [2026-10-05T10:00:01+00:00] assistant: Dzień dobry, [2026-10-05T10:00:02+00:00] assistant: tu przychodnia. [2026-10-05T10:00:05+00:00] user: Chciałam się umówić. ``` ### Nagranie ```bash theme={null} curl "https://app.brosbots.com/api/v1/agents/{agent_id}/conversations/{conversation_id}/recording?expires_in=600" \ -H "X-API-Key: bb_live_..." ``` Zwraca `download_url` (WAV), `content_type` i `expires_at`. `expires_in` to czas życia linku w sekundach, od 60 do 86400 (domyślnie 3600). Oba endpointy zwracają `404`, dopóki rozmowa trwa i plik nie został zapisany, oraz gdy plik usunęła polityka retencji. ## Usuwanie rozmowy ```bash theme={null} curl -X DELETE "https://app.brosbots.com/api/v1/agents/{agent_id}/conversations/{conversation_id}" \ -H "X-API-Key: bb_live_..." ``` Odpowiedź `204`. Usunięcie jest nieodwracalne: nagranie i transkrypcja znikają z magazynu plików, a z rozmowy - `initial_context` (w tym numer telefonu), `gathered_context`, logi, SMS-y wysłane w trakcie rozmowy i zapisy dostarczeń integracji. Rozmowa znika z historii, a endpointy przebiegu zwracają dla niej `404`. Czas trwania i koszt zostają w rozliczeniach organizacji, bo wymagają tego przepisy księgowe. Usunięcie nie cofa danych, które już wyszły z Brosbots: payloadów webhooka `call.completed`, wpisów w CRM czy wierszy w arkuszu. Usuń je u siebie. Rozmowy w toku nie da się usunąć (`409`). ## Konwencje * Ciała żądań i odpowiedzi są w JSON (`Content-Type: application/json`). * Znaczniki czasu w ISO 8601 ze strefą. * Listy stronicowane parametrami `page` / `limit`; odpowiedź zawiera `total_count` / `total_pages`. * Błędy używają standardowych kodów HTTP z ciałem JSON: ```json theme={null} { "detail": "czytelny powód błędu" } ``` | Status | Znaczenie | | - | - | | `400` | Błędne żądanie (np. kwota poniżej minimum, zły filtr) | | `401` | Brak lub nieprawidłowy klucz API | | `404` | Zasób nie istnieje lub należy do innej organizacji | | `409` | Konflikt (np. zasób już rozstrzygnięty) | | `422` | Błąd walidacji - ciało wskazuje pola | | `429` | Wszystkie kanały wychodzące zajęte - odczekaj tyle sekund, ile podaje nagłówek `Retry-After` | | `5xx` | Błąd serwera - żądania idempotentne można ponawiać | ## Limity API nie ma dziś stałego limitu liczby zapytań na klucz. Kod `429` zwracają endpointy dzwoniące (`POST /agents/{agent_id}/calls`, `POST /triggers/{trigger_id}/calls`), gdy wszystkie kanały wychodzące organizacji są zajęte; nagłówek `Retry-After` podaje, ile sekund odczekać. Połączenie poza godzinami 8:00-21:00 czasu odbiorcy kończy się kodem `409` z nagłówkiem `Retry-After` i polem `detail.retry_at`. Numer z listy Nie dzwonić organizacji kończy się kodem `403` z polem `detail` zaczynającym się od `do_not_call`. Obsługuj `429` ogólnie: czekaj tyle, ile mówi `Retry-After`, a gdy nagłówka nie ma - ponawiaj z wykładniczym odstępem. Limit zapytań może zostać wprowadzony w przyszłości. ## Interaktywna dokumentacja Zawsze aktualna, interaktywna referencja (Swagger UI): [`/api/v1/public-docs`](https://app.brosbots.com/api/v1/public-docs), a surowa specyfikacja OpenAPI: [`/api/v1/public-openapi.json`](https://app.brosbots.com/api/v1/public-openapi.json). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.