Admin API

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:

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_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) 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": "0.2.0",
  "uptimeSec": 3610,
  "db": "up",
  "embeddings": {
    "id": "local:Xenova/multilingual-e5-small:fp32:\"query: \"+\"passage: \"",
    "provider": "local", "model": "Xenova/multilingual-e5-small",
    "dimensions": 384, "dtype": "fp32", "ready": true
  },
  "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 ayrıca modelin girdi penceresini ve CHUNK_MAX_TOKENS’ın onun içine sığıp sığmadığını taşır, 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. Bir izleyicinin izlediği alanlar her iki biçimde de vardır.

Kurulum ve oturum açma

# 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.

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.

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 ya da active anahtarına 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. Panonun kendi Account menu → API tokens sayfası tam olarak bu endpoint’lerin bir istemcisidir — orada curl’e hiç dokunmadan üretin, listeleyin ve iptal edin.

# 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.

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.

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

# 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

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.aheadProjectName taşır.

MCP erişimi

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.

Kaynaklar

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:

Yüklemeler

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

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.

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.

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 ve upload-session rotaları, üç webhook teslimatı (git, Notion, Confluence) ve üç OAuth client-registration 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

Tüm hatalar JSON’dur: { "error": "conflict", "message": "…" }.

Notlar

• Secret’lar hiçbir endpoint tarafından asla döndürülmez; bir kaynak yalnızca hasSecret’ı bildirir, ve bir parola, bir geçici parolanın üretildiği o tek sefer dışında hiç döndürülmez.
• 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).