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ı’na bakın |
Authorization: Bearer $ADMIN_TOKEN |
root izinleriyle makine erişimi |
Örneğin tamamına ihtiyaç duyan betikler, CI, cron |
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.
ADMIN_TOKENher zamanrootgibi 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, yoksaOriginveReferer’a düşer, aksi halde403 csrf_blockedyanıtlar. Bearer istekleri muaftır: hiçbir çevresel kimlik bilgisi taşımazlar, bu yüzden ikisini de göndermeyencurlve 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ı şekilde403 token_has_no_accountile reddeder. Yalnızca bir oturum çerezi taşıyan bir tarayıcı onlara ulaşabilir. - Ulaşamadığınız bir proje
403değil404yanıtlar, var olmayan bir projeyle aynı şekilde, bu yüzden id’ler yoklanamaz. Ulaşabildiğiniz ama bu şekilde kullanamayacağınız bir rota403yanı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) farklıdır: çağıranın kendi
oturumuna ihtiyaç duyar, tıpkı başka her self-servis hesap endpoint’i gibi.
Sağlık
curl -s $API/health | jq
{
"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.
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’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 |
# 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.
| 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.
# 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 |
# 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.
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:
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 |
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.
# 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 veskippedKeys’te listelenir; önceki iyi çalışmanın sorduğu bir soru ayrıcanewlySkippedKeys’tedir; bu bir uyarıdır, gerileme değildir. Sorulacak hiçbir şey kalmayan bir çalışma birerror’dır.regressed, projenin sonokç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
erroryapar; 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:
{ "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:
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.
Bir statik token, projenin bazı kaynaklarına da bağlanabilir (token scope, 0.6.0’da yeni; bkz.
Yapay Zekâ İstemcilerini Bağlamak).
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 |
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ı |
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:
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 |
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ı |
gdrive |
folderIds (zorunlu, 1 ile 50), extensions; serviceAccountEmail’i sunucu yazar — bkz. Belge Kaynakları |
github |
owner ve repo (zorunlu), apiBaseUrl, includeClosed, includeDiscussions (token ister, yoksa 400 invalid_request), includeBots, extensions — bkz. Belge Kaynakları |
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 |
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 '[email protected];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ı.
Metrikler
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. 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 |
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 — bireditorve ü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).