# 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](faqs.md).

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](../integrations/api-access.md) și [Autentificare](authentication.md). 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](#estimate-what-an-import-will-cost) î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ă:

1. **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"`.
2. **Interoghează (Poll)** — `GET /kb-sources/{sourceId}` până când `status` nu mai este `queued` sau `processing`.
3. **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](#stop-an-import)). |
| `paused` | Oprită deoarece propria ta cheie AI a eșuat în timpul importului (vezi [Reluarea unui import întrerupt](#resume-a-paused-import)). |
| `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**

```bash
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**

```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**

```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`

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

Interogați `source_id` cu [Verifică o sursă](#check-a-source) 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.:

```json
{
  "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](#import-a-web-page) î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**

```bash
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`

```json
{
  "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**

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

**JavaScript**

```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**

```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**

```json
{
  "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](#how-an-import-works)). |
| `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**

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

**Răspuns**

```json
{
  "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](#discover-pages-on-a-website) sau [Găsirii paginilor noi de pe un site web](#find-new-pages-on-a-website). 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**

```bash
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**

```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**

```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`

```json
{
  "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](#check-a-source). 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](#delete-a-source), 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**

```bash
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`

```json
{
  "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](#import-many-pages-at-once).

**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**

```bash
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**

```json
{
  "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**

```bash
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**

```json
{
  "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**

```bash
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**

```json
{
  "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**

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

**Răspuns**

```json
{
  "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](#import-many-pages-at-once);
- recitește paginile pe care le ai deja cu [Reîmprospătează fiecare pagină de pe un site web](#refresh-every-page-on-a-website).

**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**

```bash
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**

```json
{
  "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](#track-a-website-refresh) și oprește-o cu [Oprește reîmprospătarea unui site web](#stop-a-website-refresh).

**Câmpuri de solicitare**

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

**cURL**

```bash
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**

```json
{
  "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**

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

**Răspuns**

```json
{
  "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](#track-a-website-refresh). |

**cURL**

```bash
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**

```json
{
  "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**

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

**Răspuns** — `202 Accepted`

```json
{
  "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**

```bash
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**

```json
{
  "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](faqs.md) 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](#add-a-faq-to-a-group).

**Câmpuri de solicitare**

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

**cURL**

```bash
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**

```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**

```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`

```json
{
  "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**

```bash
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**

```json
{
  "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**

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

**Răspuns**

```json
{
  "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**

```bash
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**

```json
{
  "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**

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

**Răspuns**

```json
{
  "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**

```bash
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**

```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**

```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**

```json
{
  "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](#apply-a-group-to-an-agent).

**Câmpuri de solicitare**

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

**cURL**

```bash
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**

```json
{
  "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:

```json
{
  "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](errors-and-pagination.md).

---

## Legate

- [API FAQ](faqs.md) — citiți, editați și conectați întrebările frecvente (FAQ) generate de sursele dvs.
- [Gestionarea FAQ](../ai-automation/faq-management.md) — aceeași bază de cunoștințe în tabloul de bord.
- [Agenți AI](../ai-agents/ai-agents.md) — Agenții cărora le atașați surse și grupuri.
- [Acces API](../integrations/api-access.md) — generați cheia API.
- [Autentificare](authentication.md) — toate modalitățile de a transmite cheia dvs.