İ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.
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:
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;
}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 += 100Idempotency
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. |