Przegląd

Quickchat AI udostępnia REST API zapewniające programistyczny dostęp do konfiguracji Twojego AI Agenta, Bazy Wiedzy, Rozmów, AI Actions i innych funkcji.

Authentication

Wszystkie endpointy API korzystają z uwierzytelniania za pomocą Bearer tokena. Dołącz swój token API w nagłówku Authorization każdego żądania:

Authorization: Bearer <API_TOKEN>

Tokeny tworzy się w Dashboardzie Quickchat w sekcji External Apps > API. Każdy token to JWT zawierający Twoje scenario_id, więc dodatkowy nagłówek identyfikujący nie jest potrzebny.

• Ważność tokena: 52 tygodnie od utworzenia
• Tokeny można odwołać w dowolnym momencie z Dashboardu
• Każdy token jest przypisany do jednego AI Agenta (scenariusza)
• Tworzenie tokenów wymaga planu Business lub wyższego; w niższych planach opcja jest wyłączona, a endpoint zwraca 402 Payment Required

Notatka

Endpoint Chat w czasie rzeczywistym (POST https://app.quickchat.ai/chat) akceptuje ten sam Bearer token co reszta tego API, ale znajduje się poza ścieżką bazową /v1/api/ i wymaga scenario_id w body żądania. Pełną dokumentację znajdziesz na stronie Chat.

Token Scopes

Tokeny API są tworzone z jednym z dwóch scope’ów:

Scope	Access Level	Description
read_all	Read-only	Może odczytywać wszystkie zasoby, ale nie może tworzyć, aktualizować ani usuwać
write_all	Read + Write	Pełny dostęp do wszystkich endpointów, w tym operacji zapisu

• Scope jest przypisywany do tokena podczas tworzenia w Dashboardzie w sekcji External Apps > API
• Scope write_all automatycznie obejmuje wszystkie uprawnienia read_all
• Użycie tokena read_all na endpoincie zapisu zwraca 403 z "Insufficient token scope. Required: write_all"

Wskazówka

Używaj tokenów read_all do monitorowania, analityki i integracji tylko do odczytu. Tokenów write_all używaj wyłącznie wtedy, gdy Twoja integracja musi tworzyć lub modyfikować zasoby.

Wymagania scope’ów według grup endpointów:

Endpoint Group	Read Operations	Write Operations
Chatbot Settings	read_all	write_all
Knowledge Base Settings	read_all	write_all
Articles	read_all	write_all
Article Language URLs	read_all	write_all
Tags	read_all	—
File Upload	—	write_all
Import External Content	—	write_all
Intercom Knowledge Base	read_all	write_all
Widget Configuration	read_all	write_all
Conversations	read_all	—
Conversation Metadata	read_all	write_all
Handoff Configuration	read_all	write_all
Conversation Rating	read_all	write_all
AI Actions	read_all	write_all

Base URL

Endpoint Group	Base URL
Knowledge Base, AI Actions, File Upload, Import, Chatbot Settings, Widget, Handoff, Conversation Rating	https://app.quickchat.ai/v1/api/
Conversations	https://app.quickchat.ai/v1/api_core/
Realtime Chat	https://app.quickchat.ai/chat

Rate Limits

Limity zapytań są stosowane per token, per endpoint.

Tier	Limit	Applies To
READ	120 requests/min	Operacje GET i listowania
WRITE	60 requests/min	POST, PATCH, PUT, DELETE
HEAVY	20 requests/min	Przesyłanie plików, importy, scrapowanie

Po przekroczeniu limitu zapytań API zwraca HTTP 429 Too Many Requests.

Pagination

Endpointy listujące obsługują paginację za pomocą parametrów zapytania:

Parameter	Description
limit integer	Liczba elementów na stronę
offset integer	Liczba elementów do pominięcia

Odpowiedzi z paginacją mają następującą strukturę:

{
  "items": [],
  "offset": 0,
  "limit": 10,
  "count": 100
}

Error Handling

Wszystkie błędy są zwracane jako JSON w następującym formacie:

{
  "errors": {
    "root": [
      {
        "message": "Description of the error",
        "code": "ERROR_CODE"
      }
    ]
  }
}

Status	Code	Description
400	BAD_REQUEST	Nieprawidłowe dane wejściowe lub brakujące wymagane pola
401	PERMISSION_DENIED	Nieprawidłowy, wygasły lub odwołany token
402	PAYMENT_REQUIRED	Wymagana aktywna subskrypcja
403	PERMISSION_DENIED	Token nie ma wymaganego scope’a dla tej operacji
404	NOT_FOUND	Zasób nie znaleziony
409	CONFLICT	Konflikt operacji (np. równoległa modyfikacja)
422	VALIDATION_ERROR	Body żądania nie przeszło walidacji schematu
429	TOO_MANY_REQUESTS	Przekroczono limit zapytań
500	UNKNOWN	Wewnętrzny błąd serwera
503	SERVICE_UNAVAILABLE	Tymczasowa niedostępność

---