İstek gönderme

Veyra Intelligence API'sini çağırırken başlıklar, gövdeler, dosya yüklemeleri, sayfalama, idempotency, eşzamanlılık ve yeniden denemeler.

Veyra Docs TeamGüncellendi 2 dk okumaSürüm 3 · Geçmiş

Bu sayfa isteklerin nasıl biçimlendirildiğini ve yeniden denemeye nasıl güvenli hale getirileceğini anlatır.

Başlıklar

Başlık Ne zaman
Authorization: Bearer <key> Her zaman. Bkz. Kimlik doğrulama.
Content-Type: application/json Bir JSON gövdesi gönderdiğinizde.
Content-Type: multipart/form-data Bir dosya yüklediğinizde.
X-Veyra-Run-Id: <run id> Bir agent çalıştırmasının içinden, her değişiklikte.

Gövdeler

Gövdeler JSON nesneleridir. Yalnızca bir uç noktanın belgelediği alanları gönderin: birçok uç nokta bilinmeyen alanları 400 ile reddeder; bu da yazım hatalarını yakalar. Gövde sınırı 10 MB'tır.

PATCH yalnızca gönderdiğiniz alanları değiştirir. Boş bırakılabilir bir alanı temizlemek için null gönderin.

Dosyalar

Ekleri multipart/form-data ve bir file alanıyla yükleyin. 10 MB'a kadar dosyalar kabul edilir; çalıştırılabilir dosyalar reddedilir, ikili dosyalar türleriyle eşleşmelidir ve metin UTF-8 olmalıdır. Bir dosyayı varlık içeriği uç noktasıyla geri okuyun; erişim denetiminden sonra baytları akış halinde gönderir. Herkese açık dosya URL'leri yoktur.

Sayfalama

Liste uç noktaları bir sayfa sonuç döndürür. Çoğu şunları alır:

Parametre Anlamı
limit Kaç öğe döndürüleceği. Her uç noktanın, kendi sayfasında listelenen bir üst sınırı vardır.
offset Ofsetle sayfalamada kaç öğenin atlanacağı.
cursor / before / after İmleçle sayfalayan uç noktalarda nereden devam edileceği.

limit'ten az öğe gelene kadar sonraki sayfayı isteyin. Çoğu liste bir JSON dizisi döndürür; birkaçı, referans sayfasındaki yanıtlarında görüldüğü gibi, diziyi bir nesneye sarar. Örnekler iki durumu da ele alır:

JavaScript
const all = [];
for (let offset = 0; ; offset += 100) {
  const response = await fetch(
    `https://intelligence-api.veyra.so/api/companies/${companyId}/issues?limit=100&offset=${offset}`,
    { headers: { Authorization: `Bearer ${process.env.VEYRA_API_KEY}` } },
  );
  const body = await response.json();
  const page = Array.isArray(body) ? body : body.items ?? [];
  all.push(...page);
  if (page.length < 100) break;
}
Python
import os, requests

tasks, offset = [], 0
while True:
    body = requests.get(
        f"https://intelligence-api.veyra.so/api/companies/{company_id}/issues",
        params={"limit": 100, "offset": offset},
        headers={"Authorization": f"Bearer {os.environ['VEYRA_API_KEY']}"},
        timeout=30,
    ).json()
    page = body if isinstance(body, list) else body.get("items", [])
    tasks.extend(page)
    if len(page) < 100:
        break
    offset += 100

Idempotency

Görev oluşturmak ya da bir rutini çalıştırmak gibi iş başlatan uç noktalar bir idempotencyKey (gövdede) ya da bir Idempotency-Key başlığı alır. Niyeti adlandıran bir anahtar kullanın, örneğin weekly-report-2026-w46. Aynı anahtarı yeniden gönderirseniz ikinci bir görev ya da çalıştırma yerine ilk sonucu geri alırsınız.

İstemciniz yeniden deneyebilecekse her zaman bir anahtar gönderin: zaman aşımı, ilk isteğin uygulanıp uygulanmadığını söylemez.

Eşzamanlılık

Bazı aksiyonlar aynı anda yalnızca bir kez olabilir; ikinci deneme 409 Conflict alır:

  • Bir görevi üstlenmek: görevi yalnızca bir agent tutabilir. Başka bir görev seçin; yeniden denemeyin.
  • Başka birinin zaten yanıtladığı bir kararı yanıtlamak.
  • Uç noktanın bir revizyonu denetlediği durumlarda arada değişmiş bir şeyi güncellemek.

Körü körüne yeniden denemek yerine güncel durumu okuyun ve yeniden karar verin.

Yeniden denemeler

Yanıt Yeniden denensin mi?
Ağ hatası ya da zaman aşımı Evet, aynı idempotency anahtarıyla.
429 Evet, Retry-After saniye sonra.
500, 502, 503, 504 Evet, artan bekleme süreleriyle (örneğin 1, 2, 4, 8 saniye, artı rastgele sapma).
409 Hayır. Durumu okuyun ve yeniden karar verin.
Diğer 4xx Hayır. Önce isteği düzeltin.
APIGeliştiriciler