API Bază de cunoștințe

Baza ta de cunoștințe este sursa din care citește AI-ul. Aceasta are două părți, iar această pagină le acoperă pe ambele:

Surse de cunoștințe (/kb-sources) — paginile web și documentele încărcate pe care le introduci în platformă. Fiecare este citită, împărțită în secțiuni și transformată în întrebări frecvente (FAQ) din care AI-ul tău poate răspunde.
Grupuri de cunoștințe (/kb-groups) — pachete denumite de întrebări frecvente pe care le poți aplica unui Agent sau unei campanii printr-un singur apel, astfel încât un set de cunoștințe pe care l-ai organizat deja să poată fi refolosit pentru următorul Agent pe care îl creezi.

Întrebările frecvente generate de o sursă ajung în aceeași bibliotecă cu cele scrise manual, așa că, odată ce un import se finalizează, le poți citi, edita și conecta folosind API-ul pentru FAQ.

Toate endpoint-urile de mai jos sunt relative la URL-ul de bază https://api.youraiconnector.com/v1. Fiecare cerere trebuie să fie autentificată — consultă Acces API și Autentificare. Accesul la API este o funcționalitate cu plată; fără acesta, cererile sunt respinse cu un 403.

Importul consumă credite. Citirea unei pagini sau a unui document și scrierea întrebărilor frecvente din acestea consumă credite, proporțional cu volumul de conținut. Folosește Estimarea unui import înainte de a începe o scanare de mari dimensiuni.

Cum funcționează un import

Importul este un proces de fundal, nu ceva care se finalizează instantaneu. Fiecare endpoint de import răspunde imediat cu un source_id, iar tu trebuie să interoghezi acea sursă până când este finalizată:

Pornește importul — POST /kb-sources/url (o pagină), POST /kb-sources/file (un document încărcat) sau POST /kb-sources/bulk-import (până la 100 de pagini). Vei primi un ID de sursă și status: "queued".
Interoghează (Poll) — GET /kb-sources/{sourceId} până când status nu mai este queued sau processing.
Citește întrebările frecvente — când starea este ready, intrările produse se află în biblioteca ta de FAQ: GET /faqs.

Fiecare sursă raportează una dintre următoarele stări:

Status	Ce înseamnă
`queued`	Așteaptă să fie citită. Încă nu s-au perceput taxe.
`processing`	Este citită și transformată în întrebări frecvente chiar acum.
`ready`	Finalizat. Întrebările frecvente sunt în biblioteca ta.
`failed`	Nu a putut fi importată. `error_message` explică motivul.
`cancelled`	Oprită înainte de a fi citită (vezi Oprirea unui import).
`paused`	Oprită deoarece propria ta cheie AI a eșuat în timpul importului (vezi Reluarea unui import întrerupt).
`deleting`	O eliminare în masă este în curs de procesare.
`unknown`	Înregistrarea nu are nicio stare. Trateaz-o ca nefiind gata.

Atașează în timp ce imporți. Trimite autoLinkToAgentId pe orice endpoint de import și sursa — plus fiecare întrebare frecventă pe care o produce — va fi adăugată în baza de cunoștințe a acelui Agent în același apel, fără a fi nevoie de un pas suplimentar de conectare. autoLinkToCampaignId face același lucru pentru o campanie clasică. Conectarea se face în limita posibilităților: un ID care nu există sau care aparține altui cont este omis silențios, iar importul continuă, așa că verifică legătura citind din nou Agentul.

Importă o pagină web

POST /kb-sources/url

Adaugă o pagină web în baza ta de cunoștințe.

Câmpuri de solicitare

Câmp	Obligatoriu	Descriere
`url`	Da	Adresa `http` sau `https` completă a paginii.
`autoLinkToAgentId`	Nu	ID-ul unui Agent AI de care să atașați sursa importată.
`autoLinkToCampaignId`	Nu	Legacy. ID-ul unei campanii de care să atașați sursa importată.

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")

Răspuns — 202 Accepted

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

Interogați source_id cu Verifică o sursă până când starea este ready sau failed.

Dacă aceeași pagină se află deja în baza de cunoștințe, nu se adaugă nimic nou la coadă și primiți un 200 — iar dacă ați solicitat o legătură automată, sursa existentă este oricum legată pentru dvs.:

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

Un url lipsă, sau unul care nu este o adresă http/https validă, returnează 400.

Importă un document încărcat

POST /kb-sources/file

Adaugă un document care se află deja în stocarea de fișiere a contului dvs. ca sursă de cunoștințe. Tipuri acceptate: PDF, DOCX, TXT, MD, CSV și XLSX.

Acest endpoint nu transportă fișierul. Nu există încărcare multipart, nu există corp base64 și nu există descărcare de la un URL: trimiteți locația de stocare a unui fișier care există deja, iar acesta trebuie să se afle în propriul folder de încărcări (storage_path trebuie să înceapă cu users/{your user id}/uploads/), altfel cererea este refuzată cu 403. Tabloul de bord plasează fișierele acolo când le trageți în interior. Dacă nu aveți nicio modalitate de a plasa un fișier acolo, importați o pagină web cu Importă o pagină web în schimb.

Câmpuri de solicitare

Câmp	Obligatoriu	Descriere
`storage_path`	Da	Unde se află fișierul încărcat. Trebuie să înceapă cu `users/{your user id}/uploads/`.
`filename`	Da	Numele original al fișierului, inclusiv extensia acestuia — astfel este detectat tipul fișierului.
`mime_type`	Da	Tipul MIME al fișierului, de exemplu `application/pdf`.
`autoLinkToAgentId`	Nu	ID-ul unui Agent AI de care să atașați documentul.
`autoLinkToCampaignId`	Nu	Legacy. ID-ul unei campanii de care să atașați documentul.

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"
  }'

Răspuns — 202 Accepted

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

Stare	Când
`400`	Un câmp obligatoriu lipsește sau fișierul nu este de un tip pe care îl putem citi.
`403`	`storage_path` este în afara propriului folder de încărcări.

Verifică o sursă

GET /kb-sources/{sourceId}

Interogarea care urmează fiecărui import și reîmprospătare. Repetați-o până când starea este ready sau 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()

Răspuns

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

Câmp	Tip	Descriere
`status`	string	Unde se află sursa în fluxul de lucru (consultați tabelul de stare).
`faq_count`	integer	Câte întrebări frecvente (FAQ) au fost generate din această sursă până acum.
`section_count`	integer	În câte secțiuni de conținut a fost împărțită sursa.
`error_message`	string \| null	Motivul pentru care importul a eșuat, atunci când starea este `failed`. `null` în caz contrar.

Ștergerea unei surse

DELETE /kb-sources/{sourceId}

Elimină o sursă de cunoștințe. În mod implicit, întrebările frecvente produse de aceasta sunt păstrate — adăugați delete_faqs=true pentru a le elimina și pe acelea.

Parametri de interogare

Parametru	Obligatoriu	Descriere
`delete_faqs`	Nu	Setați la `true` pentru a șterge, de asemenea, fiecare întrebare frecventă produsă de această sursă. Valoarea implicită este `false`.

cURL

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

Răspuns

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

faqs_deleted este 0, cu excepția cazului în care ați solicitat delete_faqs=true.

Importarea mai multor pagini simultan

POST /kb-sources/bulk-import

Adaugă până la 100 de pagini web într-un singur apel — continuarea obișnuită a Descoperirii paginilor de pe un site web sau Găsirii paginilor noi de pe un site web. Paginile care se află deja în baza de cunoștințe sunt omise în loc să fie duplicate (și rămân conectate la Agent atunci când ați solicitat acest lucru).

Câmpuri de solicitare

Câmp	Obligatoriu	Descriere
`urls`	Da	Adrese de importat. Cel puțin 1, cel mult 100 per apel.
`autoLinkToAgentId`	Nu	ID-ul unui Agent AI de care să fie atașată fiecare pagină importată.
`autoLinkToCampaignId`	Nu	Depășit. ID-ul unei campanii de care să fie atașată fiecare pagină importată.

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"]

Răspuns — 202 Accepted

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

Interogați fiecare ID din queued_source_ids folosind Verificarea unei surse. Trimiterea unui tablou urls gol, a unei intrări care nu este de tip string sau a mai mult de 100 de intrări returnează 400.

Ștergerea mai multor surse simultan

POST /kb-sources/bulk-delete

Elimină până la 2.000 de surse de cunoștințe într-un singur apel. Eliminarea rulează în fundal și veți primi un e-mail când procesul este finalizat.

Ștergerea în masă elimină întotdeauna și întrebările frecvente (FAQ). Spre deosebire de Ștergerea unei surse, care le păstrează dacă nu solicitați altfel, acest endpoint șterge fiecare sursă împreună cu întrebările frecvente pe care le-a generat. Nu există nicio opțiune de a le păstra.

Câmpuri de solicitare

Câmp	Obligatoriu	Descriere
`sourceIds`	Da	ID-urile surselor de eliminat. Cel puțin 1, cel mult 2.000 per apel.
`domainLabel`	Nu	Un nume prietenos pentru această curățare. Folosit doar în e-mailul de finalizare.

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"
  }'

Răspuns — 202 Accepted

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

Descoperirea paginilor de pe un site web

POST /kb-sources/discover-pages

Explorează un site web pornind de la o adresă inițială și listează paginile găsite pe același domeniu, fiecare cu o opinie despre dacă merită importată. Nu se importă nimic și nu se selectează nimic pentru dumneavoastră — acesta este pasul „ce se află pe acest site” pe care îl rulați înainte de a decide ce să trimiteți către Importarea mai multor pagini simultan.

Câmpuri de solicitare

Câmp	Obligatoriu	Descriere
`url`	Da	Adresa de la care să începeți explorarea, de obicei pagina principală a site-ului.
`maxPages`	Nu	Limita superioară a numărului de pagini de returnat.

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 }'

Răspuns

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

Câmp	Tip	Descriere
`source_type`	string	Cum au fost găsite paginile — `sitemap` (sitemap-ul propriu al site-ului) sau `link_discovery` (prin urmărirea linkurilor).
`url`	string	Adresa completă a paginii.
`title`	string \| null	Titlul paginii, atunci când a putut fi citit.
`depth`	integer	Câte linkuri distanță de pagina de pornire a fost găsită această pagină.
`score`	integer	Cât de utilă pare pagina ca sursă de cunoștințe, de la `0` la `100`.
`recommendation`	string	`add` (clar merită importată, scor 90 sau mai mare), `maybe` (la limită) sau `skip` (conținut care ajută rar un asistent — jurnale de modificări, pagini legale, traduceri duplicate).
`reason_key`	string	Un motiv stabil, lizibil de către mașină, din spatele recomandării, de exemplu `core_page`, `changelog_history`, `legal_page` sau `locale_duplicate`.

Explorarea este realizată în limita posibilităților. Dacă site-ul nu poate fi citit, răspunsul este tot 200, cu success: false, o listă pages goală și un mesaj error. Verificați success înainte de a citi pages.

Un url lipsă returnează 400.

Estimarea costului unui import

POST /kb-sources/estimate-cost

Calculează câte credite ar consuma un import propus, înainte de a vă angaja la acesta. Paginile sunt preluate și documentele sunt citite pentru a le măsura dimensiunea, dar nu se importă nimic, iar estimarea în sine nu consumă credite.

Câmpuri de solicitare

Câmp	Obligatoriu	Descriere
`urls`	Nu	Adresele paginilor pe care luați în considerare să le importați.
`files`	Nu	Fișiere deja încărcate pe care le luați în considerare. Fiecare intrare are nevoie de `storage_path`, `filename` și `mime_type`.
`tier`	Nu	Nivelul de calitate AI pe care va rula importul, astfel încât estimarea să corespundă cu ceea ce veți fi taxat efectiv. Lăsați necompletat pentru tariful standard.

Trimiteți urls, files sau ambele.

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"] }'

Răspuns

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

Fiecare rând reflectă URL-ul sau calea de stocare din ref, astfel încât să îl puteți potrivi cu datele de intrare. O pagină sau un fișier care nu a putut fi citit primește totuși un rând, contorizat ca un fragment, cu un error atașat.

Oprirea unei importări

POST /kb-sources/cancel-import

Oprește paginile care sunt încă în așteptare în coada de import — butonul „oprire import” pentru o scanare care s-a dovedit a fi mai mare decât vă așteptați. Anularea unei pagini în așteptare nu costă nimic, deoarece aceasta nu a fost încă citită.

Paginile care sunt deja în curs de procesare nu sunt oprite: lucrul la ele este în desfășurare și este taxat oricum, așa că acestea se finalizează. Răspunsul raportează câte au fost acestea.

Câmpuri de solicitare

Câmp	Obligatoriu	Descriere
`host`	Nu	Oprește doar paginile în așteptare de pe acest site web (de exemplu `docs.example.com`). Lăsați necompletat pentru a opri toate importările în așteptare din cont.

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" }'

Răspuns

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

Reluarea unei importări întrerupte

POST /kb-sources/resume-import

Repornește o importare care a fost întreruptă deoarece propria cheie AI a încetat să mai funcționeze.

Apelarea acestei funcții reprezintă consimțământul dumneavoastră de a finaliza importarea folosind cheia activă în acel moment — ceea ce poate însemna consumarea creditelor platformei dacă propria cheie este încă indisponibilă.

Câmpuri de solicitare

Câmp	Obligatoriu	Descriere
`host`	Nu	Reluați doar paginile întrerupte de pe acest site web. Lăsați necompletat pentru a relua tot ce este întrerupt.

cURL

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

Răspuns

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

Găsirea paginilor noi pe un site web

POST /kb-sources/refresh-domain

Explorează un site web din care ați importat deja și raportează doar paginile care nu se află încă în baza dumneavoastră de cunoștințe, fiecare cu aceeași recomandare ca la descoperirea paginilor. Nu se importă nimic și nu se modifică nimic.

Cele două acțiuni ulterioare sunt apeluri separate în mod deliberat, așa că renunțarea la acesta nu costă nimic:

importă paginile noi pe care le dorești cu Importă mai multe pagini simultan;
recitește paginile pe care le ai deja cu Reîmprospătează fiecare pagină de pe un site web.

Câmpuri de solicitare

Câmp	Obligatoriu	Descriere
`baseUrl`	Da	Orice adresă de pe site-ul web sau doar gazda.
`maxPages`	Nu	Limita superioară a numărului de pagini de explorat.

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" }'

Răspuns

{
  "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
}

Câmp	Tip	Descriere
`discovered`	întreg	Câte pagini au fost găsite în total pe site.
`new_pages`	matrice	Pagini care nu sunt încă în baza ta de cunoștințe. Nu este nimic pus în coadă pentru tine — importă-le pe cele pe care le dorești.
`new_urls_queued`	întreg	Întotdeauna `0`. Păstrat pentru compatibilitate cu versiunile anterioare; acest endpoint nu pune niciodată nimic în coadă.
`existing_refresh_queued`	întreg	Câte pagini pe care le-ai importat deja de pe acest site au fost găsite gata pentru a fi recitite. Nimic nu este pus în coadă prin acest apel.
`batch_id`	șir	Prezent doar atunci când a fost creat un lot.

La fel ca descoperirea, aceasta eșuează ușor: un site care nu poate fi citit returnează totuși 200, cu success: false, un new_pages gol și un error. Un baseUrl lipsă sau gol returnează 400.

Reîmprospătează fiecare pagină de pe un site web

POST /kb-sources/trigger-domain-refresh

Recitește fiecare pagină pe care ai importat-o deja de pe un site web, astfel încât întrebările frecvente (FAQ) să urmeze conținutul actual al site-ului: secțiunile modificate sunt actualizate, cele noi sunt adăugate, iar secțiunile eliminate sunt șterse.

Aceasta pune lucrul în coadă și returnează imediat. Urmează cu Urmărește reîmprospătarea unui site web și oprește-o cu Oprește reîmprospătarea unui site web.

Câmpuri de solicitare

Câmp	Obligatoriu	Descriere
`baseUrl`	Da	Orice adresă de pe site-ul web sau doar gazda.

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" }'

Răspuns

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

Urmărește reîmprospătarea unui site web

GET /kb-sources/domain-refresh-status

Cât de avansată este reîmprospătarea unui site web, astfel încât să poți afișa progresul precum „221 din 249”.

Parametri de interogare

Parametru	Obligatoriu	Descriere
`baseUrl`	Da	Orice adresă de pe site-ul web sau doar gazda.

cURL

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

Răspuns

{
  "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 este null atunci când nu rulează nicio reîmprospătare pentru acel site web. Paginile finalizate până acum reprezintă total minus pending. Starea status a sarcinii este una dintre refreshing (încă se lucrează la pagini), deduplicating (pasul de curățare de la final) sau stările finale completed, failed și cancelled. Păstrează domainBatchId — este ceea ce transmiți endpoint-ului de anulare.

Un baseUrl lipsă sau gol returnează 400.

Oprirea reîmprospătării unui site web

POST /kb-sources/refresh-domain/cancel

Oprește reîmprospătarea unui site web care încă procesează pagini. Paginile deja finalizate își păstrează conținutul actualizat; paginile care nu au fost începute sunt eliminate, iar paginile care erau în curs de recitire revin la starea lor anterioară.

Câmpuri de solicitare

Câmp	Obligatoriu	Descriere
`jobId`	Da	`domainBatchId` returnat de Urmărirea reîmprospătării unui site web.

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" }'

Răspuns

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

Câmp	Tip	Descriere
`status`	string	Starea reîmprospătării după acest apel: `cancelled`, `deduplicating`, `completed` sau `failed`.
`cancelled_units`	integer	Cât de multă muncă a rămas de efectuat în momentul anulării. `0` la o anulare repetată.
`sources_reset`	integer	Pagini scoase din procesare și returnate la `ready`.
`sources_cancelled`	integer	Pagini noi din această reîmprospătare care erau încă în coadă și sunt acum anulate.

Anularea de două ori este inofensivă — al doilea apel raportează aceeași stare finală. Odată ce reîmprospătarea a trecut la etapa de curățare, aceasta nu mai poate fi oprită, iar răspunsul revine cu success: false și reason: "already_finalizing". Un jobId lipsă returnează 400, iar o sarcină care nu se află în contul dumneavoastră returnează 404.

Reîmprospătarea unei singure surse

POST /kb-sources/{sourceId}/refresh

Recitește o pagină web pe care ați importat-o deja și aliniază secțiunile Întrebări frecvente (FAQ) cu conținutul actual al paginii: secțiunile modificate sunt actualizate, cele noi sunt adăugate, iar cele eliminate sunt șterse.

cURL

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

Răspuns — 202 Accepted

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

Interogați sursa până când starea acesteia nu mai este queued și processing. Un ID de sursă care nu se află în contul dumneavoastră returnează 404.

Alegerea celor mai relevante pagini

POST /kb-sources/select-relevant-pages

Solicită AI-ului să aleagă cele cinci pagini, dintr-o listă de candidați, care descriu cel mai bine o afacere — utilizat la generarea unui plan de campanie de pe un site web. Această acțiune consumă credite.

Câmpuri de solicitare

Câmp	Obligatoriu	Descriere
`urls`	Da	Adresele paginilor candidate din care se poate alege, de obicei provenite din descoperirea paginilor.
`homeUrl`	Da	Pagina principală a site-ului, utilizată ca context pentru alegere.

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"]
  }'

Răspuns

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

Acesta este un asistent, nu o resursă: în caz de eșec, acesta răspunde totuși cu 200, cu success: false, o listă pages goală și un mesaj error.

Grupuri de cunoștințe

Un grup de cunoștințe este un set denumit de întrebări frecvente (FAQ) — „Livrare și retur”, „Onboarding” — pe care îl puteți aplica unui Agent sau unei campanii printr-un singur apel. Grupul conține referințe, nu copii: întrebările frecvente rămân în biblioteca dvs. unică, deci editarea uneia prin API-ul FAQ o actualizează peste tot unde este utilizată.

Aplicarea unui grup doar adaugă ceea ce lipsește, deci aplicarea aceluiași grup de două ori este inofensivă, iar added_count revine ca 0 a doua oară.

Crearea unui grup de cunoștințe

POST /kb-groups

Creează un grup. Acesta începe gol — adăugați întrebări frecvente în el folosind Adăugarea unei întrebări frecvente la un grup.

Câmpuri de solicitare

Câmp	Obligatoriu	Descriere
`name`	Da	Numele grupului.

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"]

Răspuns — 201 Created

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

Redenumirea unui grup de cunoștințe

PUT /kb-groups/{groupId}

Schimbă numele unui grup. Întrebările sale frecvente rămân intacte.

Câmpuri de solicitare

Câmp	Obligatoriu	Descriere
`name`	Da	Numele nou al grupului.

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" }'

Răspuns

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

Ștergerea unui grup de cunoștințe

DELETE /kb-groups/{groupId}

Șterge grupul. Doar setul este eliminat — întrebările frecvente din acesta rămân în biblioteca dvs., iar tot ceea ce avea deja grupul aplicat păstrează acele întrebări frecvente.

cURL

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

Răspuns

{
  "success": true
}

Adăugarea unei întrebări frecvente (FAQ) într-un grup

POST /kb-groups/{groupId}/faqs

Plasează o întrebare frecventă existentă într-un grup. Aceasta modifică doar pachetul — nu atașează întrebarea frecventă niciunui Agent în mod individual; aplicați grupul pentru acest lucru.

Câmpuri de solicitare

Câmp	Obligatoriu	Descriere
`faq_id`	Da	ID-ul întrebării frecvente de adăugat.

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" }'

Răspuns

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

Eliminarea unei întrebări frecvente dintr-un grup

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

Scoate o întrebare frecventă dintr-un grup. Întrebarea frecventă în sine nu este ștearsă, iar Agenții cărora li s-a aplicat deja grupul o vor păstra.

cURL

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

Răspuns

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

Aplicarea unui grup unui Agent

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

Adaugă fiecare întrebare frecventă din grup la baza de cunoștințe a unui Agent AI printr-un singur apel — este modalitatea rapidă de a oferi unui Agent nou un set de cunoștințe pe care l-ați curatoriat deja.

Câmpuri de solicitare

Câmp	Obligatoriu	Descriere
`agent_id`	Da	ID-ul Agentului AI căruia i se aplică grupul.

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"]

Răspuns

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

added_count reprezintă numărul de întrebări frecvente adăugate efectiv — 0 atunci când grupul este gol sau deja aplicat.

Aplicarea unui grup unei campanii

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

Versiunea pentru campanii clasice a apelului de mai sus. Într-un cont bazat pe Agenți, utilizați în schimb Aplicarea unui grup unui Agent.

Câmpuri de solicitare

Câmp	Obligatoriu	Descriere
`campaign_id`	Da	ID-ul campaniei căreia i se aplică grupul.

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" }'

Răspuns

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

Erori API Bază de cunoștințe

Aceste endpoint-uri returnează plicul de eroare standard:

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

Status	Când apare pe un endpoint al bazei de cunoștințe
`400`	Un câmp obligatoriu lipsește sau este invalid — un `url` gol, un `baseUrl` sau `jobId` lipsă, mai mult de 100 de URL-uri într-un import în masă, mai mult de 2.000 de ID-uri într-o ștergere în masă sau un tip de fișier pe care nu îl putem citi.
`402`	Nu există suficiente credite pentru a rula importul. Reîncărcați contul și încercați din nou.
`403`	Un `storage_path` în afara propriului folder de încărcări — sau planul dvs. nu include acces API.
`404`	Sursa, grupul, FAQ, Agentul, campania sau sarcina de reîmprospătare nu au fost găsite — fie nu există, fie aparțin altui cont.

Eșecurile minore nu sunt erori. Descoperirea (discover-pages, refresh-domain) și asistentul de selectare a paginilor răspund cu 200, success: false și un mesaj error atunci când site-ul web nu poate fi citit, în loc să eșueze cererea. Verificați întotdeauna success înainte de a citi datele.

Codurile partajate pe care orice endpoint le poate returna — 401, 403 (planul dvs. nu include acces API), 429 (limită de rată) și 500 — sunt listate cu îndrumări pentru reîncercare în Erori și Paginare.

Legate

API FAQ — citiți, editați și conectați întrebările frecvente (FAQ) generate de sursele dvs.
Gestionarea FAQ — aceeași bază de cunoștințe în tabloul de bord.
Agenți AI — Agenții cărora le atașați surse și grupuri.
Acces API — generați cheia API.
Autentificare — toate modalitățile de a transmite cheia dvs.

API Bază de cunoștințe #

Cum funcționează un import #

Importă o pagină web #

Importă un document încărcat #

Verifică o sursă #

Ștergerea unei surse #

Importarea mai multor pagini simultan #

Ștergerea mai multor surse simultan #

Descoperirea paginilor de pe un site web #

Estimarea costului unui import #

Oprirea unei importări #

Reluarea unei importări întrerupte #

Găsirea paginilor noi pe un site web #

Reîmprospătează fiecare pagină de pe un site web #

Urmărește reîmprospătarea unui site web #

Oprirea reîmprospătării unui site web #

Reîmprospătarea unei singure surse #

Alegerea celor mai relevante pagini #

Grupuri de cunoștințe #

Crearea unui grup de cunoștințe #

Redenumirea unui grup de cunoștințe #

Ștergerea unui grup de cunoștințe #

Adăugarea unei întrebări frecvente (FAQ) într-un grup #

Eliminarea unei întrebări frecvente dintr-un grup #

Aplicarea unui grup unui Agent #

Aplicarea unui grup unei campanii #

Erori API Bază de cunoștințe #

Legate #

API Bază de cunoștințe

Cum funcționează un import

Importă o pagină web

Importă un document încărcat

Verifică o sursă

Ștergerea unei surse

Importarea mai multor pagini simultan

Ștergerea mai multor surse simultan

Descoperirea paginilor de pe un site web

Estimarea costului unui import

Oprirea unei importări

Reluarea unei importări întrerupte

Găsirea paginilor noi pe un site web

Reîmprospătează fiecare pagină de pe un site web

Urmărește reîmprospătarea unui site web

Oprirea reîmprospătării unui site web

Reîmprospătarea unei singure surse

Alegerea celor mai relevante pagini

Grupuri de cunoștințe

Crearea unui grup de cunoștințe

Redenumirea unui grup de cunoștințe

Ștergerea unui grup de cunoștințe

Adăugarea unei întrebări frecvente (FAQ) într-un grup

Eliminarea unei întrebări frecvente dintr-un grup

Aplicarea unui grup unui Agent

Aplicarea unui grup unei campanii

Erori API Bază de cunoștințe

Legate