İstek Gönderme

Bu sayfa, Chainabit API ile etkileşime girerken bilmeniz gereken kuralları ve kalıpları kapsar: temel URL, başlıklar, yanıt biçimi, sayfalama, hata yönetimi ve idempotency.

---

Temel URL

Tüm uç noktalar şuna görelidir:

https://api.chainabit.com/api/v1

Örneğin, AI oturumları uç noktası {API_URL}/api/v1/ai/sessions adresine çözümlenir.

---

Ortam Değişkenleri

Bu sayfadaki herhangi bir örneği çalıştırmadan önce bu değişkenleri ayarlayın:

export BASE_URL="https://api.chainabit.com/api/v1"
export TOKEN="your-access-token"

---

Zorunlu Başlıklar

Her istek şunları içermelidir:

Başlık	Değer	Zorunlu
Content-Type	application/json	POST, PUT ve PATCH istekleri için
Authorization	Bearer <accessToken>	Kimlik doğrulaması gereken tüm uç noktalar için

---

Yanıt Zarfı

Her API yanıtı tutarlı bir zarf yapısını izler:

{
  "data": { ... },
  "meta": { ... },
  "error": null
}

Alan	Açıklama
data	İstenen kaynak veya sonuç. Bir hata oluştuğunda null olur.
meta	Sayfalama bilgisi gibi ek üst veriler. Geçerli değilse null olur.
error	Hata ayrıntıları. İstek başarılı olduğunda null olur.

Zarf tasarımının daha ayrıntılı açıklaması için Yanıt Zarfı sayfasına bakın.

Başarılı Yanıt

{
  "data": {
    "id": "c9f8e7d6-5432-10fe-dcba-0987654321fe",
    "title": "Research Assistant",
    "status": "active"
  },
  "meta": null,
  "error": null
}

Hata Yanıtı

{
  "data": null,
  "meta": null,
  "error": {
    "statusCode": 404,
    "message": "Chain not found",
    "code": "NOT_FOUND"
  }
}

---

Sayfalama

Liste uç noktaları, iki sorgu parametresiyle offset tabanlı sayfalamayı destekler:

Parametre	Varsayılan	Açıklama
limit	20	Döndürülecek öğe sayısı (üst sınır uç noktaya göre değişir).
offset	0	Atlanacak öğe sayısı.

Örnek

cURL

curl "https://api.chainabit.com/api/v1/ai/sessions?limit=10&offset=20" \
  -H "Authorization: Bearer $TOKEN"

JavaScript

const response = await fetch(
  `${BASE_URL}/ai/sessions?limit=10&offset=20`,
  {
    headers: { Authorization: `Bearer ${TOKEN}` },
  }
);
const { data, meta } = await response.json();

Python

import requests

response = requests.get(
    f"{BASE_URL}/ai/sessions",
    params={"limit": 10, "offset": 20},
    headers={"Authorization": f"Bearer {TOKEN}"},
)
result = response.json()
data, meta = result["data"], result["meta"]

Postman

Open AI → GET List Sessions
Add query params: limit=10, offset=20

Yanıt

{
  "data": [
    { "id": "...", "title": "Developer Pipeline" },
    { "id": "...", "title": "Research Assistant" }
  ],
  "meta": {
    "total": 42,
    "limit": 10,
    "offset": 20
  },
  "error": null
}

Sayfa sayısını hesaplamak veya daha fazla öğe olup olmadığını belirlemek için meta.total değerini kullanın. Sayfalamanın tüm ayrıntıları için Sayfalama sayfasına bakın.

---

Hata Yönetimi

Yanıttaki error alanını her zaman kontrol edin. Yaygın HTTP durum kodları:

Durum	Anlamı
400	Hatalı istek -- geçersiz veya eksik parametreler.
401	Yetkisiz -- eksik veya süresi dolmuş token.
403	Yasak -- yetersiz izinler veya captcha hatası.
404	Bulunamadı -- kaynak mevcut değil.
409	Çakışma -- yinelenen kaynak veya idempotency anahtarı çakışması.
422	İşlenemeyen varlık -- doğrulama hatası.
429	Çok fazla istek -- hız sınırı aşıldı.
500	Dahili sunucu hatası.

Hız Sınırlama

Hız sınırını aştığınızda API, kaç saniye beklenmesi gerektiğini belirten bir Retry-After başlığıyla 429 Too Many Requests döndürür:

{
  "data": null,
  "meta": null,
  "error": {
    "statusCode": 429,
    "message": "Rate limit exceeded. Try again in 30 seconds.",
    "code": "RATE_LIMITED"
  }
}

En iyi uygulama: üstel geri çekilme uygulayın ve Retry-After başlığına uyun. Hız sınırı katmanları ve kotalar için Hız Sınırlama sayfasına bakın.

Tüm hata kodu referansı için Hatalar sayfasına bakın.

---

Idempotency

Bazı değiştirici uç noktalar (işlem oluşturma veya olay kaydetme gibi) bir Idempotency-Key başlığı kabul eder. Aynı uç nokta için aynı idempotency anahtarını göndermek, yinelenen bir kaynak oluşturmadan özgün yanıtı döndürür.

cURL

curl -X POST https://api.chainabit.com/api/v1/ai/sessions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{"title": "Pipeline session"}'

JavaScript

const response = await fetch(`${BASE_URL}/ai/sessions`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${TOKEN}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({ title: 'Pipeline session' }),
});
const { data } = await response.json();

Python

import requests
import uuid

response = requests.post(
    f"{BASE_URL}/ai/sessions",
    headers={
        "Authorization": f"Bearer {TOKEN}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={"title": "Pipeline session"},
)
data = response.json()["data"]

Postman

Open AI → POST Create Session
Set Idempotency-Key header to {{$randomUUID}}

Kurallar:

• Idempotency anahtarı olarak bir UUID v4 kullanın.
• Anahtarlar hesabınıza ve belirli bir uç noktaya göre kapsamlandırılır.
• Anahtarların süresi 24 saat sonra dolar. Sonrasında aynı anahtar yeniden kullanılabilir.
• Özgün istek hâlâ işleniyorsa, aynı anahtarla gönderilen sonraki bir istek 409 Conflict döndürür.

---

Tam İstek-Yanıt Örneği

Aşağıda bir AI oturumu oluşturan, olası hataları ele alan ve doğru başlık kullanımını gösteren eksiksiz bir örnek yer alıyor:

curl -s -w "\nHTTP_STATUS:%{http_code}" \
  -X POST https://api.chainabit.com/api/v1/ai/sessions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -d '{
    "title": "Research Assistant"
  }'

Başarılı -- 201 Created

{
  "data": {
    "id": "sess_01HQ3K5N2P4R7T9V1X3Z5A7C9E",
    "title": "Research Assistant",
    "status": "active",
    "createdAt": "2026-05-04T20:00:00.000Z"
  },
  "meta": null,
  "error": null
}

Doğrulama hatası -- 422 Unprocessable Entity

{
  "data": null,
  "meta": null,
  "error": {
    "statusCode": 422,
    "message": "Validation failed",
    "code": "VALIDATION_ERROR",
    "details": [
      {
        "field": "title",
        "message": "title must be a string and is required"
      }
    ]
  }
}

Token süresi doldu -- 401 Unauthorized

{
  "data": null,
  "meta": null,
  "error": {
    "statusCode": 401,
    "message": "Unauthorized",
    "code": "UNAUTHORIZED"
  }
}

Bir 401 aldığınızda token'ınızı yenileyin (Kimlik Doğrulama sayfasına bakın) ve isteği yeniden deneyin.

---

Sonraki Adımlar

• Ayrıntılı uç nokta belgeleri için tüm API Referansı belgesine göz atın.
• Token yönetimi için Kimlik Doğrulama konusunu öğrenin.
• Eksiksiz hata kodu kataloğu için Hatalar sayfasını inceleyin.