API: Kimlik Doğrulama ve Kontör Sistemi

YSN REST API'si, panelde yaptığınız her şeyi programatik olarak yapmanıza olanak verir. Tüm endpoint'ler https://atlas.yasinburak.com/api/v1/ altında toplanmıştır. Bu dokümanda kimlik doğrulama, token yenileme, /auth/me endpoint'i, kontör sistemi ve bir promptun nasıl çalıştırılacağını anlatıyoruz.

Bearer Token

Tüm istekler Authorization: Bearer <token> başlığı ile imzalanır. İki tür token desteklenir:

• **Oturum JWT** — panele login olunca cookie içinde verilen token. Kısa ömürlü (15 dakika). Yenileme `/api/v1/auth/refresh` ile.
• **Kişisel API anahtarı** — Ayarlar > Geliştirici > "Yeni anahtar" ile üretilir. Uzun ömürlü (yok etmeden geçerli). Format: `ysn_live_xxxxxxxxxxxxxxxxxxxx`. Sunucu tarafında Argon2 ile hash'lenir; kaybederseniz tekrar gösterilmez.

API anahtarı sadece Starter üstü planlarda. Enterprise'larda anahtar başına scope kısıtlaması ve IP whitelist yapılabilir.

/auth/me

Mevcut kullanıcı profilini ve kontör durumunu döner.

curl -s https://atlas.yasinburak.com/api/v1/auth/me \
  -H "Authorization: Bearer ysn_live_xxx"

Response:

{
  "user": {
    "id": "usr_7K2pM",
    "email": "[email protected]",
    "name": "Yasin",
    "plan": "klinik_pro",
    "role": "owner"
  },
  "workspace": {
    "id": "ws_abc",
    "name": "Mecy Clinic",
    "locale": "tr"
  },
  "credits": {
    "remaining": 18473,
    "monthly_limit": 20000,
    "reset_at": "2026-05-01T00:00:00Z",
    "addons": 0
  },
  "features": ["prompts", "bots", "chatbot", "social", "memory"]
}

credits.remaining <= 100 ise panelde turuncu uyarı çıkar.

Kontör Mantığı

Her plan aylık bir kontör kotası verir:

Ay sonunda sıfırlanır (kullanılmayan kontör devretmez). Ek kontör satın almak için Pricing > "Kontör paketi". Addon kontörler ay sonunda sıfırlanmaz, hesap kapatılana kadar durur.

Kontör maliyeti nasıl hesaplanır?

• **Sabit promptlar**: kütüphanede `credits_cost` alanında yazılı (1-8).
• **Uzman botlar**: model ve token sayısına göre dinamik (`0.001 * input_tokens + 0.003 * output_tokens` TRY cinsinden değil kontör cinsinden normalize).
• **Chatbot konuşma turu**: ortalama 1-3.
• **Resim üretimi**: 10-50.

Gerçek kontör credits_used alanında execute response'unda döner.

/prompts/execute

Bir promptu çalıştırır.

curl -N -X POST https://atlas.yasinburak.com/api/v1/prompts/execute \
  -H "Authorization: Bearer ysn_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt_id": "insta_reels_hook_v2",
    "inputs": {"konu": "botoks", "ton": "eğlenceli"},
    "locale": "tr",
    "stream": true
  }'

Stream response (SSE):

data: {"delta": "Selam! "}
data: {"delta": "Botoks hakkında"}
data: {"delta": " bilmen gereken 3 şey..."}
data: {"done": true, "credits_used": 2, "credits_remaining": 18471}

stream: false gönderirseniz tek JSON döner.

Hata Kodları

• `401 Unauthorized` — token yok / geçersiz / süresi dolmuş.
• `402 Payment Required` — kontör bitti veya plan yetersiz.
• `403 Forbidden` — endpoint plan'ınızda yok veya workspace'ten farklı kaynak.
• `404 Not Found` — prompt_id mevcut değil.
• `422 Unprocessable Entity` — input şemaya uymuyor.
• `429 Too Many Requests` — dakikada limit aşıldı (default 60 req/dk).

Oran Sınırı

Varsayılan 60 req/dk (kullanıcı başına), execute için ayrı havuz 30 req/dk. Header'larda X-RateLimit-Remaining ve X-RateLimit-Reset gelir. Enterprise planda kaldırılır.

Python Örneği

import httpx

API = "https://atlas.yasinburak.com/api/v1"
TOKEN = "ysn_live_xxx"

def run_prompt(prompt_id, inputs):
    with httpx.Client(timeout=60) as c:
        r = c.post(
            f"{API}/prompts/execute",
            headers={"Authorization": f"Bearer {TOKEN}"},
            json={"prompt_id": prompt_id, "inputs": inputs, "locale": "tr"}
        )
        r.raise_for_status()
        return r.json()

out = run_prompt("insta_reels_hook_v2", {"konu": "botoks", "ton": "eğlenceli"})
print(out["content"])

İpuçları

• Üretim entegrasyonunda `X-Request-Id` başlığı gönderin (idempotency için).
• Büyük batchleri tek döngüde çağırmak yerine concurrent 4-8 worker ile yapın.
• Her çağrı için `/auth/me`'yi baştan çağırmayın; önbelleğe alın (60 sn).