# Admin API

> Panonun kendi JSON REST API'si — kimlik doğrulama, SSO, projeler, arama, kaynaklar, üyeler, MCP tokenları, webhook'lar, metrikler, audit log ve paylaşılan hata biçimleri.

- Güncelleme: 2026-11-04
- Kaynak: https://contextator.com/tr/docs/admin-api/
- Dil: tr-TR
- Yazar: Muhammet Şafak

---
Panonun yapabildiği her şey bir JSON REST çağrısıdır — pano yalnızca bu API'nin bir istemcisidir. Onu
betiklenmiş kurulum, zamanlanmış yeniden indeksleme ya da izleme için kullanın.

**Temel URL** `http://localhost:3444/api`

## Kimlik doğrulama

Her istek şu üç kimlik bilgisinden birini taşır:

| | Nedir | Kim kullanır |
|---|---|---|
| **Bir oturum çerezi** | `POST /api/auth/login` tarafından ayarlanan `contextator_session` | Pano, ve bir tarayıcıyı süren her şey |
| **`Authorization: Bearer ctxk_…`** | Bir hesabın kendi **API token'ı** — adlandırılmış, rota alt kümesine ve opsiyonel olarak bir projeye kapsanmış, kendi başına iptal edilebilir | Bir hesabın yetkisinin yalnızca *bir kısmını* taşıması gereken betikler ve CI job'ları — aşağıda [API tokenları](#api-tokenları)'na bakın |
| **`Authorization: Bearer $ADMIN_TOKEN`** | `root` izinleriyle makine erişimi | Örneğin tamamına ihtiyaç duyan betikler, CI, cron |

```bash
export API=http://localhost:3444/api
export TOKEN=your-admin-token
curl -s $API/projects -H "Authorization: Bearer $TOKEN" | jq
```

Bu ayrımdan beş şey çıkar:

- **Ne yapabileceğiniz kim olduğunuza bağlıdır.** Bir oturum bir hesaba bağlıdır, bu yüzden onun örnek
  rolü ve proje başına üyelikleri her çağrıya karar verir — bkz.
  [Hesaplar ve İzinler](/tr/docs/accounts-and-permissions/). `ADMIN_TOKEN` her zaman `root` gibi davranır.
- **Bir API token'ı, onu üreten hesaptan asla daha fazlasını yapamaz.** Kapsamı, o hesabın kendi rolü ve
  üyeliğinden *sonra* denetlenir, bu yüzden onu daraltmak — bir projeye, ya da bir avuç rotaya —
  yalnızca yetkiyi azaltabilir, asla artıramaz.
- **Bir şeyi değiştiren bir çerez isteği bu siteden gelmelidir.** Sunucu `Sec-Fetch-Site`'ı denetler,
  yoksa `Origin` ve `Referer`'a düşer, aksi halde `403 csrf_blocked` yanıtlar. Bearer istekleri
  muaftır: hiçbir çevresel kimlik bilgisi taşımazlar, bu yüzden ikisini de göndermeyen `curl` ve CI
  değişmeden çalışır.
- **İki bearer token'dan hiçbiri, bu rotalar söz konusu olduğunda, oturum açmış bir hesap sayılmaz.**
  *Sizin* hesabınızla ilgili endpoint'ler (`/api/auth/password`, `/api/auth/sessions`) bir oturum
  gerektirir — bu denetim, tam olarak o rotaya izin verecek şekilde kapsanmış bir token dahil,
  `ADMIN_TOKEN`'ı ve kapsamlı bir API token'ını aynı şekilde `403 token_has_no_account` ile reddeder.
  Yalnızca bir oturum çerezi taşıyan bir tarayıcı onlara ulaşabilir.
- **Ulaşamadığınız bir proje `403` değil `404` yanıtlar**, var olmayan bir projeyle aynı şekilde, bu
  yüzden id'ler yoklanamaz. Ulaşabildiğiniz ama bu şekilde kullanamayacağınız bir rota `403` yanıtlar.

`GET /api/health`, `GET /api/setup/status`, `POST /api/setup`, `POST /api/auth/login`,
`GET /api/auth/oidc/login` ve `GET /api/auth/oidc/callback`, hiçbir kimlik bilgisi olmadan ulaşılabilen
tek endpoint'lerdir — son ikisi, tarayıcı yönlendirmeyi istediğinde henüz bir oturumu olmadığı için, ve
sağlayıcı **tarayıcıyı** kodla birlikte, bir yönlendirmeyle callback'e geri gönderdiği için — sağlayıcının
kendisinden sunucudan sunucuya bir çağrı değil. Zaten oturum açmış bir hesabı aynı sağlayıcıya
bağlamak (`POST /api/auth/oidc/link`, `DELETE /api/auth/oidc/link` — bkz. [Tek Oturum
Açma](/tr/docs/sso/#kendi-hesabınızı-bağlamak-ya-da-bağlantısını-kesmek)) farklıdır: çağıranın kendi
oturumuna ihtiyaç duyar, tıpkı başka her self-servis hesap endpoint'i gibi.

---

## Sağlık

```bash
curl -s $API/health | jq
```

```json
{
  "ok": true,
  "version": "1.0.0",
  "uptimeSec": 3610,
  "db": "up",
  "database": { "mode": "embedded" },
  "embeddings": {
    "id": "local:Xenova/multilingual-e5-small:fp32:\"query: \"+\"passage: \"",
    "provider": "local", "model": "Xenova/multilingual-e5-small",
    "dimensions": 384, "dtype": "fp32", "ready": true
  },
  "chunkBudget": { "checked": true, "ok": true, "chunkMaxTokens": 96, "suggestedChunkMaxTokens": null },
  "sessions": { "total": 2, "streamable": 2, "sse": 0 },
  "allowedDocRoots": ["/docs"],
  "dataDir": "/data",
  "secretKeyConfigured": true,
  "uploads": { "maxFileBytes": 52428800, "maxFilesPerRequest": 500, "maxArchiveBytes": 268435456 }
}
```

İyi bir canlılık probu: `ok === true && db === "up"`. İyi bir hazırlık probu: ayrıca
`embeddings.ready`. Yanıt, veritabanına ulaşılamadığında aynı gövdeyle `503` yanıtlar, aksi halde
`200` — bir izleyicinin bunun için ikinci bir denetime ihtiyacı yoktur.

`embeddings` modelin girdi penceresini taşır — `maxInputTokens` (modelin işe yarar biçimde okuduğu miktar), `truncatesAtTokens` (çalışma zamanının kestiği yer) ve `windowSource` — yanında `queryPrefix` ve `passagePrefix` (simetrik bir model için boş dizeler), `chunkBudget` ise `CHUNK_MAX_TOKENS`'ın onun içine sığıp sığmadığını söyler (model yüklenene kadar `checked` değeri `false`'tur), bu yüzden parçaları sessizce kesecek bir yanlış yapılandırma arama kalitesinde ortaya çıkmadan
önce burada görünür — bkz. [Yapılandırma](/tr/docs/configuration/#değişiklikleri-uygulamak).

Anonim bir çağıran daha kısa bir cevap alır — `ok`, `version`, `db`, `authRequired` ve `needsSetup` —
çünkü geri kalanı makineyi anlatır. `uptimeSec`, `database`, `embeddings`, `chunkBudget` ve `sessions` (yukarıda gösterilenler) dışında, oturum açmış bir yanıt ayrıca `disk` taşır — `DATA_DIR` için `{ freeBytes, totalBytes, minFreeBytes, ok }`, dosya sistemi okunamıyorsa `null`; bilgi verir, `ok` değerini ya da durum kodunu değiştirmez — ve kaynak iletişim kutusunun çalıştığı aralık olan `sync`: `{ defaultIntervalMinutes, minIntervalMinutes, maxIntervalMinutes, webhookMinIntervalMinutes, webhookVerificationWindowMinutes }`.

Oturum açmış bir `member` ortadaki biçimi alır: `allowedDocRoots`, `dataDir`, `secretKeyConfigured` ve veritabanı hedefi hariç her şey; bunlar bir yöneticiye kalır. Bir izleyicinin izlediği alanlar her iki biçimde de vardır.

## Kurulum ve oturum açma

| Yöntem ve yol | Açıklama |
|---------------|-------------|
| `GET /api/setup/status` | `{ needsSetup, oidc }` — `needsSetup`, bu örneğin hiç hesabı yokken `true`'dur; `oidc`, tek oturum açma yapılandırılmışsa `{ enabled, buttonLabel }`, değilse `{ enabled: false }`'tur. Herkese açık |
| `POST /api/setup` | `{ code, username, displayName?, email?, password }` → `201 { user }`, ve oturum çerezi. İlk `root` hesabını oluşturur. Yanlış kodda `403 invalid_setup_code`; bir hesap var olduktan sonra `409`. Herkese açık |
| `POST /api/auth/login` | `{ username, password }` → `{ user, mustChangePassword }` ve çerez. Hem yanlış bir parola hem de bilinmeyen bir kullanıcı adı için `401 invalid_credentials`, `403 account_disabled`, hız sınırlandığında `Retry-After` ile `429`. Herkese açık |
| `POST /api/auth/logout` | Bu oturumu iptal eder ve çerezi temizler → `204`. İdempotenttir |
| `GET /api/auth/me` | Oturum açmış hesap, rolü, `authKind` (`session`\|`token`\|`apiToken` — bir pano oturumu, `ADMIN_TOKEN` ya da bir API token'ı), ve bir `member` için `projects` içindeki proje başına rolleri. Ayrıca `oidc` (`{ enabled, buttonLabel }`), `canLinkOidc` (root için `false`) ve `federatedProviders` — aşağıda [Tek oturum açma](#tek-oturum-açma)'ya bakın |
| `POST /api/auth/password` | `{ currentPassword, newPassword }` → `204`. `mustChangePassword`'ü temizler, bu hesabın **diğer** oturumlarını iptal eder ve MCP connector kimlik bilgilerini sona erdirir. `currentPassword` yanlışsa `401 invalid_credentials` |
| `GET /api/auth/sessions` | Kendi canlı oturumlarınız: her biri ne zaman başladı, en son ne zaman görüldü, user agent'ı ve IP'si, ve hangisi `current` |
| `DELETE /api/auth/sessions?scope=others\|all` | Onları sonlandırır → `204`. Varsayılan `others`'tır; `all` sizi de çıkarır |

```bash
# sign in and keep the cookie in a jar, then use it like a browser would
curl -s -c jar -X POST $API/auth/login -H 'content-type: application/json' \
  -d '{"username":"alice","password":"…"}' | jq
curl -s -b jar $API/auth/me | jq
```

## Tek oturum açma

Yalnızca bu örnekte bir OIDC sağlayıcısı yapılandırılmışsa bulunur — kimin bağlayabileceği ve root'un
neden bağlayamadığı için bkz. [Tek Oturum Açma](/tr/docs/sso/).

| Yöntem ve yol | Açıklama |
|---------------|-------------|
| `GET /api/auth/oidc/login` | Oturum açmak için kimlik sağlayıcıya yönlendirir. Herkese açık — tarayıcının henüz bir oturumu yoktur |
| `GET /api/auth/oidc/callback` | Kimlik sağlayıcı **tarayıcıyı** kodla birlikte, bir yönlendirmeyle buraya geri gönderir — sağlayıcıdan sunucudan sunucuya bir çağrı değil. Herkese açıktır çünkü bir oturum açma henüz bir oturum olmadan gelir; bir bağlama ise onu başlatan oturumla, yönlendirmenin kendi çerezinin taşıdığı şekilde gelir. Bir `root` hesabını oturum açtırmayı reddeder (`root_local_only`), bağlantısı bir `root`'a yükseltilmeden önce yapılmış olsa bile — rol, bağlantının yapıldığı andan varsayılmaz, callback anında hesaptan yeniden okunur |
| `POST /api/auth/oidc/link` | Zaten oturum açmış bir hesap için self-servis: aynı yönlendirmeyi başlatır, ama oturum açmak yerine sağlayıcıyı bu hesaba *bağlamak* için. Bir `POST` olduğu için same-site denetimi geçerlidir. → gidilecek `200 { url }`. Root için reddedilir (`403 root_local_only`) — root asla SSO üzerinden oturum açmaz |
| `DELETE /api/auth/oidc/link` | Çağıranın kendi bağlı kimliğini kaldırır → `204`. Kendi hesabınıza kapsanmıştır; başka bir hesabın bağlantısı üzerinde bir admin görünümü yoktur. Root için reddedilmez — root'a yükseltilmeden önce yapılmış bir bağlantı kaldırılana kadar yerinde kalır, ve bunu yapan yol budur. Ayrıca hesabın tuttuğu her oturumu ve API token'ını, bu çağrıyı yapanı da dahil, ve — aynı transaction içinde — hesaba verilmiş her MCP OAuth erişim ve yenileme token'ını iptal eder, bu yüzden onunla oturum açmış bir MCP istemcisi yeniden yetkilendirene kadar `401` alır; diğer hesaplar dokunulmadan kalır. Bağlantı kesmenin audit olayı sayıyı `detail.revokedMcpCredentials` olarak kaydeder. **`409 last_sign_in_method`** — hiçbir şey kaldırılmaz, hiçbir şey iptal edilmez — hesabın yerel bir parolası yoksa ve bu bağlantı oturum açmasının tek yoluysa; bir admin önce `POST /api/users/:id/password` ile bir parola ayarlar, ve bağlantı kesme ardından başarılı olur |

## Hesaplar

`/api/users/*`, `admin` ya da `root` gerektirir. Yalnızca bir `root` hesabı başka bir `root` hesabı
oluşturabilir, değiştirebilir ya da silebilir. `PATCH /api/users/:id`, hâlâ bağlı bir SSO kimliği olan
bir hesapta `role: "root"` ayarlamak istendiğinde `409 root_requires_unlink` ile reddeder — önce onu
yukarıdaki `DELETE /api/auth/oidc/link` ile bağlantısını kesin.

| Yöntem ve yol | Açıklama |
|---------------|-------------|
| `GET /api/users` | Her hesap: rol, active anahtarı, `mustChangePassword`, proje sayısı, son oturum açma, ve `activeSessionCount` |
| `POST /api/users` | `{ username, displayName?, email?, role?, password?, mustChangePassword? }` → `201 { user, temporaryPassword }`. `role` varsayılan olarak `member`, `mustChangePassword` varsayılan olarak `true`; `password`'ü atlayın, biri üretilir ve **bir kez** döndürülür |
| `GET /api/users/:id` | `{ user, activeSessionCount }` |
| `PATCH /api/users/:id` | `{ displayName?, email?, role?, isActive? }` → güncellenmiş hesap. Bir düşürme ya da devre dışı bırakma o hesabın oturumlarını da sona erdirir |
| `POST /api/users/:id/password` | `{ password? }` → `{ temporaryPassword }`. Sonraki oturum açmada bir değişikliği zorlar ve o hesabın oturumlarını ve MCP connector kimlik bilgilerini sona erdirir |
| `DELETE /api/users/:id` | Hesabı, oturumlarını ve üyeliklerini siler → `204` |
| `DELETE /api/users/:id/sessions` | O hesabı her yerde oturumdan çıkarır → `204` |

`409`, son aktif root hesabını silinmeye, düşürülmeye ve devre dışı bırakılmaya karşı korur; `403`, bir
admin'in bir root hesabına uzanmasına ve herkesin kendi rolüne, active anahtarına ya da silinmesine uzanmasına karşı
korur.

```bash
# hand someone a new temporary password without touching the dashboard
ID=$(curl -s $API/users -H "Authorization: Bearer $TOKEN" | jq -r '.[] | select(.username=="alice") | .id')
curl -s -X POST $API/users/$ID/password -H "Authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' -d '{}' | jq -r .temporaryPassword
```

## API tokenları

`/api/tokens*` yalnızca bir oturum gerektirir — her hesap **kendi** tokenlarını yönetir, ve başkasının
tokenları üzerinde bir admin görünümü yoktur. Bir betiğin ya da CI job'unun `ADMIN_TOKEN`'dan daha dar
bir kimlik bilgisi alma yolu budur: adlandırın, opsiyonel olarak bir projeye ve bir son kullanma
tarihine sabitleyin, ve tam olarak hangi rotaları çağırabileceğini listeleyin. Bir projeye sabitlenmiş token yalnızca o projenin `/api/projects/:id/*` rotalarını çağırabilir: `GET /api/projects` ya da `GET /api/audit` gibi örnek düzeyindeki bir rota, token'ın scope listesinde yer alsa bile `403` yanıtlar. Panonun kendi **Account
menu → API tokens** sayfası tam olarak bu endpoint'lerin bir istemcisidir — orada `curl`'e hiç
dokunmadan üretin, listeleyin ve iptal edin.

| Yöntem ve yol | Açıklama |
|---------------|-------------|
| `GET /api/tokens` | Kendi tokenlarınız: `id`, `name`, `prefix`, `scope`, `projectId`, `createdAt`, `lastUsedAt`, `revokedAt`, `expiresAt`. Asla secret değil |
| `POST /api/tokens` | `{ name?, scope, projectId?, expiresAt? }` → `201 { token, secret }`. `scope`, `"POST /api/projects/:id/reindex"` gibi bir ya da daha fazla `"<METHOD> <route template>"` dizesidir. Üretme yalnızca bu biçimi ve, verildiyse, `expiresAt`'in gelecekte olduğunu denetler — bir girdiyi kendi rolünüze karşı, ya da `projectId`'yi kendi projelerinize karşı denetlemez. Token'ı sınırlı tutan şey, her isteğin *canlı* rolünüzü ve proje erişiminizi çağrı anında yeniden denetlemesidir. `secret` yalnız bu yanıtta döner, bir daha asla döndürülmez. Üretim çalışabilmeden önce oturumunuz iptal edildiyse `401 session_revoked`. Gelecekte olmayan bir `expiresAt`, standart `400 validation_failed` yanıtlar; `issues` içinde `path`'i `["expiresAt"]` ve `message`'ı `must be in the future` olan bir girdi bulunur |
| `DELETE /api/tokens/:tokenId` | Kendi tokenlarınızdan birini iptal eder → `204`. Bir sonraki istekte hemen etkili olur |

```bash
# mint a token that can only reindex one project — /api/tokens needs a session, not
# ADMIN_TOKEN, so sign in first (see "Setup and sign-in" above) and reuse the cookie jar.
# a cookie-authenticated request that changes something needs Sec-Fetch-Site too — see the
# CSRF rule above — curl never sends it on its own, unlike a real page's fetch would
curl -s -X POST $API/tokens -b jar \
  -H 'content-type: application/json' -H 'Sec-Fetch-Site: same-origin' \
  -d '{"name":"ci-reindex","scope":["POST /api/projects/:id/reindex"],"projectId":"'"$P"'"}' | jq
```

`projectId` içinde adlandırılan projeyi silmek, erişimini genişletmek yerine token'ı da siler.

## SSO grup eşlemeleri

| Yöntem ve yol | Açıklama |
|---------------|-------------|
| `GET /api/oidc/group-mappings` | Bir kimlik sağlayıcı grubundan bir projeye ve bir role (`viewer` ya da `editor`) eşlemeler. `admin` |
| `POST /api/oidc/group-mappings` | Bir tane ekler; o grup o projeyi zaten eşliyorsa `409 mapping_exists`. `admin` |
| `DELETE /api/oidc/group-mappings/:id` | Bir tane kaldırır; ona dayanan üyelikler aynı istekte yeniden hesaplanır. `admin` |

Eşlemelerin oturum açışta nasıl kullanıldığı: [Tek Oturum Açma](/tr/docs/sso/#gruplar-proje-üyeliği-verir).
`GET /api/projects/:id/members` her üye için `origin` (`manual` ya da `oidc_group`) ve `groups` döndürür; `OIDC_GROUPS_CLAIM`
ayarlıyken üyelik API'si, gruptan gelen bir satır için `409 membership_managed_by_group` yanıtı verir. `GET /api/auth/me`
`oidc.groups` taşır.

## Proje üyeleri

Bir projeye kim ulaşır. `root`, `admin` ve `ADMIN_TOKEN` her projeye bir üyelik olmadan ulaşır, bu
yüzden burada yalnızca `member` hesapları görünür.

| Yöntem ve yol | Açıklama |
|---------------|-------------|
| `GET /api/projects/:id/members` | Projenin üyeleri ve rolleri. Projenin herhangi bir üyesi bunu okuyabilir |
| `PUT /api/projects/:id/members/:userId` | `{ "role": "viewer" \| "editor" }` → üye. Üyeliği oluşturur ya da değiştirir (root/admin) |
| `DELETE /api/projects/:id/members/:userId` | Erişimi iptal eder → `204` (root/admin) |

Bir `member` hesabının sonra görebileceği bir projeye üye eklemek:

```bash
curl -s -X PUT $API/projects/$P/members/$ID -H "Authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' -d '{"role":"editor"}' | jq
```

Hedef bir `admin` ya da `root` hesabıysa `400` — zaten erişimleri vardır, bu yüzden bir üyelik satırı
doğru olmayan bir şey söylerdi.

## Projeler

| Yöntem ve yol | Açıklama |
|---------------|-------------|
| `GET /api/projects` | Sayılarla, `mcpUrl` ile ve canlı indeksleme `job`'uyla birlikte tüm projeler |
| `POST /api/projects` | `{ "name": "demo", "rootPath": "/docs/demo", "index": true }` → `201`. `rootPath` opsiyoneldir ve ilk yerel kaynağı oluşturur. Yanıt ayrıca `mcpToken` taşır — yeni bir projenin beraberinde doğduğu ilk MCP token'ı için `{ token, secret }`, yalnızca bu bir kez okunabilir — ya da `null` |
| `GET /api/projects/:id` | Listenin biçimiyle bir proje, artı `quotas: { documents, chunks, uploadBytes }`; her biri `{ limit, used, inherited }`. `limit` etkin limittir (`0` sınırsız demektir); `used` projenin belge sayısı, chunk sayısı ve saklanan upload baytıdır (disk ölçülemediyse `null`); `inherited`, projenin kendi limiti olmadığı için limit instance'ın `PROJECT_MAX_*` değeri olduğunda `true`'dur. Bir `viewer`'ın işidir |
| `GET /api/projects/:id/status` | Bir proje, artı job'u |
| `POST /api/projects/:id/reindex?force=true` | Bir çalışmayı kuyruğa alır → `202 { job }`. `force`, `true`, `false`, `1` ya da `0`'dır; zorlanmış bir çalışma canlı olanın yanına ikinci bir indeks generation'ı yazar, bu yüzden gömülü veritabanının veri dizini onu barındıramayacak kadar doluysa `507 insufficient_disk` yanıtlar |
| `GET /api/projects/:id/runs` | En yeniden en eskiye son indeksleme çalışmaları |
| `GET /api/projects/:id/search?q=…&limit=…&source=…&path_prefix=…&version=…` | Projenin `search_docs` aracının çalıştırdığı aynı arama, JSON olarak: `{ query, limit, source, pathPrefix, version, belowFloor, scoreFloor, scoreFloorOverridden, hits: [{ score, fusedScore, denseRank, lexicalRank, path, title, headingPath, chunkIndex, content, contextBefore, contextAfter }] }`. `score` cosine similarity'dir; yalnız gösterilir, sıralamada kullanılmaz; listeyi sıralayan `fusedScore`'dur, ve iki rank alıntıyı aramanın hangi yarısının bulduğunu söyler (bulmayan yarı için `null`). `belowFloor`, bir ajana *iyi eşleşme yok* denip denmeyeceğidir — hit'ler her iki durumda da geri gelir, böylece pano nelerin gizlendiğini gösterebilir. `scoreFloor` kararı veren tabandır, `scoreFloorOverridden` ise bunun örneğinki değil projenin kendi tabanı olup olmadığını söyler. `limit` 1–20'dir (varsayılan 5); `source`, `path_prefix` ve `version` isteğe bağlıdır. Bu projenin sahip olmadığı bir kaynak ya da sürüm için `400 invalid_request` (mesaj sahip olduklarını adlandırır), projenin hiç parçası yoksa `409 not_indexed`, başka bir modelle gömüldülerse `409 model_mismatch` |
| `GET /api/projects/:id/export` | Projenin tamamı — belgeler, chunk'lar, kaynak ayarları — tek bir `.tar.gz` olarak (projenin bir `manager`'ının) |
| `POST /api/projects/import` | Multipart: arşiv bir dosya parçası olarak ve isteğe bağlı bir `name` alanı → neyin içe aktarıldığını anlatan bir raporla `201` (instance `admin`'inin). `DATA_DIR`, gömülü veritabanıyla ise onun veri dizini, `DATA_DIR_MIN_FREE_BYTES` artı arşiv boyutunun dört katını tutamıyorsa `507 insufficient_disk`; denetim yükleme okunmadan önce ve açılmadan önce yeniden yapılır, bu yüzden bir ret geride ne proje satırı ne dosya bırakır |
| `DELETE /api/projects/:id` | Projeyi siler → `204` (indekslerken `409`) |

### Kotalar

| Yöntem ve yol | Açıklama |
|---------------|-------------|
| `PATCH /api/projects/:id/quotas` | `{ maxDocuments?, maxChunks?, maxUploadBytes? }`; her biri `0` ya da daha büyük bir tam sayı ya da `null`: bir sayı projenin kendi limitini koyar (`0` onu instance varsayılanından muaf tutar), `null` limiti instance'ın `PROJECT_MAX_DOCUMENTS`, `PROJECT_MAX_CHUNKS` ya da `PROJECT_MAX_UPLOAD_BYTES` değerine geri verir, yazılmayan anahtar olduğu gibi kalır → yukarıdaki biçimde `{ quotas }`. Bilinmeyen bir anahtar ya da boş gövde `400`, bilinmeyen proje `404` yanıtlar. Bir proje `manager`'ının işidir; bunu yalnızca instance `admin`'i, `root` ve `ADMIN_TOKEN` taşır, yani bir proje üyesi hiçbir zaman limit koyamaz. Audit'e yazılır |

`maxUploadBytes`'ı aşırtacak bir upload, limiti, kullanılan baytı ve istenen baytı taşıyan `413 quota_exceeded` yanıtlar; belge ya da chunk kotasını aşan bir indeksleme çalışması ise bir isteğe yanıt vermek yerine `quota_exceeded` hata koduyla biter. Saklanan upload baytı ölçülemezse upload, geçirilmek yerine `503 quota_usage_unavailable` ile reddedilir.

### Secret'lar ve kişisel veriler

| Yöntem ve yol | Açıklama |
|---------------|-------------|
| `GET /api/projects/:id/findings` | Projenin PII taramasının bulguları, bir `editor` ve üstü için (`viewer` `403` alır): belge yolu, kural, konum, maskelenmiş bir önizleme ve kısa bir grup id'si. Hiçbir zaman bir değer döndürmez. Bkz. [Yapılandırma](/tr/docs/configuration/#belgeleri-secretlar-ve-kişisel-numaralar-için-taramak) |

### Sorgu logu ve skor tabanı

Ajanların bir projeye ne sorduğu ve onlara *iyi eşleşme yok* denmesine karar veren alaka tabanı. Okumak bir `viewer`'ın işidir; ikisini değiştirmek bir proje `manager`'ınındır.

| Yöntem ve yol | Açıklama |
|---------------|----------|
| `GET /api/projects/:id/queries/summary?days=…&actor=…&model=…&generation=…&floor=…&limit=…` | Bir penceredeki loglanmış aramaların özeti. `days` 1–90'dır (varsayılan 7); `actor` `mcp` (varsayılan), `dashboard` ya da `all`'dır; `limit` 1–100'dür (varsayılan 20). `model` ve `generation` birlikte verilir ya da hiç verilmez ve tek bir retrieval yapılandırmasını adlandırır; `floor` (0 ile 1 arası bir sayı ya da `none`) adlandırılmış bir yapılandırmayı daraltır ve ikisini de gerektirir. Cevap ayrıca `reportedGaps` taşır: penceredeki `report_gap` raporları, soruya göre gruplanmış |
| `GET /api/projects/:id/queries/export?…` | Tekrarlanan soruları `application/x-ndjson` olarak (bir `….jsonl` dosya indirmesi), değerlendirme harness'i için verir. Aynı filtreleri alır; `limit` 1–500'dür (varsayılan 100). Bir `viewer`'ın işidir, çünkü özetle aynı logu okur |
| `PATCH /api/projects/:id/query-log` | `{ "enabled": true \| false }` → `{ queryLogEnabled }`. Bu projenin ajanların sorduklarını kaydedip kaydetmeyeceği; sonraki aramada etkili olur ve hiçbir şey silmez |
| `DELETE /api/projects/:id/query-log` | Bu projenin loglanmış sorgularını siler → `{ deleted, reportedGapsDeleted, dumpsUnaffected: true }` — `report_gap` raporları sorgularla birlikte gider; alınmış bir dump satırları hâlâ tutar |
| `GET /api/projects/:id/score-floor/preview?floor=…&days=…&actor=…` | Bir taban ayarlanmadan önce neye mal olacağı: penceredeki aramalardan, önerilen tabanın yanıtlayacağı ama mevcut tabanın reddettiği kaçı, ve tersi, her birinden birkaç örnekle. `floor`, 0 ile 1 arası bir sayı ya da `instance`'tır; her sayı bir üst sınırdır (`atMost: true`) |
| `PATCH /api/projects/:id/score-floor` | `{ "floor": 0.5 }` ya da `{ "floor": null }` → `{ scoreFloor, instanceScoreFloor, effectiveScoreFloor }`. `null` projeyi örneğin `SEARCH_SCORE_FLOOR` değerine geri verir; sonraki arama yeni değeri okur |

Bir taban tahmin edilmek zorunda değildir. Sunucu projeyi tabanı kapalıyken ölçüp bir taban önerebilir:

| Yöntem ve yol | Açıklama |
|---------------|-------------|
| `POST /api/projects/:id/score-floor/suggestions` | Bir proje `manager`'ının işidir. Canlı indeksi, her biri chunk'larından birinden alınmış bir cümlenin son sekiz kelimesi olan en çok 100 probe ile ölçer ve bunların hiçbirini reddetmeyen en yüksek tabanı saklar → `201 { suggestion }` (`id`, `createdAt`, `trigger`, `embeddingModel`, `liveGeneration`, `suggestedFloor`, `previousFloor`, `basis`, `appliedAt`). 20'den az probe çıkarılabiliyorsa ya da hiçbir taban uymuyorsa `200 { suggestion: null, reason: "insufficient_data" \| "no_fit" }`. Proje indekslenmemişse, başka bir modelle indekslenmişse, bir ölçümü zaten çalışıyor ya da kuyruktaysa ya da başka iki proje zaten ölçülüyorsa `409`. Projenin tabanını hiçbir zaman değiştirmez. Sunucu, model değişikliğinden kaynaklanan bir re-index'ten sonra da bir öneri üretir (`trigger: model_change`). Audit'e yazılır |
| `GET /api/projects/:id/score-floor/suggestions` | Bir `viewer`'ın işidir. `{ current: { project, embeddingModel, liveGeneration }, suggestions }`, en yeniden en eskiye; en yeni on tanesi tutulur |
| `POST /api/projects/:id/score-floor/suggestions/:suggestionId/apply` | Bir proje `manager`'ının işidir. Projenin tabanını önerininkine ayarlar → `{ suggestion, scoreFloor, instanceScoreFloor, effectiveScoreFloor }`. Zaten uygulanmışsa ya da projenin modeli veya canlı generation'ı ölçülenden farklıysa `409`; bilinmeyen öneri için `404`. Audit'e yazılır |

Bir probe, bulması gereken metnin bir parçasıdır; bu yüzden genellikle gerçek bir sorudan yüksek skor alır: öneriyi bir üst sınır olarak görün ve uygulamadan önce `score-floor/preview` ile iki yönde de sınayın.

```bash
# create and index
curl -s -X POST $API/projects -H "Authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' \
  -d '{"name":"handbook","rootPath":"/docs/handbook","index":true}' | jq

# re-index everything, every night
for id in $(curl -s $API/projects -H "Authorization: Bearer $TOKEN" | jq -r '.[].id'); do
  curl -s -X POST "$API/projects/$id/reindex" -H "Authorization: Bearer $TOKEN" > /dev/null
done
```

### Golden question'lar

Bir projenin kendi değerlendirme kümesi: soruların yanında onları yanıtlaması gereken dosya (isteğe bağlı olarak başlık). Okumak bir `viewer`'ın, kümeyi değiştirmek bir `editor`'ın işidir. Reddetme soruları burada tutulmaz.

| Yöntem ve yol | Açıklama |
|---------------|-------------|
| `GET /api/projects/:id/golden-questions` | Küme `key`'e göre sıralı → `{ questions: [{ id, key, lang, query, expectFile, expectHeading, tags, note, createdAt, updatedAt }] }`. `key` sorunun adıdır (`^[a-z0-9][a-z0-9-]*$`, en çok 100 karakter, projede benzersiz); `expectHeading` ve `note` yoksa `null`'dır |
| `POST /api/projects/:id/golden-questions` | `{ key, lang: "en" \| "tr", query, expectFile, expectHeading?, tags?, note? }` → görünümle `201`. `query` 1–4000 karakterdir; `expectFile`, öneki kaynak adı olan bir belge yoludur (`<source>/<path>`). Bilinmeyen alanlar reddedilir. Projede zaten olan bir key için `409`, diğer durumlarda `400 validation_failed`, proje 1000 soruyu bulunca `400`. Audit'e yazılır |
| `PUT /api/projects/:id/golden-questions` | `{ questions: [...] }` (her biri `POST`'taki gibi, en çok 1000) kümenin tamamını tek bir transaction'da değiştirir → `{ questions }`. Yinelenen bir key ya da geçersiz bir satır hiçbir şeyi değiştirmez (`400`); `[]` kümeyi boşaltır. Audit'e yazılır |
| `GET /api/projects/:id/golden-questions/export` | Küme `application/x-ndjson` olarak, `golden.jsonl` adıyla indirilir; depodaki `eval/golden.jsonl`'nin biçiminde her satırda bir soru |
| `GET /api/projects/:id/golden-questions/:questionId` | Tek bir soru; bilinmeyen proje ya da soru için `404` |
| `PATCH /api/projects/:id/golden-questions/:questionId` | `lang`, `query`, `expectFile`, `expectHeading` (`null` temizler), `tags`, `note` (`null` temizler) alanlarından herhangi biri → görünüm. `key` değişmez, boş gövde de olmaz (`400`). Audit'e yazılır |
| `DELETE /api/projects/:id/golden-questions/:questionId` | → `204`; bilinmeyen proje ya da soru için `404`. Audit'e yazılır. Küme projesiyle birlikte de gider |

### Golden set eval çalışmaları

Bir projenin golden question'ları (yukarıda) canlı indekse sunucunun kendisi tarafından
sorulur ve her çalışma tutulur; böylece hiçbir şey çalıştırmadan bir gerileme görünür. Bir çalışmayı bir swap (bir
force ya da model değişikliği re-index'i), chunk yazan, dosya kaldıran ya da doküman değişikliği kaydeden artımlı bir
çalışma, kümedeki bir değişiklik (başka biri gelmeden 60 saniye sonra) ve bir manager başlatır. Golden question'ı
olmayan bir proje hiçbir şey yapmaz ve hiçbir şey kaydetmez.

| Yöntem ve yol | Açıklama |
|---------------|----------|
| `GET /api/projects/:id/eval-runs?limit=` | Bir `viewer`'ın işi. Çalışmalar, en yenisi önce (`limit` 1 ile 100, varsayılan 30), soru başına sıra olmadan |
| `GET /api/projects/:id/eval-runs/:runId` | Bir `viewer`'ın işi. Tek bir çalışma, `results` ile: sorulan her soru için `{ key, fp, rank }` (doğru dosyanın on kayıtlık bir sayfadaki 0 tabanlı sırası; yani `rank: 4` beşinci sıradır; yoksa `null`). Soru metni bir çalışmada asla bulunmaz |
| `POST /api/projects/:id/eval-runs` | Bir `manager`'ın işi, audit'lenir. Şimdi bir çalışma başlatır → `202 { runId }`; çalışma arka planda sürer ve yukarıdaki iki rotadan geri okunur. Satır garanti değildir: çalışırken silinen bir proje, bir kapanma ya da başarısız bir yazma `runId`'yi sonsuza dek yazılmamış bırakır, bu yüzden bir limitle yoklayın. İstek kabul edildikten sonra boşaltılan bir golden set bir `error` çalışması kaydeder. Bu projenin zaten süren ya da bekleyen bir çalışması varsa, sunucu zaten bir tane çalıştırıyorsa (örnek genelinde bir seferde bir tane) ya da projenin golden question'ı yoksa `409` |

Bir çalışma `trigger` (`index_rebuild`, `index_incremental`, `golden_set`, `manual`), `status` (`ok` ya da `error`;
`error` nedenini söyler ve rakam taşımaz), `generation`, `embeddingModel`, `questionCount`, `scoredCount`, `recall5`,
`mrr`, `regressed`, `comparedTo` ve üç soru anahtarı listesi taşır: `lostKeys`, `skippedKeys` ve `newlySkippedKeys`.

- **`npm run eval -- --project`'in puanladığı gibi puanlanır**: taban kapalı, reranker olmadan aynı arama ve aynı
  puanlama modülü; bu yüzden iki rakam tek bir sayıdır.
- **`expectFile`'ı canlı indekste olmayan bir soru atlanır.** Paydadan çıkar ve `skippedKeys`'te listelenir;
  önceki iyi çalışmanın sorduğu bir soru ayrıca `newlySkippedKeys`'tedir; bu bir uyarıdır, gerileme değildir.
  Sorulacak hiçbir şey kalmayan bir çalışma bir `error`'dır.
- **`regressed`, projenin son `ok` çalışmasına göre en az bir soru kaybedildiğinde doğrudur**: o zaman ilk beşteydi,
  şimdi aynı metin, beklenen dosya ve başlıkla soruluyor ve artık ilk beşte değil. Sayım brüttür, bu yüzden başka bir
  yerde kazanılan bir soru kaybedileni silmez. Sonradan düzenlenmiş bir soru karşılaştırılmaz. İlk çalışmanın
  karşılaştırılacağı bir şey yoktur.
- **Çalışma sırasında değişen bir indeks** (bir swap) çalışmayı bir `error` yapar; swap kendi çalışmasını zaten kuyruğa almıştır.
- Proje başına son 100 çalışma tutulur ve çalışmalar bir proje export'unun parçası değildir.

### Bir job'u izlemek

`GET /api/projects`, canlı bir çalışması olan her proje için bir `job` içerir:

```json
{ "phase": "embedding", "filesTotal": 84, "filesDone": 31, "filesSkipped": 22,
  "filesRemoved": 0, "chunksDone": 96,
  "sources": [{ "name": "handbook", "type": "local", "status": "synced" }],
  "queue": null }
```

`phase`, `queued`, `syncing`, `scanning`, `embedding`, `finalizing`, `done`, `error`'dan biridir.
Kuyruktaki bir job `queue` taşır: `{ position, aheadProjectName }` — kuyruktaki yeri ve önünde çalışan projenin adı (ad bilinmiyorsa `null`). Kuyrukta olmayan bir job için `queue` `null`'dır.

## MCP erişimi

| Yöntem ve yol | Açıklama |
|---------------|-------------|
| `GET /api/projects/:id/mcp-tokens` | Projenin canlı tokenları: `id`, `name`, `prefix`, `createdAt`, `lastUsedAt`, `expiresAt` (süresiz token için `null`). Secret'ın kendisi asla döndürülmez. Süresi dolmuş bir token iptal edilene kadar listede kalır |
| `POST /api/projects/:id/mcp-tokens` | `{ "name": "claude-code", "expiresInDays": 90 }` → `201 { token, secret }`. `expiresInDays` `30`, `90`, `365` ya da `null`'dır (varsayılan — süresiz). **`secret` token'ın okunabilir olduğu tek andır** |
| `DELETE /api/projects/:id/mcp-tokens/:tokenId` | İptal eder → `204`, projenin açık MCP oturumlarını kapatır |
| `PATCH /api/projects/:id/mcp-tokens/:tokenId` | `{ allowedCidrs: string[] \| null }` → token'ın görünümü, secret asla. Canlı bir statik token'ın ağ izin listesini değiştirir; `null` ya da `[]` sınırı kaldırır. Token'ın sonraki MCP isteğinde etkili olur. `POST` için olduğu gibi `400`; bilinmeyen, iptal edilmiş ya da OAuth ile verilmiş bir token ya da başka bir projeninki için `404`. Route şablonu altında audit'e yazılır ve audit ayrıntısı listeyi hiçbir zaman içermez. Bir `editor`'ın işidir |
| `PATCH /api/projects/:id/mcp-auth` | `{ "mode": "open" \| "token" \| "account" }` → `{ "mcpAuth" }`. `open`'dan uzaklaşmak da projenin açık oturumlarını kapatır. `account`, çağıranın `/mcp/*` üzerinde OAuth 2.1 üzerinden projenin bir üyesi olmasını gerektirir; bu modda statik bir `ctxm_…` token reddedilir |

`GET /api/projects`, geçerli modu `mcpAuth` olarak bildirir. Bir endpoint'i kapatmak ve bir token
üretmek:

```bash
curl -s -X PATCH $API/projects/$P/mcp-auth -H "Authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' -d '{"mode":"token"}' | jq

curl -s -X POST $API/projects/$P/mcp-tokens -H "Authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' -d '{"name":"claude-code"}' | jq -r .secret
```

İstemci sonra bu secret'ı `/mcp/<project-name>` üzerinde `Authorization: Bearer ctxm_…` olarak gönderir
— bkz. [Yapay Zekâ İstemcilerini Bağlamak](/tr/docs/connecting-ai-clients/).

Bir statik token, projenin bazı kaynaklarına da bağlanabilir (token scope, 0.6.0'da yeni; bkz.
[Yapay Zekâ İstemcilerini Bağlamak](/tr/docs/connecting-ai-clients/#bir-tokenı-bazı-kaynaklarla-sınırlamak)).
`POST /api/projects/:id/mcp-tokens` `sources` alır, kaynak **adlarından** oluşan bir liste (yok ya da `null`: projenin tamamı);
`PATCH /api/projects/:id/mcp-tokens/:tokenId/sources` (`editor`), kapsamı değiştirmek için `{ "sources": ["handbook"] }`, kaldırmak
için `{ "sources": null }` alır. Reddedilenlerin kodu `error`'da taşınır: `[]` için `400 empty_scope`, projede olmayan bir ad için
`400 unknown_source`, bir OAuth kimlik bilgisi için `409 not_static`. `GET /api/projects/:id/mcp-tokens` her token'da `sources`
(`string[]` ya da `null`) ve `scopeEmpty` döndürür; iki yazma da adlarla audit edilir.

## Kaynaklar

| Yöntem ve yol | Açıklama |
|---------------|-------------|
| `GET /api/projects/:id/sources` | Projenin kaynakları. Bir kaynağın kimlik bilgisi (`secret`) asla döndürülmez — yalnızca `hasSecret`. `git`, `notion` ya da `confluence` kaynağının webhook secret'ı bir `editor` ve üstüne `webhookSecret` alanında döner, bir `viewer`'a `null` olarak; `hasWebhookSecret` bir tane ayarlı olup olmadığını söyler |
| `POST /api/projects/:id/sources` `{ type, name, label?, flavor?, config?, secret?, syncIntervalMinutes?, index? }` | Bir kaynak ekler. `type`, `local`, `git`, `upload`, `notion`, `confluence`, `web`, `s3`, `gdrive` ya da `github`'dır; `config` türe özeldir — aşağıdaki tabloya bakın. `secret`, yalnızca bir kimlik bilgisi kullanan türlerce alınır (`git`, `notion`, `confluence`, `s3`, `gdrive`, `github`; `s3` için `{"v":1,"accessKeyId":"…","secretAccessKey":"…"}` JSON dizesi, `gdrive` için servis hesabının Google'ın verdiği haliyle anahtar dosyası, `github` için isteğe bağlı olan düz token); `local`, `upload` ya da `web` üzerinde türü adlandıran bir `400 invalid_request` yanıtlar, ve `secret: null` ("secret yok" anlamında) her türde kabul edilir. `syncIntervalMinutes`, 5–43200 ya da `null`'dır; atlanırsa örnek varsayılanı alınır |
| `PATCH /api/projects/:id/sources/:sid` | Etiketi, içerik türünü (`flavor`), config'i ya da token'ı değiştirir (`"secret": null` onu kaldırır), ayrıca `syncIntervalMinutes` (`null` zamanlamayı kapatır) ve `webhookMinIntervalMinutes` (0–43200; `null` kaynağı örneğin `WEBHOOK_MIN_INTERVAL_MINUTES` değerine döndürür). Tür ve ad değiştirilemez. Webhook asgarisi yalnızca API'de bulunan bir ayardır; pano onu göstermez |
| `DELETE /api/projects/:id/sources/:sid` | Onu, dokümanlarını ve dosyalarını kaldırır (indekslerken `409`) |
| `POST /api/projects/:id/sources/notion/oauth` | Bir API token'ı rotası değildir: **Connect with Notion** akışını başlatır ve bir proje editor'ünün dashboard oturumunu ister. `GET /api/sources/notion/oauth` akışın yapılandırılıp yapılandırılmadığını söyler; `GET /api/sources/notion/oauth/callback` Notion'ın tarayıcıyı geri gönderdiği yerdir — bkz. [Notion](/tr/docs/notion/#connect-with-notion-oauth) |
| `POST /api/projects/:id/sources/:sid/sync` | Bir çalışmayı kuyruğa alır → `202 { job }` |
| `POST /api/projects/:id/sources/:sid/test` | Bağlantı denetimi → `{ ok, message }` |
| `POST /api/projects/:id/sources/:sid/webhook-verification` | Yalnızca Notion: kaynağın webhook'unun Notion'ın gönderdiği `verification_token`'ı kabul ettiği, 15 dakikalık ve tek seferlik pencereyi açar → `202 { webhookVerificationExpiresAt }`. Notion kaynağı olmayan bir kaynakta `400` |
| `POST /api/projects/:id/sources/:sid/webhook-secret` | Yeni bir webhook secret'ı üretir: bir git kaynağında onu rotate eder, ve bir Confluence kaynağında webhook'u açar (ya da yeniden üretir) — bkz. [Push Webhook'ları](/tr/docs/push-webhooks/#confluence-data-center) |
| `DELETE /api/projects/:id/sources/:sid/webhook-secret` | Yalnızca Confluence: webhook'u kapatır. Teslimatlar ardından yeniden `not_enabled` ile reddedilir |

0.6.0'dan beri, saklanan bir kimlik bilgisi varken bir kaynağın adresinin host'unu taşıyan bir düzenleme — bir Confluence
`baseUrl`'i, bir git `url`'si, bir S3 `endpoint`'i, bir GitHub `apiBaseUrl`'i — aynı istek kimlik bilgisini yeniden vermedikçe (yeni
değer ya da kaldırmak için `"secret": null`) `400 invalid_request` ile reddedilir. `{` ile başlayan bir Notion `secret`'ı da aynı
şekilde reddedilir, çünkü bu bir OAuth bağlantısının biçimidir ve onu yalnızca dashboard akışı oluşturur.

Bir git kaynağı eklemek:

```bash
curl -s -X POST $API/projects/$PROJECT_ID/sources \
  -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{
        "type": "git",
        "name": "api-docs",
        "label": "API reference",
        "config": { "url": "https://github.com/org/repo.git", "branch": "main", "subdir": "docs" },
        "secret": "ghp_…",
        "index": true
      }' | jq
```

Türe göre `config`:

| Tür | Anahtarlar |
|------|------|
| her tür | `language` (metin arama yapılandırması), `version` (`version=` arama filtresinin eşleştirdiği değer) |
| `local` | `path`, `extensions` |
| `git` | `url`, `branch`, `subdir`, `username`, `provider`, `extensions` |
| `upload` | `extensions` |
| `notion` | `rootIds`, `extensions` |
| `confluence` | `baseUrl` (zorunlu), `deployment` (`cloud` \| `datacenter`), `email` (yalnızca Cloud), `spaceKeys`, `extensions` — bkz. [Confluence](/tr/docs/confluence/) |
| `web` | `entryUrl`, `entryKind` (`auto` \| `sitemap` \| `llms` \| `crawl`, varsayılan `auto`), `extensions` — yalnızca herkese açık sayfalar, kimlik bilgisi yok |
| `s3` | `bucket` (zorunlu), `endpoint` (AWS için boş), `region`, `prefix`, `pathStyle`, `extensions` — bkz. [Belge Kaynakları](/tr/docs/document-sources/#s3-bucketları) |
| `gdrive` | `folderIds` (zorunlu, 1 ile 50), `extensions`; `serviceAccountEmail`'i sunucu yazar — bkz. [Belge Kaynakları](/tr/docs/document-sources/#google-drive) |
| `github` | `owner` ve `repo` (zorunlu), `apiBaseUrl`, `includeClosed`, `includeDiscussions` (token ister, yoksa `400 invalid_request`), `includeBots`, `extensions` — bkz. [Belge Kaynakları](/tr/docs/document-sources/#github-issueları-ve-discussions) |

## Yüklemeler

| Yöntem ve yol | Açıklama |
|---------------|-------------|
| `POST /api/projects/:id/sources/:sid/uploads` | Bir oturum açar → `{ session }`. `DATA_DIR`'in boş alanı `DATA_DIR_MIN_FREE_BYTES`'in altındaysa `507 insufficient_disk` |
| `POST /api/projects/:id/sources/:sid/uploads/:session/files` | `multipart/form-data`; her parçanın `filename`'i kaynak içindeki yoldur. Arşivler sunucu tarafında açılır. Disk denetimi her istekte yapılır, bu yüzden bir klasör yüklemesi ortasında `507 insufficient_disk` alabilir; reddedilen istek hiçbir şey yazmaz |
| `POST /api/projects/:id/sources/:sid/uploads/:session/commit?mode=add\|replace` | Bekletilen dosyaları içeri taşır ve bir çalışmayı kuyruğa alır → `202` |
| `DELETE /api/projects/:id/sources/:sid/uploads/:session` | Bekletilen yüklemeyi atar |
| `GET /api/projects/:id/sources/:sid/files` | Bir yükleme kaynağının dosyalarını listeler |
| `DELETE /api/projects/:id/sources/:sid/files?path=…` | Birini siler ve yeniden indeksler |

```bash
SESSION=$(curl -s -X POST $API/projects/$P/sources/$S/uploads -H "Authorization: Bearer $TOKEN" | jq -r .session)
curl -s -X POST "$API/projects/$P/sources/$S/uploads/$SESSION/files" \
     -H "Authorization: Bearer $TOKEN" -F 'file=@guide.md;filename=guides/guide.md'
curl -s -X POST "$API/projects/$P/sources/$S/uploads/$SESSION/commit?mode=add" \
     -H "Authorization: Bearer $TOKEN"
```

## Webhook'lar

| Yöntem ve yol | Açıklama |
|---------------|-------------|
| `POST /api/webhooks/git/:sourceId` | Bir git kaynağı için push webhook'u, bir hesap ya da `ADMIN_TOKEN` **değil**, kaynak başına secret ile kimliklendirilir |
| `POST /api/webhooks/confluence/:sourceId` | Confluence Data Center webhook'u, kaynak başına secret üzerinden `X-Hub-Signature` ile imzalanır. Kaynağın webhook'u açılana kadar `401 not_enabled` |
| `POST /api/webhooks/notion/:sourceId` | Notion webhook'u. İmzasız bir `verification_token` yalnızca bir doğrulama penceresi açıkken saklanır (yukarıdaki `webhook-verification`'a bakın); ondan sonra her teslimat `X-Notion-Signature` ile imzalanır. Aksi halde `401 verification_not_open`, `invalid_signature` ya da `not_verified` |

Bkz. [Push Webhook'ları](/tr/docs/push-webhooks/).

## Metrikler

```bash
curl -s http://localhost:3444/metrics -H "Authorization: Bearer $METRICS_TOKEN"
```

`GET /metrics`, kendi kimlik bilgisi kurallarına sahip ayrı, Prometheus biçimli bir endpoint'tir
(`text/plain; version=0.0.4`) — `/api/*`'ın **bir parçası değildir** ve varsayılan olarak **herkese
açık değildir**. Şeride göre indeksleme kuyruğunu, birinin çalışıp çalışmadığını, son indeksleme
çalışmasını ve işe yarayıp yaramadığını, aktöre göre aramaları, veritabanı bağlantı havuzunu ve
veritabanının kendisinin yanıt verip vermediğini bildirir.

Bunların ötesinde `/metrics`, tek bir sürecin ne zaman yetmez olduğunu söyleyenleri taşır:
her MCP ve pano araması için `contextator_search_request_duration_seconds{indexing}` ile
`contextator_search_duration_seconds{phase,indexing}`, indeksleme için
`contextator_embedding_batch_duration_seconds` ve `contextator_embedding_batch_size`, kuyruk için
`contextator_index_run_wait_seconds{lane}`. `contextator_mcp_requests_total{method,tool,era}` MCP mesajlarını protokol
dönemine göre sayar (sunucunun tanımadığı bir araç adı `other` olarak sayılır) ve
`contextator_mcp_tool_duration_seconds{tool}` her araç çağrısını süreler. `contextator_mcp_gap_reports_total{outcome}`
`report_gap` çağrılarını sonuca göre sayar (`accepted`, `limited`, `disabled` ya da `failed`); golden set eval
çalışmaları etiketsiz olarak `contextator_eval_runs_total`, `contextator_eval_run_errors_total` ve
`contextator_eval_regressions_total` ile sayılır; bir projenin skoru asla bir metrik değildir. Hiçbir etiket bir proje, bir belge ya da bir
sorgu taşımaz. Contextator bilerek tek süreç ve tek indeksleyici kuyruğuyla çalışır; bunu, bir hafta boyunca süren
biçimde, indeksleme sırasındaki arama p95'i 1 sn'nin üzerinde ve boştakinin iki katıysa, etkileşimli kuyruk bekleme
p95'i 5 dakikayı aşıyorsa ya da etkileşimli backlog 15 dakika boyunca sıfırın üzerinde kalıyorsa yeniden gözden geçirin.

Açık bir oturumu, `ADMIN_TOKEN`'ı, bir `METRICS_TOKEN` bearer'ını, ya da
`METRICS_PUBLIC=1` iken hiçbir kimlik bilgisini kabul eder — bkz.
[Yapılandırma](/tr/docs/configuration/#gözlemlenebilirlik). Veritabanı çökükken bile `200` yanıtlar,
`contextator_db_up 0` ile ve veritabanı gerektiren satırlar dışarıda bırakılarak, bu yüzden bir scrape
boşluğu bir kesintinin bildirilme yolu asla olmaz. **Veritabanı çökükken yalnızca veritabanı okuması
gerektirmeyen üç kimlik bilgisi çalışmaya devam eder** — `ADMIN_TOKEN`, `METRICS_TOKEN`,
`METRICS_PUBLIC` — bir oturum çerezi bir veritabanı satırıdır ve doğrulanamaz, bu yüzden bir tane
sunan bir tarayıcı bir kesinti sırasında `500` yerine `401` alır. `METRICS_TOKEN`'ı bir kesinti
sırasında değil öncesinde yapılandırmanın nedeni budur.

## Audit log

`/api/audit`, `root` ya da `admin` gerektirir — log örnek geneli olduğu için, bir proje üyeliği kime
root rolü verildiğini okumak için bir dayanak değildir.

| Yöntem ve yol | Açıklama |
|---------------|-------------|
| `GET /api/audit?actor&actorUser&action&project&from&to&limit&cursor` | Audit log, en yeniden en eskiye. Her filtre SQL'de uygulanır: `actor`, o anda kaydedildiği haliyle etikettir; `actorUser`, işlemi yapan hesaba karşı **tam olarak** eşleştirilen bir hesap id'sidir — o hesabın kendi oturumlarını **ve** sahip olduğu her API token'ını döndürür, tokenlar nasıl adlandırılmış olursa olsun; bir UUID olmayan bir değer `400 validation_failed` yanıtlar. `action`, `<METHOD> <rota şablonu>`'dur; `project`, bir proje id'si ya da `none`'dır. `from`/`to` **UTC günleridir**, ve `to` adlandırılan günü dahil eder. `limit` 1–200'dür (varsayılan 50). `cursor`, önceki sayfanın `nextCursor`'ıdır — kodlanmış bir an değil her zaman bir **satır id'si**, bu yüzden aynı milisaniye içindeki iki olay bir sayfa sınırında birbirini asla kaybedemez; hiçbir satırı adlandırmayan bir cursor `400` yanıtlar. `{ events, nextCursor, filters, retentionDays }` döner — son sayfada `nextCursor` `null`'dır, ve `filters` (farklı aktörler, eylemler, projeler, ve olayları olan hesaplar, seçiciler için) yalnızca ilk sayfada geri gelir |

```bash
curl -s "$API/audit?action=DELETE%20/api/projects/:id&limit=50" \
  -H "Authorization: Bearer $TOKEN" | jq
```

### Nasıl yazılır

Yukarıdaki durum değiştiren her istek, `audit_events`'te isteği yapan hesabı adlandıran bir satır
bırakır — ne yapıldığı, hangi projeye, kaynağa, token'a, üyeliğe ya da hesaba, ve ne zaman. Bir oturum
açma ve ilk hesabın oluşturulması da kaydedilir, ve bir kişinin bir konnektöre bir projeye kalıcı okuma
erişimi verdiği `POST /oauth/authorize` de öyle.

Her handler tarafından değil **politika katmanı** tarafından yazılır, bu yüzden kapsanmadan
eklenebilecek bir rota yoktur — ve katılmama seçeneği olan da yoktur. İstisnalar **sekiz** tanedir — bir
kaynağın test rotası, bir upload-session'ın dosya-baytları rotası, üç webhook teslimatı (git, Notion, Confluence) ve üç OAuth
OAuth protokol rotası (`register`, `token`, `revoke`) — her biri `src/auth/policy.ts` içinde kendi
gerekçesiyle adlandırılmıştır.

Bir şey *oluşturan* bir rota kendi yolunda hiçbir şey adlandırmaz, bu yüzden yeni nesnenin id'si yanıttan
geri okunur, aynı dosyadaki sabit yollardan oluşan bir tablo üzerinden, ve yalnızca orada bulunan değer
bir UUID olduğunda tutulur — "bunu kim üretti" bu yüzden log'un yanıtladığı bir sorudur, ve aynı id'yi
adlandıran iptalle hizalanır.

### Neyi tutmaz

Satırlar hiçbir kullanıcı içeriği taşımaz: bir soru, bir belge ve bir alıntı bu tablonun bir sütununa
asla ulaşmaz. Herhangi bir eylemin kaydedebileceği tek gövde alanları aynı politika dosyasında
adlandırılır, her biri kapalı bir değer kümesiyle sınırlıdır (`mode`, `open`/`token`/`account`'tan
biridir, ve benzeri). Bu, onu sorgu günlüğünden farklı bir kayıt tutar — o, ajanların ne sorduğunu
tutar, kendi saklama süresiyle yönetilir ve kendi proje başına anahtarına sahiptir — ikisi bilerek tek
bir tablo değildir.

Bunun ötesinde iki şey bilerek kaydedilmez. **Reddedilen istekler** — bir reddediş, izin matrisinin
çalışmasıdır, ve her yoklamayı loglamak tabloyu bir tarama günlüğüne dönüştürürdü; tek istisna bir
kişinin `/oauth/authorize`'da bir konnektörü reddetmesidir, ki bu matrisin karar vermesi değil birinin
karar vermesidir. Ve **bir şeyi değiştiren ve ardından `5xx` yanıtlayan bir eylem**: satır yalnızca
400'ün altındaki bir yanıt için yazılır, bu yüzden commit edip sonra başarısız olan bir handler hiçbir
şey bırakmaz. Bu API'de şu anda bu şekilde biçimlenmiş hiçbir handler yok, ve `SECURITY.md` bunu olduğu
sınır olarak adlandırır.

### Okumak

`GET /api/audit` ve panonun **Audit log** paneli (hesap menüsü, Users'ın yanında) ikisi de yalnızca
root/admin'dir. Her satır, saklandığı sütunlar yerine bir cümle olarak render edilir ("dana deleted a source from
handbook" — "dana handbook'tan bir kaynak sildi"). "Kim" iki seçicidir: **Actor**, kaydedildiği haliyle etikettir, ve **Account**, hesap
id'sidir — bu, o hesabın kendi eylemlerini sahip olduğu her API token'ınınkilerle birlikte bulur, çünkü
bir token'ın etiketi yalnızca adı ve sahibidir ve onları kendi başına toplayamaz. Bir proje o zamandan
beri silinmişse satırları hâlâ vardır: `project_id` bir foreign key taşımaz, bu yüzden panel *adını*
arayamaz, ve bunu boş bırakmak yerine satırda söyler.

Panelin filtrelediği iki sütun — `actor_label`, çünkü hesaptan daha uzun ömürlüdür, ve `action` —
`0011` migration'ı ile indekslenir. 200.004 satırda, seçici bir actor filtresi indekssiz 9,7 ms'ye karşı
0,07 ms'de çalışır, bir sayfa çevirme 3 ms'dir, ve ilk sayfa 19–52 ms'dir çünkü hiçbir indeksin
yardım edemeyeceği üç `DISTINCT` taramasıyla filtre açılır menülerini de doldurur — filtre değişimi
başına bir kez ödenir, hiçbir zaman sayfa çevirme başına değil.

Log **tamper-evident değildir** — veritabanı erişimi olan herkes bir satırı kaldırabilir ve burada
hiçbir şey bunu göstermez (`SECURITY.md`) — ve `AUDIT_LOG_RETENTION_DAYS`'ten daha eski satırlar,
süresi dolmuş oturumlarla aynı çeyrek saatlik zamanlayıcıda süpürülür.

## Hatalar

| Durum | Anlamı |
|--------|---------|
| `400` | `validation_failed` — gövde ya da sorgu şemasına uymadı; `issues` her sorunu listeler. Ya da `invalid_request` — bozuk bir yol, eksik `SECRET_KEY`, politikanın reddettiği bir parola; `message` açıklar |
| `401` | Kimlik bilgisi yok, ya da yanlış. `setup_required`, bu örneğin henüz hiç hesabı olmadığı anlamına gelir |
| `403` | Oturum açık, ama izin yok: `forbidden`, `csrf_blocked`, `password_change_required`, `account_disabled`, `token_has_no_account`, `invalid_setup_code`, `root_local_only` |
| `404` | Bilinmeyen proje, kaynak ya da oturum — **ve** bu hesabın erişimi olmadığı her proje |
| `409` | Yinelenen ad, proje indeksleniyor, kurulum zaten tamamlandı, son root hesabı, ya da kendi kodunu taşıyan bir ret (`root_requires_unlink`, `not_indexed`, `model_mismatch` ve reddedilen bir proje import'unun kodları). `DELETE /api/auth/oidc/link`, hesabın yerel bir parolası olmadığında bunun yerine `409 last_sign_in_method` yanıtlar — bağlantıyı kesmek onu oturum açacak bir yol bırakmazdı, bu yüzden bir admin bir tane ayarlayana kadar hiçbir şey kaldırılmaz |
| diğer `4xx` | `request_error` — framework'ün kendi reddi, rotaya özgü denetimlerden önce: bozuk JSON, boyut sınırını aşan gövde, desteklenmeyen content type. `message` Fastify'ındır |
| `429` | Çok fazla oturum açma denemesi. `Retry-After` ve `retryAfterSec` ne kadar süreceğini söyler |
| `507` | `insufficient_disk` — zorlanmış bir yeniden indeksleme, bir import ya da bir yükleme (oturum açma veya dosya gönderme), disk onu barındıramadığı için reddedildi; hiçbir şey yazılmadı |
| `500` | İç hata — cevap yalnızca bunu söyler; ayrıntılar loglardadır |

Hatalar JSON'dur: `{ "error": "conflict", "message": "…" }`; `validation_failed` üzerinde `issues`, `429` üzerinde `retryAfterSec` eklenir. Tabloda adı geçen kodlar bu sayfanın andığı kodlardır, kapalı bir liste değildir.

## Notlar

- Bir kaynağın kimlik bilgisi ve bir hesabın parolası asla döndürülmez: bir kaynak yalnızca `hasSecret`'ı bildirir, ve bir parola yalnızca bir geçici parolanın üretildiği o tek seferde gösterilir. Webhook secret'ı farklıdır — bir `editor` ve üstüne döner (bkz. Kaynaklar), çünkü bir operatörün onu göndericiye yapıştırması gerekir.
- `POST /api/projects/:id/reindex`'i sık çağırmak güvenlidir: indeksleme artımlıdır.
- Yetkilendirme, rotaları yöntemlerine ve biçimlerine göre kapsayan tek bir politika tablosundan
  sunucu tarafında kararlaştırılır, bu yüzden yeni bir endpoint var olduğu anda korunur. Panonun
  gizlediği şey kozmetiktir.
- API, panoyla ve MCP endpoint'leriyle aynı porta bağlıdır, bu yüzden birine ulaşabilen ötekilere de
  ulaşabilir ([Güvenlik](/tr/docs/security/)).
