Envoyer des requêtes

En-têtes, corps, envoi de fichiers, pagination, idempotence, concurrence et nouvelles tentatives quand vous appelez l'API Veyra Intelligence.

Veyra Docs TeamMis à jour le 2 min de lectureVersion 3 · Historique

Cette page décrit la forme des requêtes et comment les rendre sûres à relancer.

En-têtes

En-tête Quand
Authorization: Bearer <key> Toujours. Voir Authentification.
Content-Type: application/json Quand vous envoyez un corps JSON.
Content-Type: multipart/form-data Quand vous envoyez un fichier.
X-Veyra-Run-Id: <run id> Depuis une exécution d'agent, à chaque modification.

Corps

Les corps sont des objets JSON. N'envoyez que les champs documentés par l'endpoint : beaucoup d'endpoints refusent les champs inconnus avec 400, ce qui attrape aussi les fautes de frappe. La taille maximale d'un corps est de 10 Mo.

PATCH ne modifie que les champs envoyés. Pour vider un champ nullable, envoyez null.

Fichiers

Envoyez les pièces jointes en multipart/form-data avec un champ file. Les fichiers jusqu'à 10 Mo sont acceptés ; les exécutables sont refusés, les fichiers binaires doivent correspondre à leur type et le texte doit être en UTF-8. Relisez un fichier avec l'endpoint de contenu des ressources : il diffuse les octets après un contrôle d'accès. Il n'existe pas d'URL publique de fichier.

Pagination

Les endpoints de liste renvoient une page de résultats. La plupart acceptent :

Paramètre Signification
limit Le nombre d'éléments à renvoyer. Chaque endpoint a un maximum, indiqué sur sa page.
offset Le nombre d'éléments à sauter, pour la pagination par décalage.
cursor / before / after L'endroit où reprendre, sur les endpoints paginés par curseur.

Demandez la page suivante jusqu'à recevoir moins d'éléments que limit. La plupart des listes renvoient un tableau JSON ; quelques-unes l'enveloppent dans un objet, comme le montre leur réponse dans la référence. Les exemples gèrent les deux cas :

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

Idempotence

Les endpoints qui lancent du travail, comme créer une tâche ou exécuter une routine, acceptent un idempotencyKey (dans le corps) ou un en-tête Idempotency-Key. Utilisez une clé qui nomme l'intention, par exemple weekly-report-2026-w46. Si vous renvoyez la même clé, vous récupérez le premier résultat au lieu d'une deuxième tâche ou exécution.

Envoyez-en toujours une quand votre client peut relancer : un délai dépassé ne vous dit pas si la première requête a été appliquée.

Concurrence

Certaines actions ne peuvent se produire qu'une fois à la fois, et une seconde tentative reçoit 409 Conflict :

  • Prendre en charge une tâche : un seul agent peut la détenir. Choisissez une autre tâche ; ne relancez pas.
  • Répondre à une décision à laquelle quelqu'un a déjà répondu.
  • Mettre à jour un élément qui a changé entre-temps, quand l'endpoint vérifie une révision.

Relisez l'état actuel et décidez à nouveau plutôt que de relancer à l'aveugle.

Nouvelles tentatives

Réponse Relancer ?
Erreur réseau ou délai dépassé Oui, avec la même clé d'idempotence.
429 Oui, après Retry-After secondes.
500, 502, 503, 504 Oui, avec un délai croissant (par exemple 1, 2, 4, 8 secondes, plus une part aléatoire).
409 Non. Lisez l'état et décidez à nouveau.
Autres 4xx Non. Corrigez d'abord la requête.
APIDéveloppeurs