API bazy wiedzy

Twoja baza wiedzy to źródło, z którego korzysta sztuczna inteligencja. Składa się ona z dwóch części, a ta strona omawia obie z nich:

Źródła wiedzy (/kb-sources) — strony internetowe i przesłane dokumenty, które dostarczasz platformie. Każde z nich jest odczytywane, dzielone na sekcje i przekształcane w odpowiedzi na często zadawane pytania (FAQ), z których może korzystać Twoja sztuczna inteligencja.
Grupy wiedzy (/kb-groups) — nazwane zestawy FAQ, które możesz zastosować do Agenta lub kampanii w jednym wywołaniu, dzięki czemu raz przygotowany zasób wiedzy można ponownie wykorzystać w kolejnym tworzonym Agencie.

FAQ wygenerowane ze źródła trafiają do tej samej biblioteki, co te napisane ręcznie, więc po zakończeniu importu możesz je przeglądać, edytować i łączyć za pomocą API FAQ.

Wszystkie poniższe punkty końcowe odnoszą się do bazowego adresu URL https://api.youraiconnector.com/v1. Każde żądanie musi zostać uwierzytelnione — zobacz Dostęp do API oraz Uwierzytelnianie. Dostęp do API jest funkcją płatną; bez niego żądania będą odrzucane z błędem 403.

Importowanie kosztuje kredyty. Odczytanie strony lub dokumentu i utworzenie z nich FAQ zużywa kredyty, mniej więcej proporcjonalnie do ilości zawartości. Skorzystaj z Szacowania importu przed rozpoczęciem dużego procesu indeksowania.

Jak działa import

Importowanie to zadanie działające w tle, a nie proces, który kończy się natychmiast. Każdy punkt końcowy importu odpowiada natychmiast za pomocą source_id, a Ty odpytujesz to źródło, aż do zakończenia procesu:

Rozpocznij import — POST /kb-sources/url (jedna strona), POST /kb-sources/file (przesłany dokument) lub POST /kb-sources/bulk-import (do 100 stron). Otrzymasz identyfikator źródła oraz status: "queued".
Odpytuj — GET /kb-sources/{sourceId}, aż status przestanie mieć wartość queued lub processing.
Odczytaj FAQ — gdy status to ready, wygenerowane wpisy znajdują się w Twojej bibliotece FAQ: GET /faqs.

Każde źródło zgłasza jeden z następujących statusów:

Status	Co to oznacza
`queued`	Oczekiwanie na odczytanie. Jeszcze nie pobrano opłat.
`processing`	Trwa odczytywanie i przekształcanie w FAQ.
`ready`	Zakończono. FAQ znajdują się w Twojej bibliotece.
`failed`	Nie udało się zaimportować. `error_message` wyjaśnia dlaczego.
`cancelled`	Zatrzymano przed odczytaniem (zobacz Zatrzymanie importu).
`paused`	Zatrzymano, ponieważ Twój klucz AI zawiódł w trakcie importu (zobacz Wznawianie wstrzymanego importu).
`deleting`	Trwa masowe usuwanie danych.
`unknown`	Rekord nie posiada statusu. Traktuj go jako niegotowy.

Dołączaj podczas importu. Przekaż autoLinkToAgentId w dowolnym punkcie końcowym importu, a źródło — wraz ze wszystkimi wygenerowanymi przez nie FAQ — trafi do bazy wiedzy Agenta w tym samym wywołaniu, bez konieczności wykonywania dodatkowego kroku łączenia. autoLinkToCampaignId robi to samo dla klasycznej kampanii. Łączenie odbywa się w miarę możliwości: identyfikator, który nie istnieje lub należy do innego konta, jest pomijany bez powiadomienia, a import nadal trwa, więc potwierdź połączenie, odczytując dane Agenta.

Importowanie strony internetowej

POST /kb-sources/url

Dodaje jedną stronę internetową do Twojej bazy wiedzy.

Pola żądania

Pole	Wymagane	Opis
`url`	Tak	Pełny adres `http` lub `https` strony.
`autoLinkToAgentId`	Nie	Identyfikator agenta AI, do którego ma zostać przypisane importowane źródło.
`autoLinkToCampaignId`	Nie	Starsza wersja. Identyfikator kampanii, do której ma zostać przypisane importowane źródło.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/url?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/pricing",
    "autoLinkToAgentId": "ag7HkQ2ZpLxR3mNb"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/kb-sources/url", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://example.com/pricing",
    autoLinkToAgentId: "ag7HkQ2ZpLxR3mNb",
  }),
});
const { source_id } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/kb-sources/url",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "url": "https://example.com/pricing",
        "autoLinkToAgentId": "ag7HkQ2ZpLxR3mNb",
    },
)
source_id = res.json().get("source_id")

Odpowiedź — 202 Accepted

{
  "success": true,
  "source_id": "kb_src_abc123",
  "status": "queued",
  "batch_id": "batch_9f2a"
}

Odpytuj source_id za pomocą Sprawdź źródło, aż status będzie ready lub failed.

Jeśli ta sama strona znajduje się już w Twojej bazie wiedzy, nic nowego nie zostanie dodane do kolejki i otrzymasz 200 — a jeśli poprosiłeś o automatyczne połączenie, istniejące źródło zostanie dla Ciebie powiązane:

{
  "success": true,
  "status": "exists",
  "skipped_duplicate": 1
}

Brakujący url lub adres, który nie jest poprawnym adresem http/https, zwraca 400.

Importuj przesłany dokument

POST /kb-sources/file

Dodaje dokument, który znajduje się już w pamięci plików Twojego konta, jako źródło wiedzy. Obsługiwane typy: PDF, DOCX, TXT, MD, CSV i XLSX.

Ten punkt końcowy nie przesyła pliku. Nie ma tu przesyłania wieloczęściowego (multipart), treści base64 ani pobierania z adresu URL: wysyłasz lokalizację pliku, który już istnieje, i musi on znajdować się w Twoim własnym folderze przesyłania (storage_path musi zaczynać się od users/{your user id}/uploads/), w przeciwnym razie żądanie zostanie odrzucone z 403. Panel sterowania umieszcza tam pliki, gdy przeciągniesz je do okna. Jeśli nie masz możliwości umieszczenia tam pliku, zaimportuj stronę internetową za pomocą Importuj stronę internetową.

Pola żądania

Pole	Wymagane	Opis
`storage_path`	Tak	Gdzie znajduje się przesłany plik. Musi zaczynać się od `users/{your user id}/uploads/`.
`filename`	Tak	Oryginalna nazwa pliku wraz z rozszerzeniem — w ten sposób wykrywany jest typ pliku.
`mime_type`	Tak	Typ MIME pliku, na przykład `application/pdf`.
`autoLinkToAgentId`	Nie	Identyfikator agenta AI, do którego ma zostać przypisany dokument.
`autoLinkToCampaignId`	Nie	Starsza wersja. Identyfikator kampanii, do której ma zostać przypisany dokument.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/file?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "storage_path": "users/abc123uid/uploads/handbook.pdf",
    "filename": "handbook.pdf",
    "mime_type": "application/pdf",
    "autoLinkToAgentId": "ag7HkQ2ZpLxR3mNb"
  }'

Odpowiedź — 202 Accepted

{
  "success": true,
  "source_id": "kb_src_abc123",
  "status": "queued"
}

Status	Kiedy
`400`	Brakuje wymaganego pola lub plik jest typu, którego nie możemy odczytać.
`403`	`storage_path` znajduje się poza Twoim własnym folderem przesyłania.

Sprawdź źródło

GET /kb-sources/{sourceId}

Odpytywanie, które następuje po każdym imporcie i odświeżeniu. Powtarzaj je, aż status będzie ready lub failed.

cURL

curl "https://api.youraiconnector.com/v1/kb-sources/kb_src_abc123?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/kb-sources/kb_src_abc123",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const source = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/kb-sources/kb_src_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
source = res.json()

Odpowiedź

{
  "success": true,
  "source_id": "kb_src_abc123",
  "status": "ready",
  "faq_count": 24,
  "section_count": 31,
  "error_message": null
}

Pole	Typ	Opis
`status`	string	Gdzie znajduje się źródło w potoku (zobacz tabelę statusów).
`faq_count`	integer	Ile FAQ zostało wygenerowanych z tego źródła do tej pory.
`section_count`	integer	Na ile sekcji treści zostało podzielone źródło.
`error_message`	string \| null	Dlaczego import się nie powiódł, gdy status to `failed`. W przeciwnym razie `null`.

Usuwanie źródła

DELETE /kb-sources/{sourceId}

Usuwa jedno źródło wiedzy. Domyślnie wygenerowane przez nie FAQ są zachowywane — dodaj delete_faqs=true, aby usunąć również je.

Parametry zapytania

Parametr	Wymagane	Opis
`delete_faqs`	Nie	Ustaw na `true`, aby usunąć również każde FAQ wygenerowane przez to źródło. Domyślnie `false`.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/kb-sources/kb_src_abc123?delete_faqs=true&apiKey=YOUR_API_KEY"

Odpowiedź

{
  "success": true,
  "faqs_deleted": 24
}

faqs_deleted to 0, chyba że poprosisz o delete_faqs=true.

Importowanie wielu stron jednocześnie

POST /kb-sources/bulk-import

Dodaje do 100 stron internetowych w jednym wywołaniu — jest to typowy krok po Odkrywaniu stron w witrynie lub Wyszukiwaniu nowych stron w witrynie. Strony, które już znajdują się w Twojej bazie wiedzy, są pomijane zamiast duplikowania (i nadal są powiązane z Agentem, jeśli o to poprosisz).

Pola żądania

Pole	Wymagane	Opis
`urls`	Tak	Adresy do zaimportowania. Co najmniej 1, maksymalnie 100 na wywołanie.
`autoLinkToAgentId`	Nie	Identyfikator Agenta AI, do którego należy przypisać każdą zaimportowaną stronę.
`autoLinkToCampaignId`	Nie	Starsza wersja. Identyfikator kampanii, do której należy przypisać każdą zaimportowaną stronę.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/bulk-import?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://example.com/pricing", "https://example.com/faq"],
    "autoLinkToAgentId": "ag7HkQ2ZpLxR3mNb"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/kb-sources/bulk-import", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    urls: ["https://example.com/pricing", "https://example.com/faq"],
    autoLinkToAgentId: "ag7HkQ2ZpLxR3mNb",
  }),
});
const { queued_source_ids } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/kb-sources/bulk-import",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "urls": ["https://example.com/pricing", "https://example.com/faq"],
        "autoLinkToAgentId": "ag7HkQ2ZpLxR3mNb",
    },
)
queued_source_ids = res.json()["queued_source_ids"]

Odpowiedź — 202 Accepted

{
  "success": true,
  "batch_id": "batch_9f2a",
  "queued": 2,
  "skipped_duplicate": 0,
  "queued_source_ids": ["kb_src_abc123", "kb_src_def456"]
}

Odpytuj każdy identyfikator w queued_source_ids za pomocą Sprawdź źródło. Przesłanie pustej tablicy urls, wpisu niebędącego ciągiem znaków lub więcej niż 100 wpisów zwróci 400.

Usuwanie wielu źródeł jednocześnie

POST /kb-sources/bulk-delete

Usuwa do 2000 źródeł wiedzy w jednym wywołaniu. Usuwanie odbywa się w tle, a po jego zakończeniu otrzymasz wiadomość e-mail.

Masowe usuwanie zawsze usuwa również FAQ. W przeciwieństwie do Usuwania źródła, które zachowuje je, chyba że zaznaczysz inaczej, ten punkt końcowy usuwa każde źródło wraz z wygenerowanymi przez nie FAQ. Nie ma opcji ich zachowania.

Pola żądania

Pole	Wymagane	Opis
`sourceIds`	Tak	Identyfikatory źródeł do usunięcia. Co najmniej 1, maksymalnie 2000 na wywołanie.
`domainLabel`	Nie	Przyjazna nazwa dla tego czyszczenia. Używana tylko w wiadomości e-mail o zakończeniu.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/bulk-delete?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceIds": ["kb_src_abc123", "kb_src_def456"],
    "domainLabel": "example.com"
  }'

Odpowiedź — 202 Accepted

{
  "success": true,
  "batch_id": "del_batch_31a",
  "queued": 2
}

Odkrywanie stron w witrynie

POST /kb-sources/discover-pages

Przeszukuje witrynę od wskazanego adresu początkowego i wyświetla listę stron znalezionych w tej samej domenie, z oceną, czy warto je zaimportować. Nic nie jest importowane i nic nie jest wybierane automatycznie — jest to krok „co znajduje się w tej witrynie”, który wykonujesz przed podjęciem decyzji, co wysłać do Importu wielu stron jednocześnie.

Pola żądania

Pole	Wymagane	Opis
`url`	Tak	Adres, od którego należy rozpocząć przeszukiwanie, zazwyczaj strona główna witryny.
`maxPages`	Nie	Górny limit liczby stron do zwrócenia.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/discover-pages?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com", "maxPages": 100 }'

Odpowiedź

{
  "success": true,
  "source_type": "sitemap",
  "pages": [
    {
      "url": "https://example.com/pricing",
      "title": "Pricing",
      "depth": 1,
      "score": 95,
      "recommendation": "add",
      "reason_key": "core_page"
    }
  ]
}

Pole	Typ	Opis
`source_type`	string	Sposób znalezienia stron — `sitemap` (własna mapa witryny) lub `link_discovery` (poprzez śledzenie linków).
`url`	string	Pełny adres strony.
`title`	string \| null	Tytuł strony, jeśli udało się go odczytać.
`depth`	integer	Jak daleko od strony początkowej znaleziono tę stronę (liczba linków).
`score`	integer	Jak użyteczna wydaje się strona jako wiedza, od `0` do `100`.
`recommendation`	string	`add` (zdecydowanie warto zaimportować, wynik 90 lub wyższy), `maybe` (na granicy) lub `skip` (treści rzadko przydatne dla asystenta — dzienniki zmian, strony prawne, zduplikowane tłumaczenia).
`reason_key`	string	Stabilny, czytelny dla maszyny powód rekomendacji, na przykład `core_page`, `changelog_history`, `legal_page` lub `locale_duplicate`.

Eksploracja jest wykonywana w miarę możliwości. Jeśli witryny nie można odczytać, odpowiedź to nadal 200, z success: false, pustą listą pages i komunikatem error. Sprawdź success przed odczytaniem pages.

Brakujący url zwraca 400.

Szacowanie kosztów importu

POST /kb-sources/estimate-cost

Oblicza, ile kredytów zużyłby proponowany import, zanim go zatwierdzisz. Strony są pobierane, a dokumenty odczytywane w celu zmierzenia ich rozmiaru, ale nic nie jest importowane, a samo oszacowanie nie zużywa kredytów.

Pola żądania

Pole	Wymagane	Opis
`urls`	Nie	Adresy stron, które rozważasz zaimportować.
`files`	Nie	Już przesłane pliki, które rozważasz. Każdy wpis wymaga `storage_path`, `filename` i `mime_type`.
`tier`	Nie	Poziom jakości AI, na którym zostanie uruchomiony import, aby szacunek odpowiadał kwocie, która zostanie faktycznie pobrana. Pozostaw puste dla stawki standardowej.

Wyślij urls, files lub oba.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/estimate-cost?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "urls": ["https://example.com/pricing"] }'

Odpowiedź

{
  "success": true,
  "estimates": [
    { "ref": "https://example.com/pricing", "chunks": 7, "credits": 7 }
  ],
  "total_chunks": 7,
  "total_credits": 7
}

Każdy wiersz odzwierciedla adres URL lub ścieżkę przechowywania w ref, dzięki czemu można dopasować go do danych wejściowych. Strona lub plik, których nie udało się odczytać, również otrzymują wiersz, liczony jako jeden fragment, z oznaczeniem error.

Zatrzymanie importu

POST /kb-sources/cancel-import

Zatrzymuje strony, które wciąż oczekują w kolejce importu — przycisk „zatrzymaj import” dla indeksowania, które okazało się większe, niż oczekiwano. Anulowanie oczekującej strony nic nie kosztuje, ponieważ nie została ona jeszcze odczytana.

Strony, które są już przetwarzane, nie zostają zatrzymane: ich przetwarzanie trwa i jest naliczane w każdym przypadku, więc zostaną ukończone. Odpowiedź zawiera informację, ile takich stron było.

Pola żądania

Pole	Wymagane	Opis
`host`	Nie	Zatrzymaj tylko oczekujące strony w tej witrynie (na przykład `docs.example.com`). Pozostaw puste, aby zatrzymać każdy oczekujący import na koncie.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/cancel-import?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "host": "docs.example.com" }'

Odpowiedź

{
  "success": true,
  "cancelled": 412,
  "in_flight": 3
}

Wznawianie wstrzymanego importu

POST /kb-sources/resume-import

Restartuje import, który został wstrzymany, ponieważ Twój własny klucz AI przestał działać.

Wywołanie tego jest Twoją zgodą na dokończenie importu przy użyciu klucza, który jest aktualnie aktywny — co może oznaczać zużycie kredytów platformy, jeśli Twój własny klucz nadal nie działa.

Pola żądania

Pole	Wymagane	Opis
`host`	Nie	Wznów tylko wstrzymane strony w tej witrynie. Pozostaw puste, aby wznowić wszystko, co zostało wstrzymane.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/resume-import?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Odpowiedź

{
  "success": true,
  "resumed": 58
}

Znajdowanie nowych stron w witrynie

POST /kb-sources/refresh-domain

Przeszukuje witrynę, z której już importowano dane, i zgłasza tylko te strony, których nie ma jeszcze w Twojej bazie wiedzy, każdą z taką samą rekomendacją jak w przypadku odkrywania stron. Nic nie jest importowane i nic nie jest zmieniane.

Dwa kolejne kroki są celowo oddzielnymi wywołaniami, więc zrezygnowanie z tego etapu nic nie kosztuje:

zaimportuj nowe strony, których potrzebujesz, korzystając z Importuj wiele stron jednocześnie;
odśwież strony, które już posiadasz, korzystając z Odśwież każdą stronę w witrynie.

Pola żądania

Pole	Wymagane	Opis
`baseUrl`	Tak	Dowolny adres w witrynie lub tylko host.
`maxPages`	Nie	Górna granica liczby stron do przeszukania.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/refresh-domain?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "baseUrl": "https://example.com" }'

Odpowiedź

{
  "success": true,
  "source_type": "sitemap",
  "discovered": 249,
  "new_pages": [
    {
      "url": "https://example.com/new-guide",
      "score": 95,
      "recommendation": "add",
      "reason_key": "core_page"
    }
  ],
  "new_urls_queued": 0,
  "existing_refresh_queued": 249
}

Pole	Typ	Opis
`discovered`	liczba całkowita	Łączna liczba stron znalezionych w witrynie.
`new_pages`	tablica	Strony, których nie ma jeszcze w Twojej bazie wiedzy. Nic nie jest dla Ciebie kolejkowane — zaimportuj te, które chcesz.
`new_urls_queued`	liczba całkowita	Zawsze `0`. Zachowane dla kompatybilności wstecznej; ten punkt końcowy nigdy niczego nie kolejkuje.
`existing_refresh_queued`	liczba całkowita	Liczba stron już zaimportowanych z tej witryny, które zostały uznane za gotowe do ponownego odczytania. To wywołanie niczego nie kolejkuje.
`batch_id`	ciąg znaków	Obecne tylko wtedy, gdy utworzono partię.

Podobnie jak w przypadku wykrywania, kończy się to łagodnym niepowodzeniem: witryna, której nie można odczytać, nadal zwraca 200, z success: false, pustym new_pages oraz error. Brakujący lub pusty baseUrl zwraca 400.

Odśwież każdą stronę w witrynie

POST /kb-sources/trigger-domain-refresh

Ponownie odczytuje każdą stronę, która została już zaimportowana z witryny, dzięki czemu jej sekcje FAQ są zgodne z aktualną zawartością witryny: zmienione sekcje są aktualizowane, nowe dodawane, a usunięte usuwane.

To kolejkuje zadanie i zwraca odpowiedź natychmiast. Następnie użyj Śledź odświeżanie witryny, a aby je zatrzymać, użyj Zatrzymaj odświeżanie witryny.

Pola żądania

Pole	Wymagane	Opis
`baseUrl`	Tak	Dowolny adres w witrynie lub tylko host.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/trigger-domain-refresh?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "baseUrl": "https://example.com" }'

Odpowiedź

{
  "success": true,
  "queued": 249
}

Śledź odświeżanie witryny

GET /kb-sources/domain-refresh-status

Informacja o postępie odświeżania witryny, dzięki której możesz wyświetlić postęp, np. „221 z 249”.

Parametry zapytania

Parametr	Wymagane	Opis
`baseUrl`	Tak	Dowolny adres w witrynie lub tylko host.

cURL

curl "https://api.youraiconnector.com/v1/kb-sources/domain-refresh-status?baseUrl=https://example.com&apiKey=YOUR_API_KEY"

Odpowiedź

{
  "success": true,
  "job": {
    "domainBatchId": "job_7c1e",
    "host": "example.com",
    "total": 249,
    "pending": 28,
    "succeeded": 219,
    "failed": 2,
    "skippedDuplicate": 0,
    "status": "refreshing",
    "startedAtIso": "2026-06-15T09:00:00.000Z"
  }
}

job wynosi null, gdy dla danej witryny nie jest uruchomione żadne odświeżanie. Liczba ukończonych stron to total minus pending. Zadanie status jest jednym z refreshing (trwa przetwarzanie stron), deduplicating (końcowe czyszczenie) lub finalnym completed, failed i cancelled. Zachowaj domainBatchId — to identyfikator, który przekazujesz do punktu końcowego anulowania.

Brakujący lub pusty baseUrl zwraca 400.

Zatrzymaj odświeżanie witryny

POST /kb-sources/refresh-domain/cancel

Zatrzymuje odświeżanie witryny, które wciąż przetwarza swoje strony. Strony, które zostały już ukończone, zachowują zaktualizowaną zawartość; strony, których przetwarzanie nie zostało rozpoczęte, są pomijane, a strony, które były w trakcie ponownego odczytu, wracają do swojego poprzedniego stanu.

Pola żądania

Pole	Wymagane	Opis
`jobId`	Tak	`domainBatchId` zwrócony przez Śledzenie odświeżania witryny.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/refresh-domain/cancel?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "jobId": "job_7c1e" }'

Odpowiedź

{
  "success": true,
  "status": "cancelled",
  "cancelled_units": 28,
  "sources_reset": 3,
  "sources_cancelled": 25
}

Pole	Typ	Opis
`status`	string	Stan odświeżania po tym wywołaniu: `cancelled`, `deduplicating`, `completed` lub `failed`.
`cancelled_units`	integer	Ilość pracy, która pozostała do wykonania w momencie anulowania. `0` w przypadku ponownego anulowania.
`sources_reset`	integer	Strony wycofane z przetwarzania i przywrócone do `ready`.
`sources_cancelled`	integer	Całkowicie nowe strony tego odświeżania, które były w kolejce i zostały teraz anulowane.

Dwukrotne anulowanie jest nieszkodliwe — drugie wywołanie zgłasza ten sam stan końcowy. Gdy odświeżanie przejdzie do etapu czyszczenia, nie można go już zatrzymać, a odpowiedź powraca z success: false i reason: "already_finalizing". Brakujący jobId zwraca 400, a zadanie, którego nie ma na Twoim koncie, zwraca 404.

Odśwież pojedyncze źródło

POST /kb-sources/{sourceId}/refresh

Ponownie odczytuje jedną stronę internetową, która została już zaimportowana, i dostosowuje zawarte na niej FAQ do bieżącej zawartości strony: zmienione sekcje są aktualizowane, nowe dodawane, a usunięte usuwane.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/kb_src_abc123/refresh?apiKey=YOUR_API_KEY"

Odpowiedź — 202 Accepted

{
  "success": true,
  "source_id": "kb_src_abc123",
  "status": "queued"
}

Odpytuj źródło, aż jego status przestanie być queued i processing. Identyfikator źródła, którego nie ma na Twoim koncie, zwraca 404.

Wybierz najbardziej odpowiednie strony

POST /kb-sources/select-relevant-pages

Prosi AI o wybranie pięciu stron z listy kandydatów, które najlepiej opisują firmę — używane podczas generowania scenariusza kampanii na podstawie witryny internetowej. Ta operacja zużywa kredyty.

Pola żądania

Pole	Wymagane	Opis
`urls`	Tak	Adresy stron kandydujących do wyboru, zazwyczaj z wykrywania stron.
`homeUrl`	Tak	Strona główna witryny, używana jako kontekst dla wyboru.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/select-relevant-pages?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "homeUrl": "https://example.com",
    "urls": ["https://example.com/about", "https://example.com/pricing"]
  }'

Odpowiedź

{
  "success": true,
  "pages": [
    { "url": "https://example.com/pricing", "title": "Pricing", "type": "pricing" }
  ]
}

Jest to pomocnik, a nie zasób: w przypadku niepowodzenia nadal odpowiada 200, z success: false, pustą listą pages oraz komunikatem error.

Grupy wiedzy

Grupa wiedzy to nazwany zestaw FAQ — „Wysyłka i zwroty”, „Wdrożenie” — który można zastosować do agenta lub kampanii za pomocą jednego wywołania. Grupa przechowuje odwołania, a nie kopie: same FAQ pozostają w Twojej pojedynczej bibliotece, więc edycja jednego z nich za pomocą API FAQ aktualizuje je wszędzie, gdzie jest używane.

Zastosowanie grupy zawsze tylko dodaje to, czego brakuje, więc dwukrotne zastosowanie tej samej grupy jest nieszkodliwe, a added_count za drugim razem zwraca 0.

Tworzenie grupy wiedzy

POST /kb-groups

Tworzy grupę. Na początku jest ona pusta — dodaj do niej FAQ za pomocą Dodaj FAQ do grupy.

Pola żądania

Pole	Wymagane	Opis
`name`	Tak	Nazwa grupy.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-groups?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Shipping and returns" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/kb-groups", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "Shipping and returns" }),
});
const { group_id } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/kb-groups",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"name": "Shipping and returns"},
)
group_id = res.json()["group_id"]

Odpowiedź — 201 Created

{
  "success": true,
  "group_id": "kbg_abc123"
}

Zmiana nazwy grupy wiedzy

PUT /kb-groups/{groupId}

Zmienia nazwę grupy. Zawarte w niej FAQ pozostają nienaruszone.

Pola żądania

Pole	Wymagane	Opis
`name`	Tak	Nowa nazwa grupy.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Shipping, returns and refunds" }'

Odpowiedź

{
  "success": true,
  "group_id": "kbg_abc123",
  "name": "Shipping, returns and refunds"
}

Usuwanie grupy wiedzy

DELETE /kb-groups/{groupId}

Usuwa grupę. Usuwany jest tylko zestaw — zawarte w nim FAQ pozostają w Twojej bibliotece, a wszystko, do czego grupa była już zastosowana, zachowuje te FAQ.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123?apiKey=YOUR_API_KEY"

Odpowiedź

{
  "success": true
}

Dodaj FAQ do grupy

POST /kb-groups/{groupId}/faqs

Umieszcza istniejące FAQ w grupie. Zmienia to tylko pakiet — samo w sobie nie przypisuje FAQ do żadnego Agenta; w tym celu należy zastosować grupę.

Pola żądania

Pole	Wymagane	Opis
`faq_id`	Tak	ID FAQ do dodania.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/faqs?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "faq_id": "aBcD1234eFgH5678" }'

Odpowiedź

{
  "success": true,
  "group_id": "kbg_abc123",
  "faq_id": "aBcD1234eFgH5678"
}

Usuń FAQ z grupy

DELETE /kb-groups/{groupId}/faqs/{faqId}

Usuwa FAQ z grupy. Samo FAQ nie jest usuwane, a Agenci, do których grupa została już zastosowana, zachowują je.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/faqs/aBcD1234eFgH5678?apiKey=YOUR_API_KEY"

Odpowiedź

{
  "success": true,
  "group_id": "kbg_abc123",
  "faq_id": "aBcD1234eFgH5678"
}

Zastosuj grupę do Agenta

POST /kb-groups/{groupId}/apply-to-agent

Dodaje każde FAQ z grupy do wiedzy Agenta AI w jednym wywołaniu — to szybki sposób na przekazanie nowemu Agentowi bazy wiedzy, którą już przygotowałeś.

Pola żądania

Pole	Wymagane	Opis
`agent_id`	Tak	ID Agenta AI, do którego ma zostać zastosowana grupa.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/apply-to-agent?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agent_id": "ag7HkQ2ZpLxR3mNb" }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/apply-to-agent",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ agent_id: "ag7HkQ2ZpLxR3mNb" }),
  }
);
const { added_count } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/apply-to-agent",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"agent_id": "ag7HkQ2ZpLxR3mNb"},
)
added_count = res.json()["added_count"]

Odpowiedź

{
  "success": true,
  "group_id": "kbg_abc123",
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "added_count": 12
}

added_count to liczba faktycznie dodanych FAQ — 0, gdy grupa jest pusta lub już została zastosowana.

Zastosuj grupę do kampanii

POST /kb-groups/{groupId}/apply-to-campaign

Wersja powyższego wywołania dla klasycznych kampanii. Na koncie opartym na Agentach użyj zamiast tego Zastosuj grupę do Agenta.

Pola żądania

Pole	Wymagane	Opis
`campaign_id`	Tak	Identyfikator kampanii, do której ma zostać przypisana grupa.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/apply-to-campaign?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "campaign_id": "campaign123" }'

Odpowiedź

{
  "success": true,
  "group_id": "kbg_abc123",
  "campaign_id": "campaign123",
  "added_count": 12
}

Błędy API bazy wiedzy

Te punkty końcowe zwracają standardową kopertę błędu:

{
  "success": false,
  "error": "Knowledge base source not found."
}

Status	Kiedy występuje w punkcie końcowym bazy wiedzy
`400`	Brakuje wymaganego pola lub jest ono nieprawidłowe — puste `url`, brak `baseUrl` lub `jobId`, więcej niż 100 adresów URL w imporcie zbiorczym, więcej niż 2000 identyfikatorów w usuwaniu zbiorczym lub nieobsługiwany typ pliku.
`402`	Niewystarczająca liczba kredytów do przeprowadzenia importu. Doładuj konto i spróbuj ponownie.
`403`	`storage_path` poza własnym folderem przesyłania — lub Twój plan nie obejmuje dostępu do API.
`404`	Nie znaleziono źródła, grupy, FAQ, agenta, kampanii lub zadania odświeżania — albo nie istnieje, albo należy do innego konta.

Błędy miękkie nie są błędami. Odkrywanie (discover-pages, refresh-domain) oraz pomocnik wyboru stron odpowiadają 200 za pomocą success: false i komunikatu error, gdy witryna nie może zostać odczytana, zamiast przerywać żądanie. Zawsze sprawdzaj success przed odczytaniem danych.

Wspólne kody, które może zwrócić każdy punkt końcowy — 401, 403 (Twój plan nie obejmuje dostępu do API), 429 (limit szybkości) oraz 500 — zostały wymienione wraz ze wskazówkami dotyczącymi ponawiania prób w sekcji Błędy i stronicowanie.

Powiązane

API FAQ — odczytuj, edytuj i łącz FAQ tworzone przez Twoje źródła.
Zarządzanie FAQ — ta sama baza wiedzy w panelu nawigacyjnym.
Agenci AI — agenci, do których przypisujesz źródła i grupy.
Dostęp do API — wygeneruj swój klucz API.
Uwierzytelnianie — wszystkie sposoby przekazywania klucza.

API bazy wiedzy #

Jak działa import #

Importowanie strony internetowej #

Importuj przesłany dokument #

Sprawdź źródło #

Usuwanie źródła #

Importowanie wielu stron jednocześnie #

Usuwanie wielu źródeł jednocześnie #

Odkrywanie stron w witrynie #

Szacowanie kosztów importu #

Zatrzymanie importu #

Wznawianie wstrzymanego importu #

Znajdowanie nowych stron w witrynie #

Odśwież każdą stronę w witrynie #

Śledź odświeżanie witryny #

Zatrzymaj odświeżanie witryny #

Odśwież pojedyncze źródło #

Wybierz najbardziej odpowiednie strony #

Grupy wiedzy #

Tworzenie grupy wiedzy #

Zmiana nazwy grupy wiedzy #

Usuwanie grupy wiedzy #

Dodaj FAQ do grupy #

Usuń FAQ z grupy #

Zastosuj grupę do Agenta #

Zastosuj grupę do kampanii #

Błędy API bazy wiedzy #

Powiązane #

API bazy wiedzy

Jak działa import

Importowanie strony internetowej

Importuj przesłany dokument

Sprawdź źródło

Usuwanie źródła

Importowanie wielu stron jednocześnie

Usuwanie wielu źródeł jednocześnie

Odkrywanie stron w witrynie

Szacowanie kosztów importu

Zatrzymanie importu

Wznawianie wstrzymanego importu

Znajdowanie nowych stron w witrynie

Odśwież każdą stronę w witrynie

Śledź odświeżanie witryny

Zatrzymaj odświeżanie witryny

Odśwież pojedyncze źródło

Wybierz najbardziej odpowiednie strony

Grupy wiedzy

Tworzenie grupy wiedzy

Zmiana nazwy grupy wiedzy

Usuwanie grupy wiedzy

Dodaj FAQ do grupy

Usuń FAQ z grupy

Zastosuj grupę do Agenta

Zastosuj grupę do kampanii

Błędy API bazy wiedzy

Powiązane