API v2 – agenci i ustawienia

Za pomocą tych punktów końcowych zarządzasz agentami i ich ustawieniami. Każdy punkt końcowy na tej stronie wymaga nagłówka Authorization: Bearer YOUR_API_KEY. Trasy dotyczące konkretnego agenta zwracają 404 AGENT_NOT_FOUND, gdy agent nie istnieje lub nie należy do konta powiązanego z danym kluczem API.

Odpowiedzi z listami mają w przypadku powodzenia otoczkę z polami data i pagination. Odpowiedzi ze szczegółami agenta oraz jego ustawieniami są nieopakowanymi obiektami, bez otoczki data. Wspólne błędy uwierzytelniania i walidacji opisano w katalogu błędów.

Obiekt agenta

{
  "id": "955f28f1-8515-40bb-802c-f3f730bf0343",
  "name": "Support Agent",
  "url": "https://example.com",
  "createdAt": 1784332800,
  "settings": {
    "ai": {
      "model": "openai/gpt-5.6-luna",
      "instructionsPreset": "ai-chatbot",
      "instructionsPrompt": "Be helpful, accurate, and conversational."
    },
    "title": "AI Assistant",
    "branding": {
      "appearance": "Light",
      "bubbleColor": "#e9e9e7",
      "primaryColor": "#0a0a0a",
      "primaryColorHeader": false
    },
    "position": "bottom-right",
    "conversation": {
      "defaultPrompts": {
        "enabled": false,
        "prompts": [],
        "keepShowing": false
      },
      "initialMessages": ["Hey! What can I help with?"],
      "messagePlaceholder": "Ask our chatbot a question...",
      "showInitialMessageBubble": true
    },
    "features": {
      "attachments": true
    },
    "notification": {
      "dailyConversations": true,
      "dailyEmails": true,
      "quotaAlerts": true
    }
  }
}

Lista agentów

Ścieżka: /api/v2/agents

GET /api/v2/agents

Uwierzytelnianie: klucz API typu Bearer.

Sukces: 200 OK

curl 'https://your-domain.com/api/v2/agents?limit=20' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "data": [
    {
      "id": "955f28f1-8515-40bb-802c-f3f730bf0343",
      "name": "Support Agent",
      "url": "https://example.com/",
      "createdAt": 1784332800,
      "settings": {}
    }
  ],
  "pagination": {
    "cursor": null,
    "hasMore": false,
    "total": 1
  }
}

Nieprawidłowe wartości limit lub cursor skutkują błędem 400 VALIDATION_INVALID_BODY.

Tworzenie agenta

POST /api/v2/agents

Uwierzytelnianie: klucz API typu Bearer.

curl -X POST 'https://your-domain.com/api/v2/agents' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Support Agent","url":"https://example.com"}'

Sukces: 201 Created wraz z nieopakowanym obiektem agenta.

Nieprawidłowa treść żądania skutkuje błędem 400 VALIDATION_INVALID_BODY. Przekroczenie limitu agentów dostępnego w ramach obszaru roboczego skutkuje błędem 403 QUOTA_CHATBOT_LIMIT.

Pobieranie agenta

Ścieżka: /api/v2/agents/{agentId}

GET /api/v2/agents/{agentId}

Uwierzytelnianie: klucz API typu Bearer z dostępem do {agentId}.

Sukces: 200 OK wraz z nieopakowanym obiektem agenta.

curl 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Aktualizacja agenta

PATCH /api/v2/agents/{agentId}

Uwierzytelnianie: klucz API typu Bearer z dostępem do {agentId}.

Wymagane jest podanie co najmniej jednego pola.

curl -X PATCH 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Customer Support"}'

Sukces: 200 OK wraz z zaktualizowanym, nieopakowanym obiektem agenta. Nieprawidłowa lub pusta treść żądania skutkuje błędem 400 VALIDATION_INVALID_BODY.

Usuwanie agenta

DELETE /api/v2/agents/{agentId}

Uwierzytelnianie: klucz API typu Bearer z dostępem do {agentId}.

curl -X DELETE 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Sukces: 200 OK

{
  "deleted": true
}

Schemat ustawień AI

Ścieżka: /api/v2/agents/{agentId}/settings/ai

Aktualizacja ustawień AI wymaga podania co najmniej jednego pola.

Dla zachowania zgodności wstecznej pole model akceptuje również wycofane oznaczenia openai/gpt-5.5, openai/gpt-5.4, openai/gpt-5.4-mini, openai/gpt-5.4-nano, anthropic/claude-opus-4.7, anthropic/claude-opus-4-6, anthropic/claude-sonnet-4-6, google/gemini-3-flash-preview oraz google/gemini-3.6-flash. Istniejące agenty mogą nadal przechowywać te wartości (a metoda GET może je nadal zwracać), dzięki czemu cykl GET→PATCH zawsze przechodzi walidację — jednak nie są one już dostępne w selektorze modeli w panelu, a nowe integracje powinny korzystać z aktualnego katalogu powyżej.

Pobieranie ustawień AI

GET /api/v2/agents/{agentId}/settings/ai

Uwierzytelnianie: klucz API typu Bearer z dostępem do {agentId}.

Sukces: 200 OK. Obiekt ustawień AI jest zwracany bez opakowania; brak ustawionych wartości skutkuje zwróceniem {}.

{
  "model": "openai/gpt-5.6-luna",
  "instructionsPreset": "customer-support",
  "instructionsPrompt": "Answer using the support documentation."
}

Aktualizacja ustawień AI

PATCH /api/v2/agents/{agentId}/settings/ai

Uwierzytelnianie: klucz API typu Bearer z dostępem do {agentId}.

curl -X PATCH 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/settings/ai' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"model":"openai/gpt-5.6-luna","instructionsPreset":"customer-support"}'

Sukces: 200 OK wraz z zaktualizowanym obiektem ustawień AI, zwróconym bez opakowania. Niedostępny model skutkuje błędem 403 CHAT_MODEL_NOT_ALLOWED; nieprawidłowa lub pusta treść żądania skutkuje błędem 400 VALIDATION_INVALID_BODY.

Schemat ustawień wyglądu

Ścieżka: /api/v2/agents/{agentId}/settings/design

Aktualizacja ustawień wyglądu wymaga podania co najmniej jednego pola.

Pobieranie ustawień wyglądu

GET /api/v2/agents/{agentId}/settings/design

Uwierzytelnianie: klucz API typu Bearer z dostępem do {agentId}.

Sukces: 200 OK. Odpowiedź to nieopakowany obiekt zawierający aktualne grupy title, language, position, branding i conversation. Nieustawione klucze opcjonalne są pomijane.

{
  "title": "AI Assistant",
  "language": "en",
  "position": "bottom-right",
  "branding": {
    "appearance": "Light",
    "bubbleColor": "#e9e9e7",
    "primaryColor": "#0a0a0a",
    "primaryColorHeader": false
  },
  "conversation": {
    "defaultPrompts": {
      "enabled": false,
      "prompts": [],
      "keepShowing": false
    },
    "initialMessages": ["Hey! What can I help with?"],
    "messagePlaceholder": "Ask our chatbot a question...",
    "showInitialMessageBubble": true
  }
}

Aktualizacja ustawień wyglądu

PATCH /api/v2/agents/{agentId}/settings/design

Uwierzytelnianie: klucz API typu Bearer z dostępem do {agentId}.

curl -X PATCH 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/settings/design' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"title":"Support","language":"en-US","appearance":"Dark","prompts":["Track my order"]}'

Sukces: 200 OK. W przeciwieństwie do odpowiedzi GET dla ustawień wyglądu, PATCH zwraca pełny obiekt ustawień bez opakowania. Może on zawierać następujące pola i grupy najwyższego poziomu, jeśli są ustawione: title, language, position, branding, ai, conversation, security, guardrails, notification, training, channels i identityVerification. Aliasy językowe są zwracane i zapisywane w formie kanonicznej. Nieprawidłowa lub pusta treść żądania skutkuje błędem 400 VALIDATION_INVALID_BODY.

Schemat ustawień zabezpieczeń

Ścieżka: /api/v2/agents/{agentId}/settings/security

Aktualizacja ustawień zabezpieczeń wymaga podania co najmniej jednego pola najwyższego poziomu.

Pobieranie ustawień zabezpieczeń

GET /api/v2/agents/{agentId}/settings/security

Uwierzytelnianie: klucz API typu Bearer z dostępem do {agentId}.

Sukces: 200 OK. Obiekt zabezpieczeń jest zwracany bez opakowania; brak ustawionych wartości skutkuje zwróceniem {}.

{
  "isPrivate": false,
  "rateLimit": {
    "maxMessages": 20,
    "windowSeconds": 240,
    "limitMessage": "Too many messages in a row"
  },
  "allowedDomains": {
    "enabled": true,
    "domains": ["https://example.com"]
  }
}

Aktualizacja ustawień zabezpieczeń

PATCH /api/v2/agents/{agentId}/settings/security

Uwierzytelnianie: klucz API typu Bearer z dostępem do {agentId}.

curl -X PATCH 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/settings/security' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"allowedDomains":{"enabled":true,"domains":["https://example.com"]}}'

Sukces: 200 OK wraz z zaktualizowanym obiektem ustawień zabezpieczeń, zwróconym bez opakowania. Nieprawidłowa lub pusta treść żądania skutkuje błędem 400 VALIDATION_INVALID_BODY.

Schemat ustawień powiadomień

Ścieżka: /api/v2/agents/{agentId}/settings/notifications

Wymagane jest podanie co najmniej jednego pola.

Pominięte dailyConversations zachowuje się jak false (wyłączone); pominięte dailyEmails i quotaAlerts zachowują się jak true (włączone). Odpowiedź GET zwraca tylko pola ustawione jawnie.

Pobieranie ustawień powiadomień

GET /api/v2/agents/{agentId}/settings/notifications

Uwierzytelnianie: klucz API typu Bearer z dostępem do {agentId}.

Sukces: 200 OK. Obiekt powiadomień jest zwracany bez opakowania; brak ustawionych wartości skutkuje zwróceniem {}.

{
  "dailyConversations": true,
  "dailyEmails": true,
  "quotaAlerts": true
}

Aktualizacja ustawień powiadomień

PATCH /api/v2/agents/{agentId}/settings/notifications

Uwierzytelnianie: klucz API typu Bearer z dostępem do {agentId}.

curl -X PATCH 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/settings/notifications' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"dailyConversations":false}'

Sukces: 200 OK wraz z zaktualizowanym obiektem ustawień powiadomień, zwróconym bez opakowania. Nieprawidłowa lub pusta treść żądania skutkuje błędem 400 VALIDATION_INVALID_BODY.

Schemat ustawień trenowania

Ścieżka: /api/v2/agents/{agentId}/settings/training

Pobieranie ustawień trenowania

GET /api/v2/agents/{agentId}/settings/training

Uwierzytelnianie: klucz API typu Bearer z dostępem do {agentId}.

Sukces: 200 OK. Obiekt ustawień trenowania jest zwracany bez opakowania; brak ustawionych wartości skutkuje zwróceniem {}.

{
  "autoRetrainEnabled": true
}

Aktualizacja ustawień trenowania

PATCH /api/v2/agents/{agentId}/settings/training

Uwierzytelnianie: klucz API typu Bearer z dostępem do {agentId}.

curl -X PATCH 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/settings/training' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"autoRetrainEnabled":true}'

Sukces: 200 OK wraz z zaktualizowanym obiektem ustawień trenowania, zwróconym bez opakowania. Włączenie automatycznego ponownego trenowania bez dostępu w ramach planu skutkuje błędem 403 SUBSCRIPTION_API_RESTRICTED_PLAN; nieprawidłowa treść żądania skutkuje błędem 400 VALIDATION_INVALID_BODY.

Powiązane materiały

• Przegląd API v2
• Katalog błędów API v2
• Źródła i trenowanie