# Bilgi Bankası API'si

Bilgi bankanız, yapay zekanın okuduğu kaynaktır. İki bölümden oluşur ve bu sayfa her ikisini de kapsar:

- **Bilgi kaynakları** (`/kb-sources`) — platforma beslediğiniz web sayfaları ve yüklenen belgeler. Her biri okunur, bölümlere ayrılır ve yapay zekanızın yanıt verebileceği SSS'lere dönüştürülür.
- **Bilgi grupları** (`/kb-groups`) — tek bir çağrıda bir Temsilciye veya kampanyaya uygulayabileceğiniz, önceden düzenlediğiniz bir bilgi kümesini oluşturduğunuz bir sonraki Temsilcide yeniden kullanmanıza olanak tanıyan adlandırılmış SSS paketleri.

Bir kaynağın ürettiği SSS'ler, elle yazdıklarınızla aynı kütüphaneye düşer; bu nedenle bir içe aktarma işlemi bittiğinde bunları [SSS API'si](faqs.md) ile okuyabilir, düzenleyebilir ve bağlayabilirsiniz.

Aşağıdaki tüm uç noktalar `https://api.youraiconnector.com/v1` temel URL'sine göredir. Her istek kimlik doğrulamasına tabidir; bkz. [API Erişimi](../integrations/api-access.md) ve [Kimlik Doğrulama](authentication.md). API erişimi ücretli bir özelliktir; bu özellik olmadan istekler `403` ile reddedilir.


> **İçe aktarma kredisi tüketir.** Bir sayfayı veya belgeyi okumak ve ondan SSS yazmak, içeriğin ne kadar olduğuna bağlı olarak yaklaşık oranda kredi tüketir. Büyük bir tarama işlemi başlatmadan önce [İçe aktarmayı tahmin et](#estimate-what-an-import-will-cost) özelliğini kullanın.

---

## İçe aktarma nasıl çalışır

İçe aktarma, beklerken biten bir işlem değil, arka plan görevidir. Her içe aktarma uç noktası hemen bir `source_id` ile yanıt verir ve siz de bitene kadar o kaynağı sorgularsınız:

1. **İçe aktarmayı başlat** — `POST /kb-sources/url` (tek sayfa), `POST /kb-sources/file` (yüklenen belge) veya `POST /kb-sources/bulk-import` (100 sayfaya kadar). Bir kaynak kimliği ve `status: "queued"` alırsınız.
2. **Sorgula** — `status` değeri `queued` veya `processing` olana kadar `GET /kb-sources/{sourceId}` ile sorgulayın.
3. **SSS'leri oku** — durum `ready` olduğunda, ürettiği girdiler SSS kütüphanenizdedir: `GET /faqs`.

Her kaynak şu durumlardan birini bildirir:

| Durum | Anlamı |
|---|---|
| `queued` | Okunmayı bekliyor. Henüz ücretlendirme yapılmadı. |
| `processing` | Şu anda okunuyor ve SSS'lere dönüştürülüyor. |
| `ready` | Tamamlandı. SSS'leri kütüphanenizde. |
| `failed` | İçe aktarılamadı. `error_message` nedenini belirtir. |
| `cancelled` | Okunmadan önce durduruldu (bkz. [İçe aktarmayı durdur](#stop-an-import)). |
| `paused` | İçe aktarma sırasında kendi yapay zeka anahtarınız başarısız olduğu için durduruldu (bkz. [Duraklatılmış içe aktarmayı sürdür](#resume-a-paused-import)). |
| `deleting` | Toplu silme işlemi üzerinde çalışıyor. |
| `unknown` | Kayıt herhangi bir durum taşımıyor. Hazır değil olarak değerlendirin. |

> **İçe aktarırken ekleyin.** Herhangi bir içe aktarma uç noktasında `autoLinkToAgentId` parametresini geçin; kaynak ve ürettiği her SSS, takip eden bir bağlama adımı olmaksızın aynı çağrıda o Temsilcinin bilgisine eklenir. `autoLinkToCampaignId`, klasik bir kampanya için de aynısını yapar. Bağlama işlemi en iyi çaba esasına dayanır: mevcut olmayan veya başka bir hesaba ait olan bir kimlik sessizce atlanır ve içe aktarma yine de çalışır, bu nedenle Temsilciyi geri okuyarak bağlantıyı doğrulayın.

---

## Bir web sayfasını içe aktarın

`POST /kb-sources/url`

Bilgi bankanıza bir web sayfası ekler.

**İstek alanları**

| Alan | Gerekli | Açıklama |
|---|---|---|
| `url` | Evet | Sayfanın tam `http` veya `https` adresi. |
| `autoLinkToAgentId` | Hayır | İçe aktarılan kaynağın ekleneceği bir Yapay Zeka Temsilcisinin (AI Agent) kimliği. |
| `autoLinkToCampaignId` | Hayır | Eski. İçe aktarılan kaynağın ekleneceği bir kampanyanın kimliği. |

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

**Yanıt** — `202 Accepted`

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

Durum `ready` veya `failed` olana kadar [Bir kaynağı kontrol et](#check-a-source) ile `source_id` sorgulayın.

Aynı sayfa zaten bilgi tabanınızda bulunuyorsa, yeni bir şey sıraya alınmaz ve bunun yerine bir `200` alırsınız; ayrıca otomatik bağlantı istediyseniz, mevcut kaynak sizin için yine de bağlanır:

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

Eksik bir `url` veya geçerli bir `http`/`https` adresi olmayan bir değer, `400` döndürür.

---

## Yüklenmiş bir belgeyi içe aktarın

`POST /kb-sources/file`

**Hesabınızın dosya depolama alanında zaten bulunan** bir belgeyi bilgi kaynağı olarak ekler. Desteklenen türler: PDF, DOCX, TXT, MD, CSV ve XLSX.

> **Bu uç nokta dosyayı taşımaz.** Çok parçalı yükleme, base64 gövdesi veya bir URL'den indirme yoktur: zaten var olan bir dosyanın depolama konumunu gönderirsiniz ve bu dosya kendi yükleme klasörünüzün altında bulunmalıdır (`storage_path`, `users/{your user id}/uploads/` ile başlamalıdır), aksi takdirde istek `403` ile reddedilir. Kontrol paneli, dosyaları sürükleyip bıraktığınızda oraya yerleştirir. Oraya dosya koymanın bir yolu yoksa, bunun yerine [Bir web sayfasını içe aktarın](#import-a-web-page) seçeneğini kullanın.

**İstek alanları**

| Alan | Gerekli | Açıklama |
|---|---|---|
| `storage_path` | Evet | Yüklenen dosyanın bulunduğu yer. `users/{your user id}/uploads/` ile başlamalıdır. |
| `filename` | Evet | Uzantısı dahil orijinal dosya adı — dosya türü bu şekilde algılanır. |
| `mime_type` | Evet | Dosyanın MIME türü, örneğin `application/pdf`. |
| `autoLinkToAgentId` | Hayır | Belgenin ekleneceği bir Yapay Zeka Temsilcisinin (AI Agent) kimliği. |
| `autoLinkToCampaignId` | Hayır | Eski. Belgenin ekleneceği bir kampanyanın kimliği. |

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

**Yanıt** — `202 Accepted`

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

| Durum | Ne zaman |
|---|---|
| `400` | Gerekli bir alan eksik veya dosya okuyabileceğimiz bir türde değil. |
| `403` | `storage_path`, kendi yükleme klasörünüzün dışında. |

---

## Bir kaynağı kontrol et

`GET /kb-sources/{sourceId}`

Her içe aktarma ve yenileme işleminden sonra gelen sorgulama. Durum `ready` veya `failed` olana kadar tekrarlayın.

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

**Yanıt**

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

| Alan | Tür | Açıklama |
|---|---|---|
| `status` | string | Kaynağın işlem hattındaki konumu (bkz. [durum tablosu](#how-an-import-works)). |
| `faq_count` | integer | Bu kaynaktan şimdiye kadar kaç SSS oluşturulduğu. |
| `section_count` | integer | Kaynağın kaç içerik bölümüne ayrıldığı. |
| `error_message` | string \| null | Durum `failed` olduğunda içe aktarmanın neden başarısız olduğu. Aksi takdirde `null`. |

---

## Bir kaynağı silme

`DELETE /kb-sources/{sourceId}`

Bir bilgi kaynağını kaldırır. **Varsayılan olarak, oluşturduğu SSS'ler korunur** — bunları da kaldırmak için `delete_faqs=true` ekleyin.

**Sorgu parametreleri**

| Parametre | Gerekli | Açıklama |
|---|---|---|
| `delete_faqs` | Hayır | Bu kaynağın oluşturduğu her SSS'yi de silmek için `true` olarak ayarlayın. Varsayılan değer `false`'dir. |

**cURL**

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

**Yanıt**

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

`faqs_deleted`, `delete_faqs=true` istemediğiniz sürece `0`'dir.

---

## Aynı anda çok sayıda sayfa içe aktarma

`POST /kb-sources/bulk-import`

Tek bir çağrıda 100 adede kadar web sayfası ekler — bu, [Bir web sitesindeki sayfaları keşfetme](#discover-pages-on-a-website) veya [Bir web sitesinde yeni sayfalar bulma](#find-new-pages-on-a-website) işlemlerinin olağan devamıdır. Bilgi tabanınızda zaten bulunan sayfalar çoğaltılmak yerine atlanır (ve istediğinizde Temsilciye bağlı kalmaya devam ederler).

**İstek alanları**

| Alan | Gerekli | Açıklama |
|---|---|---|
| `urls` | Evet | İçe aktarılacak adresler. Çağrı başına en az 1, en fazla 100 adet. |
| `autoLinkToAgentId` | Hayır | İçe aktarılan her sayfayı bağlamak için bir Yapay Zeka Temsilcisinin kimliği. |
| `autoLinkToCampaignId` | Hayır | Eski sürüm. İçe aktarılan her sayfayı bağlamak için bir kampanyanın kimliği. |

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

**Yanıt** — `202 Accepted`

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

`queued_source_ids` içindeki her kimliği [Bir kaynağı kontrol et](#check-a-source) ile sorgulayın. Boş bir `urls` dizisi, dize olmayan bir girdi veya 100'den fazla girdi göndermek `400` döndürür.

---

## Aynı anda çok sayıda kaynağı silme

`POST /kb-sources/bulk-delete`

Tek bir çağrıda 2.000 adede kadar bilgi kaynağını kaldırır. Kaldırma işlemi arka planda çalışır ve tamamlandığında size bir e-posta gönderilir.

> **Toplu silme işlemi SSS'leri de her zaman kaldırır.** Aksi belirtilmedikçe onları tutan [Bir kaynağı sil](#delete-a-source) işleminin aksine, bu uç nokta her kaynağı ürettiği SSS'lerle birlikte siler. Bunları tutmak için bir seçenek yoktur.

**İstek alanları**

| Alan | Gerekli | Açıklama |
|---|---|---|
| `sourceIds` | Evet | Kaldırılacak kaynakların kimlikleri. Çağrı başına en az 1, en fazla 2.000 adet. |
| `domainLabel` | Hayır | Bu temizlik işlemi için kullanıcı dostu bir ad. Yalnızca tamamlama e-postasında kullanılır. |

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

**Yanıt** — `202 Accepted`

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

---

## Bir web sitesindeki sayfaları keşfetme

`POST /kb-sources/discover-pages`

Bir web sitesini başlangıç adresinden itibaren tarar ve aynı alan adında bulunan sayfaları, içe aktarılmaya değer olup olmadıklarına dair bir görüşle birlikte listeler. **Hiçbir şey içe aktarılmaz ve sizin adınıza hiçbir şey seçilmez** — bu, [Birçok sayfayı aynı anda içe aktar](#import-many-pages-at-once) kısmına ne göndereceğinize karar vermeden önce çalıştırdığınız "bu sitede neler var" adımıdır.

**İstek alanları**

| Alan | Gerekli | Açıklama |
|---|---|---|
| `url` | Evet | Keşfetmeye başlanacak adres, genellikle sitenin ana sayfası. |
| `maxPages` | Hayır | Döndürülecek sayfa sayısı için üst sınır. |

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

**Yanıt**

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

| Alan | Tür | Açıklama |
|---|---|---|
| `source_type` | string | Sayfaların nasıl bulunduğu — `sitemap` (sitenin kendi site haritası) veya `link_discovery` (bağlantıları takip ederek). |
| `url` | string | Sayfanın tam adresi. |
| `title` | string \| null | Okunabildiği durumlarda sayfa başlığı. |
| `depth` | integer | Bu sayfanın başlangıç sayfasından kaç bağlantı uzakta bulunduğu. |
| `score` | integer | Sayfanın bilgi kaynağı olarak ne kadar yararlı göründüğü, `0` ile `100` arası. |
| `recommendation` | string | `add` (açıkça içe aktarmaya değer, 90 puan veya üzeri), `maybe` (sınırda) veya `skip` (asistan için nadiren yardımcı olan içerikler — değişiklik günlükleri, yasal sayfalar, yinelenen çeviriler). |
| `reason_key` | string | Önerinin arkasındaki kararlı, makine tarafından okunabilir bir neden; örneğin `core_page`, `changelog_history`, `legal_page` veya `locale_duplicate`. |

> **Keşif en iyi çaba esasına dayanır.** Site okunamıyorsa yanıt yine de `200` olur; `success: false`, boş bir `pages` listesi ve bir `error` mesajı ile birlikte. `pages` kısmını okumadan önce `success` kısmını kontrol edin.

Eksik bir `url`, `400` döndürür.

---

## Bir içe aktarma işleminin maliyetini tahmin etme

`POST /kb-sources/estimate-cost`

Önerilen bir içe aktarma işleminin, siz onaylamadan önce kaç kredi tüketeceğini hesaplar. Sayfalar getirilir ve boyutlarını ölçmek için belgeler okunur, ancak hiçbir şey içe aktarılmaz ve tahminin kendisi kredi harcamaz.

**İstek alanları**

| Alan | Gerekli | Açıklama |
|---|---|---|
| `urls` | Hayır | İçe aktarmayı düşündüğünüz sayfa adresleri. |
| `files` | Hayır | Zaten yüklenmiş olan ve düşündüğünüz dosyalar. Her giriş `storage_path`, `filename` ve `mime_type` gerektirir. |
| `tier` | Hayır | İçe aktarma işleminin üzerinde çalışacağı yapay zeka kalite düzeyi; böylece tahmin, gerçekte ücretlendirileceğiniz tutarla eşleşir. Standart oran için boş bırakın. |

`urls`, `files` veya her ikisini birden gönderin.

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

**Yanıt**

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

Her satır, girişinizle eşleştirebilmeniz için `ref` içindeki URL'yi veya depolama yolunu geri yansıtır. Okunamayan bir sayfa veya dosya yine de bir satır alır, bir parça olarak sayılır ve üzerinde bir `error` bulunur.

---

## Bir içe aktarma işlemini durdurun

`POST /kb-sources/cancel-import`

İçe aktarma kuyruğunda bekleyen sayfaları durdurur — beklediğinizden daha büyük olduğu ortaya çıkan bir tarama için "içe aktarmayı durdur" düğmesi. Bekleyen bir sayfayı iptal etmenin hiçbir maliyeti yoktur, çünkü henüz okunmamıştır.

Hali hazırda işlenmekte olan sayfalar **durdurulmaz**: işlemleri devam etmektedir ve her halükarda ücretlendirilirler, bu yüzden tamamlanırlar. Yanıt, bunlardan kaç tane olduğunu bildirir.

**İstek alanları**

| Alan | Gerekli | Açıklama |
|---|---|---|
| `host` | Hayır | Yalnızca bu web sitesindeki bekleyen sayfaları durdurun (örneğin `docs.example.com`). Hesaptaki tüm bekleyen içe aktarmaları durdurmak için boş bırakın. |

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

**Yanıt**

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

---

## Duraklatılmış bir içe aktarma işlemini devam ettirin

`POST /kb-sources/resume-import`

Kendi yapay zeka anahtarınızın çalışmayı durdurması nedeniyle duraklatılan bir içe aktarma işlemini yeniden başlatır.

> Bunu çağırmak, içe aktarma işlemini o anda aktif olan anahtar üzerinde bitirmeyi kabul ettiğiniz anlamına **gelir** — bu, kendi anahtarınız hala çalışmıyorsa platform kredisi harcamanız gerekebileceği anlamına gelebilir.

**İstek alanları**

| Alan | Gerekli | Açıklama |
|---|---|---|
| `host` | Hayır | Yalnızca bu web sitesinde duraklatılmış sayfaları devam ettirin. Duraklatılan her şeyi devam ettirmek için boş bırakın. |

**cURL**

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

**Yanıt**

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

---

## Bir web sitesinde yeni sayfalar bulun

`POST /kb-sources/refresh-domain`

Daha önce içe aktardığınız bir web sitesini keşfeder ve yalnızca bilgi tabanınızda henüz **olmayan** sayfaları, her biri sayfa keşfi ile aynı öneriye sahip olacak şekilde bildirir. Hiçbir şey içe aktarılmaz ve hiçbir şey değiştirilmez.

İki takip işlemi kasıtlı olarak ayrı çağrılardır, bu yüzden bundan vazgeçmenin hiçbir maliyeti yoktur:

- [Birden fazla sayfayı aynı anda içe aktar](#import-many-pages-at-once) ile istediğiniz yeni sayfaları içe aktarın;
- [Bir web sitesindeki her sayfayı yenile](#refresh-every-page-on-a-website) ile zaten sahip olduğunuz sayfaları yeniden okuyun.

**İstek alanları**

| Alan | Gerekli | Açıklama |
|---|---|---|
| `baseUrl` | Evet | Web sitesindeki herhangi bir adres veya sadece ana bilgisayar adı. |
| `maxPages` | Hayır | Keşfedilecek sayfa sayısı için üst sınır. |

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

**Yanıt**

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

| Alan | Tür | Açıklama |
|---|---|---|
| `discovered` | tamsayı | Sitede toplamda kaç sayfa bulundu. |
| `new_pages` | dizi | Henüz bilgi tabanınızda olmayan sayfalar. Sizin için hiçbir şey kuyruğa alınmaz; istediklerinizi içe aktarın. |
| `new_urls_queued` | tamsayı | Her zaman `0`. Geriye dönük uyumluluk için tutulmuştur; bu uç nokta hiçbir şeyi kuyruğa almaz. |
| `existing_refresh_queued` | tamsayı | Bu siteden daha önce içe aktardığınız sayfalardan kaç tanesinin yeniden okunmaya hazır olduğu bulundu. Bu çağrı ile hiçbir şey kuyruğa alınmaz. |
| `batch_id` | dize | Yalnızca bir toplu iş oluşturulduğunda mevcuttur. |

Keşif gibi, bu da yumuşak bir şekilde başarısız olur: okunamayan bir site yine de `200`, `success: false`, boş bir `new_pages` ve bir `error` ile döner. Eksik veya boş bir `baseUrl`, `400` döndürür.

---

## Bir web sitesindeki her sayfayı yenile

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

Bir web sitesinden daha önce içe aktardığınız her sayfayı yeniden okur, böylece SSS'ler sitenin güncel içeriğini takip eder: değiştirilen bölümler güncellenir, yeni bölümler eklenir ve kaldırılan bölümler silinir.

Bu, işi kuyruğa alır ve hemen döner. Ardından [Bir web sitesi yenilemesini takip et](#track-a-website-refresh) ile takip edin ve [Bir web sitesi yenilemesini durdur](#stop-a-website-refresh) ile durdurun.

**İstek alanları**

| Alan | Gerekli | Açıklama |
|---|---|---|
| `baseUrl` | Evet | Web sitesindeki herhangi bir adres veya sadece ana bilgisayar adı. |

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

**Yanıt**

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

---

## Bir web sitesi yenilemesini takip et

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

Bir web sitesi yenilemesinin ne kadar ilerlediğini gösterir, böylece "249'un 221'i" gibi bir ilerleme durumu gösterebilirsiniz.

**Sorgu parametreleri**

| Parametre | Gerekli | Açıklama |
|---|---|---|
| `baseUrl` | Evet | Web sitesindeki herhangi bir adres veya sadece ana bilgisayar adı. |

**cURL**

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

**Yanıt**

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

O web sitesi için hiçbir yenileme çalışmadığında `job`, `null` değerindedir. Şimdiye kadar tamamlanan sayfalar `total` eksi `pending`'tür. `status` işi; `refreshing` (sayfalar üzerinde çalışılıyor), `deduplicating` (sonundaki temizleme geçişi) veya nihai `completed`, `failed` ve `cancelled` durumlarından biridir. `domainBatchId` değerini saklayın; iptal uç noktasına ileteceğiniz değer budur.

Eksik veya boş bir `baseUrl`, `400` döndürür.

---

## Bir web sitesi yenilemesini durdurun

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

Hâlâ sayfaları üzerinde işlem yapan bir web sitesi yenilemesini durdurur. Zaten tamamlanmış sayfalar güncellenmiş içeriklerini korur; henüz başlanmamış sayfalar bırakılır ve yeniden okunmakta olan sayfalar önceki durumlarına geri döner.

**İstek alanları**

| Alan | Gerekli | Açıklama |
|---|---|---|
| `jobId` | Evet | [Bir web sitesi yenilemesini takip et](#track-a-website-refresh) tarafından döndürülen `domainBatchId`. |

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

**Yanıt**

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

| Alan | Tür | Açıklama |
|---|---|---|
| `status` | string | Bu çağrıdan sonra yenilemenin durumu: `cancelled`, `deduplicating`, `completed` veya `failed`. |
| `cancelled_units` | integer | İptal gerçekleştiğinde hâlâ bekleyen iş miktarı. Tekrarlanan bir iptalde `0`. |
| `sources_reset` | integer | İşlemden geri alınan ve `ready` durumuna döndürülen sayfalar. |
| `sources_cancelled` | integer | Bu yenilemenin henüz kuyrukta olan ve şimdi iptal edilen yepyeni sayfaları. |

İki kez iptal etmek zararsızdır; ikinci çağrı aynı nihai durumu bildirir. Yenileme temizleme aşamasına geçtikten sonra artık durdurulamaz ve yanıt `success: false` ve `reason: "already_finalizing"` ile döner. Eksik bir `jobId`, `400` döndürür ve hesabınızda bulunmayan bir iş `404` döndürür.

---

## Tek bir kaynağı yenileyin

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

Daha önce içe aktardığınız bir web sayfasını yeniden okur ve SSS'lerini sayfanın mevcut içeriğiyle uyumlu hale getirir: değiştirilen bölümler güncellenir, yenileri eklenir, kaldırılanlar çıkarılır.

**cURL**

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

**Yanıt** — `202 Accepted`

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

Durumu `queued` ve `processing` değerlerinden çıkana kadar kaynağı sorgulayın. Hesabınızda bulunmayan bir kaynak kimliği `404` döndürür.

---

## En alakalı sayfaları seçin

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

Yapay zekadan, bir aday listesinden bir işletmeyi en iyi tanımlayan beş sayfayı seçmesini ister; bu, bir web sitesinden kampanya kılavuzu oluştururken kullanılır. Bu işlem kredi tüketir.

**İstek alanları**

| Alan | Gerekli | Açıklama |
|---|---|---|
| `urls` | Evet | Genellikle sayfa keşfinden elde edilen, seçim yapılacak aday sayfa adresleri. |
| `homeUrl` | Evet | Seçim için bağlam olarak kullanılan sitenin ana sayfası. |

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

**Yanıt**

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

Bu bir yardımcıdır, kaynak değildir: hata durumunda yine de `200`, `success: false`, boş bir `pages` listesi ve bir `error` mesajı ile yanıt verir.

---

## Bilgi grupları

Bir **bilgi grubu**, tek bir çağrıda bir Temsilciye veya kampanyaya uygulayabileceğiniz, "Gönderim ve iadeler", "İşe alım" gibi SSS'lerden oluşan adlandırılmış bir pakettir. Grup, kopyaları değil referansları tutar: SSS'lerin kendisi tek bir kütüphanenizde kalır, bu nedenle birini [FAQs API](faqs.md) ile düzenlemek, kullanıldığı her yerde güncellenmesini sağlar.

Bir grubu uygulamak yalnızca eksik olanı **ekler**, bu nedenle aynı grubu iki kez uygulamak zararsızdır ve ikinci seferde `added_count`, `0` olarak döner.

---

## Bilgi grubu oluşturma

`POST /kb-groups`

Bir grup oluşturur. Boş başlar; [Bir gruba SSS ekle](#add-a-faq-to-a-group) ile gruba SSS ekleyebilirsiniz.

**İstek alanları**

| Alan | Gerekli | Açıklama |
|---|---|---|
| `name` | Evet | Grubun adı. |

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

**Yanıt** — `201 Created`

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

---

## Bilgi grubunu yeniden adlandırma

`PUT /kb-groups/{groupId}`

Bir grubun adını değiştirir. İçindeki SSS'lere dokunulmaz.

**İstek alanları**

| Alan | Gerekli | Açıklama |
|---|---|---|
| `name` | Evet | Grubun yeni adı. |

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

**Yanıt**

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

---

## Bilgi grubunu silme

`DELETE /kb-groups/{groupId}`

Grubu siler. Yalnızca paket kaldırılır; içindeki SSS'ler kütüphanenizde kalır ve grubun daha önce uygulandığı her şey bu SSS'leri korumaya devam eder.

**cURL**

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

**Yanıt**

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

---

## Bir gruba SSS ekleme

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

Mevcut bir SSS'yi bir gruba dahil eder. Bu işlem yalnızca paketi değiştirir; SSS'yi tek başına herhangi bir Temsilciye (Agent) bağlamaz; bunun için grubu uygulamanız gerekir.

**İstek alanları**

| Alan | Gerekli | Açıklama |
|---|---|---|
| `faq_id` | Evet | Eklenecek SSS'nin kimliği (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" }'
```

**Yanıt**

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

---

## Bir gruptan SSS kaldırma

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

Bir SSS'yi gruptan çıkarır. SSS'nin kendisi silinmez ve grubun daha önce uygulandığı Temsilciler (Agent) SSS'yi tutmaya devam eder.

**cURL**

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

**Yanıt**

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

---

## Bir Temsilciye (Agent) grup uygulama

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

Gruptaki her SSS'yi tek bir çağrıda bir Yapay Zeka Temsilcisinin (AI Agent) bilgisine ekler; bu, yeni bir Temsilciye halihazırda düzenlediğiniz bir bilgi kümesini vermenin hızlı yoludur.

**İstek alanları**

| Alan | Gerekli | Açıklama |
|---|---|---|
| `agent_id` | Evet | Grubun uygulanacağı Yapay Zeka Temsilcisinin (AI Agent) kimliği (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"]
```

**Yanıt**

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

`added_count`, aslında kaç SSS'nin eklendiğini gösterir; grup boş olduğunda veya zaten uygulandığında `0` değerini döndürür.

---

## Bir kampanyaya grup uygulama

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

Yukarıdaki çağrının klasik kampanya sürümüdür. Temsilci (Agent) tabanlı bir hesapta bunun yerine [Bir Temsilciye grup uygulama](#apply-a-group-to-an-agent) seçeneğini kullanın.

**İstek alanları**

| Alan | Gerekli | Açıklama |
|---|---|---|
| `campaign_id` | Evet | Grubun uygulanacağı kampanyanın kimliği (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" }'
```

**Yanıt**

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

---

## Bilgi Bankası API hataları

Bu uç noktalar standart hata zarfını döndürür:

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

| Durum | Bir bilgi bankası uç noktasında gerçekleştiğinde |
|---|---|
| `400` | Gerekli bir alan eksik veya geçersiz — boş bir `url`, eksik bir `baseUrl` veya `jobId`, toplu içe aktarmada 100'den fazla URL, toplu silmede 2.000'den fazla kimlik veya okuyamadığımız bir dosya türü. |
| `402` | İçe aktarma işlemini çalıştırmak için yeterli kredi yok. Kredi yükleyin ve tekrar deneyin. |
| `403` | Kendi yükleme klasörünüzün dışında bir `storage_path` — veya planınız API erişimini içermiyor. |
| `404` | Kaynak, grup, SSS, Temsilci, kampanya veya yenileme işi bulunamadı — ya mevcut değil ya da başka bir hesaba ait. |

> **Hafif hatalar hata değildir.** Keşif (`discover-pages`, `refresh-domain`) ve sayfa seçme yardımcısı, web sitesi okunamadığında isteği başarısız kılmak yerine `success: false` ve bir `error` mesajı ile `200` yanıtını verir. Verileri okumadan önce her zaman `success` kontrol edin.

Her uç noktanın döndürebileceği ortak kodlar — `401`, `403` (planınız API erişimini içermiyor), `429` (hız sınırı) ve `500` — yeniden deneme rehberliği ile birlikte [Hatalar ve Sayfalandırma](errors-and-pagination.md) bölümünde listelenmiştir.

---

## İlgili

- [SSS API](faqs.md) — kaynaklarınızın ürettiği SSS'leri okuyun, düzenleyin ve bağlayın.
- [SSS Yönetimi](../ai-automation/faq-management.md) — kontrol panelindeki aynı bilgi bankası.
- [Yapay Zeka Temsilcileri](../ai-agents/ai-agents.md) — kaynakları ve grupları eklediğiniz Temsilciler.
- [API Erişimi](../integrations/api-access.md) — API anahtarınızı oluşturun.
- [Kimlik Doğrulama](authentication.md) — anahtarınızı iletmenin tüm yolları.