Envoyer des requêtes
En-têtes, corps, envoi de fichiers, pagination, idempotence, concurrence et nouvelles tentatives quand vous appelez l'API Veyra Intelligence.
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 :
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 += 100Idempotence
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. |