ServerNox — AI Coding API Dokümantasyonu

Kendi sitelerinizden (i-okul.com, quantlabs.idx.cx vb.) veya CI hatlarınızdan, ServerNox'un yönettiği bir sunucuda Claude Code / Codex oturumu programatik olarak tetikleyin. Oturum, ServerNox panelindeki "AI Coding" ile aynı altyapıyı (aynı hesap izolasyonu, aynı güvenlik profilleri) kullanır — panelden ayrı bir kimlik veya oturum gerekmez.

Kimlik doğrulama

Tüm istekler X-API-Key başlığında bir API anahtarı gerektirir.

Anahtarlar, ServerNox panelinde AI Coding → Hesaplar → Servis API anahtarları altından oluşturulur (oturum açmış bir kullanıcı olarak). Her anahtarın, isteklerde tekrarlamak zorunda kalmayacağınız isteğe bağlı varsayılan ayarları (sağlayıcı, model, düşünme gücü, hesap profili) da olabilir. Anahtar yalnızca oluşturulduğu anda gösterilir; sunucu tarafında yalnız hash'i saklanır.

Kapsam: Bir anahtar, oluşturulduğu organizasyonun tüm sunucularını hedefleyebilir; isteğe bağlı olarak oluşturulurken tek bir sunucuya sabitlenebilir (server_name) — bu durumda o anahtarla yapılan her istek yalnız o sunucuyu hedefleyebilir.

Anahtar yönetimi

En kolay yol panel arayüzü: AI Coding → Hesaplar → Servis API anahtarları. Programatik olarak yönetmek isterseniz aşağıdaki uçlar, panel oturumu (JWT, Authorization: Bearer …) ile çağrılır — dış API anahtarıyla değil.

Yöntem	Yol	Açıklama
GET	`/api/ai-coding-api/keys`	Organizasyonunuzun API anahtarlarını listeler (anahtarın kendisi değil, yalnız önek/etiket/durum/varsayılanlar)
POST	`/api/ai-coding-api/keys`	Yeni anahtar oluşturur — gövde: `{ "label", "server_name", "defaults": { "tool", "model", "reasoning_effort", "account_slug" } }`
DELETE	`/api/ai-coding-api/keys/{id}`	Anahtarı iptal eder

Kimlik doğrulama başlığı

X-API-Key: snx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Anahtar oluştur (panel oturumuyla)

curl -X POST https://app.servernox.com/api/ai-coding-api/keys \
  -H "Authorization: Bearer <panel_jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "i-okul.com entegrasyonu",
    "server_name": "İDx Server",
    "defaults": { "tool": "claude", "account_slug": "isa" }
  }'

Agent

POST https://api.servernox.com/ai-coding/v1/agent

Bir sunucuda Claude Code veya Codex oturumu başlatır, mesajı gönderir, ajan turu bitene kadar (en fazla 300 saniye) bekler ve asistanın cevabını döndürür.

İstek gövdesi parametreleri

Parametre	Tip	Zorunlu	Açıklama
`message`	string	Zorunlu	Ajana verilecek görev/istek
`project_id`	string (uuid)	Koşullu	ServerNox'ta tanımlı bir AI Coding projesinin kimliği — verilirse `cwd` projenin kök dizininden alınır
`cwd`	string	Koşullu	Mutlak çalışma dizini — `project_id` verilmediyse zorunlu
`server_name`	string	Koşullu	Hedef sunucu adı — anahtar bir sunucuya sabitlenmediyse zorunlu; sabitliyse ve farklı bir isim gönderilirse 403 döner
`provider`	string	Opsiyonel	`claude` veya `codex` — belirtilmezse anahtarın varsayılanı, o da yoksa `claude`
`model`	string	Opsiyonel	Sağlayıcının model kimliği — belirtilmezse anahtarın varsayılanı, o da yoksa CLI'nın kendi varsayılanı
`reasoning_effort`	string	Opsiyonel	Modelin desteklediği düşünme gücü (ör. `low`/`medium`/`high`) — belirtilmezse anahtarın varsayılanı
`account_slug`	string	Opsiyonel	O sunucuda bağlı birden fazla hesap varsa hangisinin kullanılacağı — belirtilmezse anahtarın varsayılanı, o da yoksa `default`
`permission_mode`	string	Opsiyonel	Sağlayıcıya özgü izin modu (panel arayüzündeki mod listesiyle aynı) — belirtilmezse anahtarın varsayılanı

Hesap gerekliliği: Hedef sunucuda seçilen sağlayıcı için account_slug ile eşleşen bir hesap oturum açmış olmalı (panelden veya "İzole profile aktar" ile). Bağlı hesap yoksa 422 ile açıklayıcı bir hata döner.

Varsayılan ayarlar: Anahtar oluştururken sağlayıcı/model/düşünme gücü/hesap profili ayarlarsanız, istek gövdesinde belirtilmeyen her alan otomatik o değeri kullanır — her seferinde tekrarlamanız gerekmez.

Yanıt (JSON)

v1 senkron bir yanıt döner — akış (SSE) yok; ajan turu bitene kadar istek açık kalır.

Temel istek — projeyle

curl -X POST https://api.servernox.com/ai-coding/v1/agent \
  -H "Content-Type: application/json" \
  -H "X-API-Key: snx_..." \
  -d '{
    "project_id": "cb0b3387-e206-4878-85f7-1e0deeebfa9b",
    "message": "README dosyasına kurulum adımlarını ekle",
    "provider": "claude"
  }'

Manuel dizin + model/effort seçimi

curl -X POST https://api.servernox.com/ai-coding/v1/agent \
  -H "Content-Type: application/json" \
  -H "X-API-Key: snx_..." \
  -d '{
    "server_name": "İDx Server",
    "cwd": "/home/isa/sites/i-okul.com",
    "message": "Yeni bir migration oluştur",
    "provider": "codex",
    "model": "gpt-5.6-terra",
    "reasoning_effort": "medium"
  }'

Varsayılan ayarlı anahtarla — kısa istek

curl -X POST https://api.servernox.com/ai-coding/v1/agent \
  -H "Content-Type: application/json" \
  -H "X-API-Key: snx_..." \
  -d '{
    "project_id": "cb0b3387-e206-4878-85f7-1e0deeebfa9b",
    "message": "Testleri çalıştır ve sonucu özetle"
  }'

Anahtar zaten tool/account_slug vb. taşıyorsa bu kadarı yeter.

Başarılı yanıt

{
  "success": true,
  "session_id": "592cb8b6-2c11-4fd1-9830-42dbcfc4ed0c",
  "still_running": false,
  "message": "İşlem tamamlandı, README güncellendi.",
  "events": 7
}

300 saniyeyi aşan tur

{
  "success": false,
  "session_id": "592cb8b6-2c11-4fd1-9830-42dbcfc4ed0c",
  "still_running": true,
  "message": "…o ana kadar üretilen kısmi metin…",
  "events": 41
}

Oturum sunucuda çalışmaya devam eder; panel arayüzünden veya session_id ile mevcut ServerNox oturum geçmişi uçlarından takip edilebilir.

Hata yanıtı

{
  "detail": "Codex hesabı bağlı değil (profil: default). Hesaplar sekmesinden bu profile giriş yapın…"
}

Kullanım örnekleri

Mevcut bir AI Coding projesini kullan

project_id vererek panelde zaten tanımlı bir projenin kök dizinini ve sunucusunu otomatik çözdürün.

CI/CD entegrasyonu

GitHub Actions veya benzeri bir hatta, bir dağıtım sonrası ajanı tetikleyip sonucu yakalayın.

Kendi sitenizden tetikleme

i-okul.com veya quantlabs.idx.cx gibi kendi uygulamanızın backend'inden, bir webhook/cron tetiklemesiyle bu uca istek atarak ilgili sunucuda bakım/otomasyon görevleri çalıştırın.

CI/CD (GitHub Actions)

- name: ServerNox AI Coding tetikle
  run: |
    curl -X POST https://api.servernox.com/ai-coding/v1/agent \
      -H "X-API-Key: ${{ secrets.SERVERNOX_API_KEY }}" \
      -H "Content-Type: application/json" \
      -d '{
        "project_id": "${{ secrets.SERVERNOX_PROJECT_ID }}",
        "message": "Bağımlılıkları güncelle ve testleri çalıştır"
      }'

Python

import requests

response = requests.post(
    "https://api.servernox.com/ai-coding/v1/agent",
    headers={"X-API-Key": "snx_..."},
    json={
        "project_id": "cb0b3387-e206-4878-85f7-1e0deeebfa9b",
        "message": "Loglardaki son hatayı analiz et",
    },
    timeout=310,
)
print(response.json())