# API בסיס ידע

בסיס הידע שלך הוא המקור שממנו ה-AI קורא. הוא מורכב משני חלקים, ודף זה מכסה את שניהם:

- **מקורות ידע** (`/kb-sources`) — דפי אינטרנט ומסמכים שהועלו שאתה מזין לפלטפורמה. כל אחד מהם נקרא, מחולק למקטעים, ומומר לשאלות נפוצות (FAQs) שה-AI שלך יכול להשיב מהן.
- **קבוצות ידע** (`/kb-groups`) — צרורות בעלי שם של שאלות נפוצות שניתן להחיל על סוכן (Agent) או קמפיין בקריאה אחת, כך שניתן לעשות שימוש חוזר במאגר ידע שכבר אצרת עבור הסוכן הבא שתצור.

השאלות הנפוצות שמקור מייצר מגיעות לאותה ספרייה שבה נמצאות השאלות שכתבת ידנית, כך שברגע שייבוא מסתיים, תוכל לקרוא, לערוך ולקשר אותן באמצעות ה-[FAQs API](faqs.md).

כל נקודות הקצה להלן יחסיות לכתובת ה-URL הבסיסית `https://api.youraiconnector.com/v1`. כל בקשה חייבת לעבור אימות — ראה [גישה ל-API](../integrations/api-access.md) ו-[אימות](authentication.md). גישה ל-API היא תכונה בתשלום; ללא גישה זו, בקשות יידחו עם `403`.


> **ייבוא צורך קרדיטים.** קריאת דף או מסמך וכתיבת שאלות נפוצות מתוכו צורכת קרדיטים, בערך ביחס לכמות התוכן שיש בו. השתמש ב-[הערכת ייבוא](#estimate-what-an-import-will-cost) לפני שאתה מתחייב לסריקה גדולה.

---

## כיצד פועל ייבוא

ייבוא הוא תהליך רקע, לא משהו שמסתיים בזמן שאתה ממתין. כל נקודת קצה של ייבוא משיבה מיד עם `source_id`, ואתה מבצע תשאול (poll) של אותו מקור עד שהוא מסתיים:

1. **התחלת הייבוא** — `POST /kb-sources/url` (דף אחד), `POST /kb-sources/file` (מסמך שהועלה), או `POST /kb-sources/bulk-import` (עד 100 דפים). אתה מקבל בחזרה מזהה מקור ו-`status: "queued"`.
2. **תשאול (Poll)** — `GET /kb-sources/{sourceId}` עד ש-`status` אינו עוד `queued` או `processing`.
3. **קריאת השאלות הנפוצות** — כאשר הסטטוס הוא `ready`, הערכים שהוא הפיק נמצאים בספריית השאלות הנפוצות שלך: `GET /faqs`.

כל מקור מדווח על אחד מהסטטוסים הבאים:

| סטטוס | מה זה אומר |
|---|---|
| `queued` | ממתין לקריאה. טרם חויבת על כך. |
| `processing` | נקרא ומומר לשאלות נפוצות ברגעים אלו. |
| `ready` | הסתיים. השאלות הנפוצות שלו נמצאות בספרייה שלך. |
| `failed` | לא ניתן היה לייבא. `error_message` מסביר מדוע. |
| `cancelled` | נעצר לפני שנקרא (ראה [עצירת ייבוא](#stop-an-import)). |
| `paused` | נעצר מכיוון שמפתח ה-AI שלך נכשל באמצע הייבוא (ראה [המשך ייבוא מושהה](#resume-a-paused-import)). |
| `deleting` | מחיקה מרוכזת פועלת עליו כעת. |
| `unknown` | לרשומה אין סטטוס. התייחס אליה כאל לא מוכנה. |

> **צירוף בזמן הייבוא.** העבר `autoLinkToAgentId` בכל נקודת קצה של ייבוא, והמקור — בתוספת כל שאלה נפוצה שהוא מייצר — יתווסף לידע של אותו סוכן באותה קריאה, ללא צעד קישור נוסף. `autoLinkToCampaignId` עושה את אותו הדבר עבור קמפיין קלאסי. הקישור נעשה במיטב המאמץ: מזהה שלא קיים, או ששייך לחשבון אחר, ידלג בשקט והייבוא עדיין ירוץ, לכן אשר את הקישור על ידי קריאה חוזרת של הסוכן.

---

## ייבוא דף אינטרנט

`POST /kb-sources/url`

מוסיף דף אינטרנט אחד לבסיס הידע שלך.

**שדות הבקשה**

| שדה | חובה | תיאור |
|---|---|---|
| `url` | כן | כתובת `http` או `https` מלאה של הדף. |
| `autoLinkToAgentId` | לא | מזהה של סוכן AI שאליו יש לצרף את המקור המיובא. |
| `autoLinkToCampaignId` | לא | מיושן. מזהה של קמפיין שאליו יש לצרף את המקור המיובא. |

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

**תגובה** — `202 Accepted`

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

בצע סקר (poll) ל-`source_id` באמצעות [בדיקת מקור](#check-a-source) עד שהסטטוס יהיה `ready` או `failed`.

אם אותו דף כבר נמצא בבסיס הידע שלך, שום דבר חדש לא יתווסף לתור ותקבל `200` במקום זאת — ואם ביקשת קישור אוטומטי, המקור הקיים יקושר עבורך בכל מקרה:

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

`url` חסר, או כזה שאינו כתובת `http`/`https` תקינה, יחזיר `400`.

---

## ייבוא מסמך שהועלה

`POST /kb-sources/file`

מוסיף מסמך שכבר נמצא ב**אחסון הקבצים של החשבון שלך** כמקור ידע. סוגים נתמכים: PDF, DOCX, TXT, MD, CSV ו-XLSX.

> **נקודת קצה זו אינה נושאת את הקובץ.** אין העלאת multipart, אין גוף base64 ואין הורדה מ-URL: אתה שולח את מיקום האחסון של קובץ שכבר קיים, והוא חייב להימצא תחת תיקיית ההעלאות שלך (`storage_path` חייב להתחיל ב-`users/{your user id}/uploads/`), אחרת הבקשה תידחה עם `403`. לוח הבקרה מציב שם קבצים כאשר אתה גורר אותם פנימה. אם אין לך דרך להציב שם קובץ, ייבא דף אינטרנט באמצעות [ייבוא דף אינטרנט](#import-a-web-page) במקום זאת.

**שדות הבקשה**

| שדה | חובה | תיאור |
|---|---|---|
| `storage_path` | כן | היכן שהקובץ שהועלה נמצא. חייב להתחיל ב-`users/{your user id}/uploads/`. |
| `filename` | כן | שם הקובץ המקורי כולל הסיומת שלו — כך מזוהה סוג הקובץ. |
| `mime_type` | כן | סוג MIME של הקובץ, לדוגמה `application/pdf`. |
| `autoLinkToAgentId` | לא | מזהה של סוכן AI שאליו יש לצרף את המסמך. |
| `autoLinkToCampaignId` | לא | מיושן. מזהה של קמפיין שאליו יש לצרף את המסמך. |

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

**תגובה** — `202 Accepted`

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

| סטטוס | מתי |
|---|---|
| `400` | שדה חובה חסר, או שהקובץ אינו מסוג שאנו יכולים לקרוא. |
| `403` | `storage_path` נמצא מחוץ לתיקיית ההעלאות שלך. |

---

## בדיקת מקור

`GET /kb-sources/{sourceId}`

הסקר (poll) שמתבצע לאחר כל ייבוא ורענון. חזור עליו עד שהסטטוס יהיה `ready` או `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()
```

**תגובה**

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

| שדה | סוג | תיאור |
|---|---|---|
| `status` | string | מיקום המקור בצינור העיבוד (ראו את [טבלת הסטטוס](#how-an-import-works)). |
| `faq_count` | integer | כמה שאלות נפוצות נוצרו ממקור זה עד כה. |
| `section_count` | integer | לכמה מקטעי תוכן פוצל המקור. |
| `error_message` | string \| null | הסיבה לכשל בייבוא, כאשר הסטטוס הוא `failed`. `null` אחרת. |

---

## מחיקת מקור

`DELETE /kb-sources/{sourceId}`

מסיר מקור ידע אחד. **כברירת מחדל, השאלות הנפוצות שהופקו ממנו נשמרות** — הוסיפו את `delete_faqs=true` כדי להסיר גם אותן.

**פרמטרים של שאילתה**

| פרמטר | נדרש | תיאור |
|---|---|---|
| `delete_faqs` | לא | הגדירו כ-`true` כדי למחוק גם את כל השאלות הנפוצות שמקור זה הפיק. ברירת המחדל היא `false`. |

**cURL**

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

**תגובה**

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

`faqs_deleted` הוא `0` אלא אם ביקשתם `delete_faqs=true`.

---

## ייבוא דפים רבים בבת אחת

`POST /kb-sources/bulk-import`

מוסיף עד 100 דפי אינטרנט בקריאה אחת — ההמשך הרגיל ל-[גילוי דפים באתר](#discover-pages-on-a-website) או [מציאת דפים חדשים באתר](#find-new-pages-on-a-website). דפים שכבר נמצאים בבסיס הידע שלכם ידולגו במקום להשתכפל (ועדיין יקושר לסוכן כאשר ביקשתם זאת).

**שדות הבקשה**

| שדה | נדרש | תיאור |
|---|---|---|
| `urls` | כן | כתובות לייבוא. לפחות 1, לכל היותר 100 בכל קריאה. |
| `autoLinkToAgentId` | לא | מזהה של סוכן בינה מלאכותית לצירוף כל דף מיובא. |
| `autoLinkToCampaignId` | לא | מיושן. מזהה של קמפיין לצירוף כל דף מיובא. |

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

**תגובה** — `202 Accepted`

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

בצעו סקר (poll) לכל מזהה ב-`queued_source_ids` באמצעות [בדיקת מקור](#check-a-source). שליחת מערך `urls` ריק, ערך שאינו מחרוזת, או יותר מ-100 ערכים תחזיר `400`.

---

## מחיקת מקורות רבים בבת אחת

`POST /kb-sources/bulk-delete`

מסיר עד 2,000 מקורות ידע בקריאה אחת. ההסרה מתבצעת ברקע ותקבלו אימייל בסיומה.

> **מחיקה מרוכזת מסירה תמיד גם את השאלות הנפוצות.** בניגוד ל-[מחיקת מקור](#delete-a-source), ששומרת אותן אלא אם תבקש אחרת, נקודת קצה זו מוחקת כל מקור יחד עם השאלות הנפוצות שהוא הפיק. אין אפשרות לשמור אותן.

**שדות הבקשה**

| שדה | נדרש | תיאור |
|---|---|---|
| `sourceIds` | כן | מזהי המקורות להסרה. לפחות 1, לכל היותר 2,000 לכל קריאה. |
| `domainLabel` | לא | שם ידידותי עבור פעולת ניקוי זו. משמש רק בהודעת האימייל על השלמת הפעולה. |

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

**תגובה** — `202 Accepted`

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

---

## גילוי דפים באתר אינטרנט

`POST /kb-sources/discover-pages`

סורק אתר אינטרנט מכתובת התחלה אחת ומפרט את הדפים שנמצאו באותו דומיין, כאשר לכל אחד מהם מצורפת חוות דעת האם כדאי לייבא אותו. **שום דבר לא מיובא ושום דבר לא נבחר עבורך** — זהו שלב ה-"מה יש באתר הזה" שאתה מריץ לפני ההחלטה מה לשלוח ל-[ייבוא דפים רבים בבת אחת](#import-many-pages-at-once).

**שדות הבקשה**

| שדה | נדרש | תיאור |
|---|---|---|
| `url` | כן | כתובת להתחלת הסריקה, בדרך כלל דף הבית של האתר. |
| `maxPages` | לא | גבול עליון למספר הדפים להחזרה. |

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

**תגובה**

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

| שדה | סוג | תיאור |
|---|---|---|
| `source_type` | string | כיצד נמצאו הדפים — `sitemap` (מפת האתר של האתר עצמו) או `link_discovery` (על ידי מעקב אחר קישורים). |
| `url` | string | כתובת מלאה של הדף. |
| `title` | string \| null | כותרת הדף, כאשר ניתן היה לקרוא אותה. |
| `depth` | integer | כמה קישורים רחוק מדף ההתחלה נמצא דף זה. |
| `score` | integer | עד כמה הדף נראה שימושי כידע, מ-`0` עד `100`. |
| `recommendation` | string | `add` (בהחלט שווה ייבוא, ציון 90 ומעלה), `maybe` (גבולי), או `skip` (תוכן שלעיתים רחוקות עוזר לעוזר אישי — יומני שינויים, דפים משפטיים, תרגומים כפולים). |
| `reason_key` | string | סיבה יציבה וקריאה למכונה מאחורי ההמלצה, לדוגמה `core_page`, `changelog_history`, `legal_page` או `locale_duplicate`. |

> **הסריקה היא לפי המאמץ המיטבי.** אם לא ניתן לקרוא את האתר, התגובה היא עדיין `200`, עם `success: false`, רשימת `pages` ריקה והודעת `error`. בדוק את `success` לפני קריאת `pages`.

ערך `url` חסר מחזיר `400`.

---

## הערכת עלות הייבוא

`POST /kb-sources/estimate-cost`

מחשב כמה קרדיטים יצרוך ייבוא מוצע, לפני שאתה מתחייב אליו. דפים נמשכים ומסמכים נקראים כדי למדוד את גודלם, אך שום דבר לא מיובא וההערכה עצמה אינה צורכת קרדיטים.

**שדות הבקשה**

| שדה | נדרש | תיאור |
|---|---|---|
| `urls` | לא | כתובות דפים שאתה שוקל לייבא. |
| `files` | לא | קבצים שכבר הועלו שאתה שוקל. כל רשומה צריכה `storage_path`, `filename` ו-`mime_type`. |
| `tier` | לא | רמת האיכות של ה-AI שבה יתבצע הייבוא, כך שההערכה תתאים למה שתחויב בו בפועל. השאר ריק עבור התעריף הסטנדרטי. |

שלח `urls`, `files`, או את שניהם.

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

**תגובה**

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

כל שורה מהדהדת חזרה את ה-URL או את נתיב האחסון ב-`ref` כך שתוכל להתאים אותו לקלט שלך. דף או קובץ שלא ניתן היה לקרוא עדיין מקבלים שורה, הנספרת כנתח אחד, עם `error` עליה.

---

## עצירת ייבוא

`POST /kb-sources/cancel-import`

עוצר דפים שעדיין ממתינים בתור הייבוא — כפתור "עצירת ייבוא" עבור סריקה שהתבררה כגדולה ממה שציפית. ביטול דף ממתין אינו עולה דבר, מכיוון שהוא טרם נקרא.

דפים שכבר נמצאים בתהליך עיבוד **אינם** נעצרים: העבודה עליהם בעיצומה והם מחויבים בכל מקרה, לכן הם מסתיימים. התגובה מדווחת כמה כאלה היו.

**שדות הבקשה**

| שדה | נדרש | תיאור |
|---|---|---|
| `host` | לא | עצור רק דפים ממתינים באתר זה (לדוגמה `docs.example.com`). השאר ריק כדי לעצור כל ייבוא ממתין בחשבון. |

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

**תגובה**

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

---

## המשך ייבוא מושהה

`POST /kb-sources/resume-import`

מפעיל מחדש ייבוא שהושהה מכיוון שמפתח ה-AI שלך הפסיק לעבוד.

> קריאה לזה **מהווה** את הסכמתך לסיים את הייבוא באמצעות המפתח הפעיל כעת — מה שעשוי להיות כרוך בניצול קרדיטים של הפלטפורמה אם המפתח שלך עדיין מושבת.

**שדות הבקשה**

| שדה | נדרש | תיאור |
|---|---|---|
| `host` | לא | המשך רק דפים מושהים באתר זה. השאר ריק כדי להמשיך את כל מה שמושהה. |

**cURL**

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

**תגובה**

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

---

## מציאת דפים חדשים באתר

`POST /kb-sources/refresh-domain`

סורק אתר שכבר ייבאת ממנו ומדווח רק על הדפים ש**אינם** נמצאים עדיין בבסיס הידע שלך, כל אחד עם אותה המלצה כמו גילוי דפים. דבר אינו מיובא ושום דבר אינו משתנה.

שתי פעולות ההמשך הן קריאות נפרדות במכוון, כך שוויתור על זו אינו עולה דבר:

- ייבא את הדפים החדשים שברצונך להוסיף באמצעות [ייבוא דפים רבים בבת אחת](#import-many-pages-at-once);
- קרא מחדש את הדפים שכבר יש לך באמצעות [רענון כל דף באתר](#refresh-every-page-on-a-website).

**שדות הבקשה**

| שדה | חובה | תיאור |
|---|---|---|
| `baseUrl` | כן | כל כתובת באתר, או רק שם המארח (host). |
| `maxPages` | לא | גבול עליון למספר הדפים שיש לסרוק. |

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

**תגובה**

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

| שדה | סוג | תיאור |
|---|---|---|
| `discovered` | integer | כמה דפים נמצאו באתר בסך הכל. |
| `new_pages` | array | דפים שעדיין לא נמצאים בבסיס הידע שלך. שום דבר לא מתווסף לתור עבורך — ייבא את הדפים שברצונך להוסיף. |
| `new_urls_queued` | integer | תמיד `0`. נשמר לצורך תאימות לאחור; נקודת קצה זו לעולם לא מוסיפה דבר לתור. |
| `existing_refresh_queued` | integer | כמה דפים שכבר ייבאת מהאתר הזה נמצאו מוכנים לקריאה מחדש. שום דבר לא מתווסף לתור על ידי קריאה זו. |
| `batch_id` | string | מופיע רק כאשר נוצרה אצווה. |

בדומה לגילוי, פעולה זו נכשלת בצורה רכה: אתר שלא ניתן לקרוא עדיין מחזיר `200`, עם `success: false`, `new_pages` ריק ו-`error`. `baseUrl` חסר או ריק מחזיר `400`.

---

## רענון כל דף באתר

`POST /kb-sources/trigger-domain-refresh`

קורא מחדש כל דף שכבר ייבאת מאתר אינטרנט, כך שהשאלות הנפוצות (FAQs) שלו יתאימו לתוכן העדכני של האתר: מקטעים ששונו מתעדכנים, מקטעים חדשים מתווספים ומקטעים שהוסרו נמחקים.

פעולה זו מוסיפה עבודה לתור ומחזירה תשובה באופן מיידי. המשך ב-[מעקב אחר רענון אתר](#track-a-website-refresh), ועצור אותו באמצעות [עצירת רענון אתר](#stop-a-website-refresh).

**שדות הבקשה**

| שדה | חובה | תיאור |
|---|---|---|
| `baseUrl` | כן | כל כתובת באתר, או רק שם המארח (host). |

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

**תגובה**

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

---

## מעקב אחר רענון אתר

`GET /kb-sources/domain-refresh-status`

באיזה שלב נמצא רענון האתר, כדי שתוכל להציג התקדמות כמו "221 מתוך 249".

**פרמטרים של שאילתה**

| פרמטר | חובה | תיאור |
|---|---|---|
| `baseUrl` | כן | כל כתובת באתר, או רק שם המארח (host). |

**cURL**

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

**תגובה**

```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` הוא `null` כאשר לא מתבצע רענון עבור אותו אתר. מספר הדפים שהושלמו עד כה הוא `total` פחות `pending`. המשימה `status` היא אחת מ-`refreshing` (עדיין מעבד דפים), `deduplicating` (שלב הניקוי בסיום), או המצבים הסופיים `completed`, `failed` ו-`cancelled`. שמור את `domainBatchId` — זה מה שאתה מעביר לנקודת הקצה של הביטול.

`baseUrl` חסר או ריק מחזיר `400`.

---

## עצירת רענון אתר

`POST /kb-sources/refresh-domain/cancel`

עוצר רענון אתר שעדיין מעבד את דפיו. דפים שכבר סיימו את התהליך שומרים על התוכן המעודכן שלהם; דפים שטרם החלו מוסרים, ודפים שהיו בתהליך קריאה חוזרת חוזרים למצבם הקודם.

**שדות הבקשה**

| שדה | חובה | תיאור |
|---|---|---|
| `jobId` | כן | ה-`domainBatchId` שהוחזר על ידי [מעקב אחר רענון אתר](#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" }'
```

**תגובה**

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

| שדה | סוג | תיאור |
|---|---|---|
| `status` | string | מצב הרענון לאחר קריאה זו: `cancelled`, `deduplicating`, `completed` או `failed`. |
| `cancelled_units` | integer | כמות העבודה שנותרה לביצוע כאשר התקבלה בקשת הביטול. `0` בביטול חוזר. |
| `sources_reset` | integer | דפים שהוצאו מהעיבוד והוחזרו למצב `ready`. |
| `sources_cancelled` | integer | דפים חדשים לגמרי מרענון זה שעדיין היו בתור וכעת בוטלו. |

ביטול פעמיים אינו מזיק — הקריאה השנייה מדווחת על אותו מצב סופי. ברגע שהרענון עבר לשלב הניקוי, לא ניתן לעצור אותו יותר, והתגובה חוזרת עם `success: false` ו-`reason: "already_finalizing"`. חוסר ב-`jobId` מחזיר `400`, ומשימה שאינה בחשבונך מחזירה `404`.

---

## רענון מקור יחיד

`POST /kb-sources/{sourceId}/refresh`

קורא מחדש דף אינטרנט שכבר ייבאת ומסנכרן את השאלות הנפוצות (FAQs) שלו עם התוכן הנוכחי של הדף: סעיפים ששונו מתעדכנים, חדשים מתווספים, ואלו שהוסרו נמחקים.

**cURL**

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

**תגובה** — `202 Accepted`

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

בצע סקר (Poll) למקור עד שהסטטוס שלו יצא מ-`queued` ו-`processing`. מזהה מקור שאינו בחשבונך מחזיר `404`.

---

## בחירת הדפים הרלוונטיים ביותר

`POST /kb-sources/select-relevant-pages`

מבקש מה-AI לבחור את חמשת הדפים, מתוך רשימת מועמדים, שמתארים בצורה הטובה ביותר עסק — בשימוש בעת יצירת תוכנית פעולה (playbook) לקמפיין מתוך אתר אינטרנט. פעולה זו צורכת קרדיטים.

**שדות הבקשה**

| שדה | חובה | תיאור |
|---|---|---|
| `urls` | כן | כתובות דפי מועמדים לבחירה, בדרך כלל מתוך גילוי דפים. |
| `homeUrl` | כן | דף הבית של האתר, המשמש כהקשר לבחירה. |

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

**תגובה**

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

זהו כלי עזר, לא משאב: במקרה של כשל הוא עדיין משיב `200`, עם `success: false`, רשימת `pages` ריקה והודעת `error`.

---

## קבוצות ידע

**קבוצת ידע** היא צרור בעל שם של שאלות נפוצות (FAQs) — "משלוחים והחזרות", "קליטה" — שניתן להחיל על סוכן או קמפיין בקריאה אחת. הקבוצה מחזיקה הפניות, לא עותקים: השאלות הנפוצות עצמן נשארות בספרייה היחידה שלך, לכן עריכת אחת מהן באמצעות [API של שאלות נפוצות](faqs.md) מעדכנת אותה בכל מקום שבו היא נמצאת בשימוש.

החלת קבוצה תמיד רק **מוסיפה** את מה שחסר, לכן החלת אותה קבוצה פעמיים היא בטוחה ו-`added_count` יחזור כ-`0` בפעם השנייה.

---

## יצירת קבוצת ידע

`POST /kb-groups`

יוצר קבוצה. היא מתחילה ריקה — ניתן להוסיף לה שאלות נפוצות באמצעות [הוספת שאלה נפוצה לקבוצה](#add-a-faq-to-a-group).

**שדות הבקשה**

| שדה | חובה | תיאור |
|---|---|---|
| `name` | כן | שם הקבוצה. |

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

**תגובה** — `201 Created`

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

---

## שינוי שם של קבוצת ידע

`PUT /kb-groups/{groupId}`

משנה את שם הקבוצה. השאלות הנפוצות שבה נשארות ללא שינוי.

**שדות הבקשה**

| שדה | חובה | תיאור |
|---|---|---|
| `name` | כן | שם חדש לקבוצה. |

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

**תגובה**

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

---

## מחיקת קבוצת ידע

`DELETE /kb-groups/{groupId}`

מוחק את הקבוצה. רק הצרור מוסר — השאלות הנפוצות שבו נשארות בספרייה שלך, וכל מה שהקבוצה כבר הוחלה עליו שומר על אותן שאלות נפוצות.

**cURL**

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

**תגובה**

```json
{
  "success": true
}
```

---

## הוספת שאלות נפוצות (FAQ) לקבוצה

`POST /kb-groups/{groupId}/faqs`

מכניס שאלות נפוצות קיימות לקבוצה. פעולה זו משנה רק את הצרור — היא אינה מצמידה את השאלות הנפוצות לסוכן כלשהו בפני עצמו; לשם כך יש להחיל את הקבוצה.

**שדות הבקשה**

| שדה | חובה | תיאור |
|---|---|---|
| `faq_id` | כן | מזהה (ID) של השאלות הנפוצות להוספה. |

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

**תגובה**

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

---

## הסרת שאלות נפוצות מקבוצה

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

מוציא שאלות נפוצות מקבוצה. השאלות עצמן אינן נמחקות, וסוכנים שהקבוצה כבר הוחלה עליהם ימשיכו להחזיק בהן.

**cURL**

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

**תגובה**

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

---

## החלת קבוצה על סוכן

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

מוסיף את כל השאלות הנפוצות שבקבוצה לידע של סוכן בינה מלאכותית בקריאה אחת — הדרך המהירה להעניק לסוכן חדש מאגר ידע שכבר אצרת.

**שדות הבקשה**

| שדה | חובה | תיאור |
|---|---|---|
| `agent_id` | כן | מזהה (ID) של סוכן הבינה המלאכותית שעליו יש להחיל את הקבוצה. |

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

**תגובה**

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

`added_count` הוא מספר השאלות הנפוצות שנוספו בפועל — `0` כאשר הקבוצה ריקה או שכבר הוחלה.

---

## החלת קבוצה על קמפיין

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

גרסת הקמפיין הקלאסי של הקריאה לעיל. בחשבון מבוסס סוכנים, השתמש ב-[החלת קבוצה על סוכן](#apply-a-group-to-an-agent) במקום זאת.

**שדות הבקשה**

| שדה | חובה | תיאור |
|---|---|---|
| `campaign_id` | כן | מזהה הקמפיין שעליו יש להחיל את הקבוצה. |

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

**תגובה**

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

---

## שגיאות API של מאגר הידע

נקודות קצה אלו מחזירות את מעטפת השגיאה הסטנדרטית:

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

| סטטוס | מתי זה קורה בנקודת קצה של מאגר ידע |
|---|---|
| `400` | שדה חובה חסר או לא תקין — `url` ריק, `baseUrl` או `jobId` חסרים, יותר מ-100 כתובות URL בייבוא מרוכז, יותר מ-2,000 מזהים במחיקה מרוכזת, או סוג קובץ שאיננו יכולים לקרוא. |
| `402` | אין מספיק קרדיטים להרצת הייבוא. יש להטעין קרדיטים ולנסות שוב. |
| `403` | `storage_path` מחוץ לתיקיית ההעלאות שלך — או שהתוכנית שלך אינה כוללת גישת API. |
| `404` | המקור, הקבוצה, ה-FAQ, הסוכן, הקמפיין או משימת הרענון לא נמצאו — או שהם אינם קיימים או שהם שייכים לחשבון אחר. |

> **כשלים רכים אינם שגיאות.** גילוי (`discover-pages`, `refresh-domain`) ומסייע בחירת הדפים עונים ב-`200` עם `success: false` והודעת `error` כאשר לא ניתן לקרוא את האתר, במקום להכשיל את הבקשה. תמיד יש לבדוק את `success` לפני קריאת הנתונים.

הקודים המשותפים שכל נקודת קצה יכולה להחזיר — `401`, `403` (התוכנית שלך אינה כוללת גישת API), `429` (מגבלת קצב) ו-`500` — מפורטים עם הנחיות לניסיון חוזר ב-[שגיאות ועימוד](errors-and-pagination.md).

---

## קשור

- [API של שאלות נפוצות (FAQs)](faqs.md) — קריאה, עריכה וקישור של השאלות הנפוצות שהמקורות שלך מייצרים.
- [ניהול שאלות נפוצות](../ai-automation/faq-management.md) — אותו מאגר ידע בלוח הבקרה.
- [סוכני בינה מלאכותית](../ai-agents/ai-agents.md) — הסוכנים שאליהם אתה מצרף מקורות וקבוצות.
- [גישת API](../integrations/api-access.md) — יצירת מפתח ה-API שלך.
- [אימות](authentication.md) — כל הדרכים להעברת המפתח שלך.