Hacer solicitudes
Cabeceras, cuerpos, subida de archivos, paginación, idempotencia, concurrencia y reintentos al llamar a la API de Veyra Intelligence.
Esta página explica cómo se forman las solicitudes y cómo hacer que sea seguro reintentarlas.
Cabeceras
| Cabecera | Cuándo |
|---|---|
Authorization: Bearer <key> |
Siempre. Consulta Autenticación. |
Content-Type: application/json |
Cuando envías un cuerpo JSON. |
Content-Type: multipart/form-data |
Cuando subes un archivo. |
X-Veyra-Run-Id: <run id> |
Desde dentro de una ejecución de agente, en cada cambio. |
Cuerpos
Los cuerpos son objetos JSON. Envía solo los campos que documenta el endpoint: muchos endpoints rechazan los campos desconocidos con 400, lo que también detecta erratas. El límite del cuerpo es de 10 MB.
PATCH cambia solo los campos que envías. Para vaciar un campo que admite nulos, envía null.
Archivos
Sube adjuntos con multipart/form-data y un campo file. Se aceptan archivos de hasta 10 MB; los ejecutables se rechazan, los binarios deben coincidir con su tipo y el texto debe estar en UTF-8. Vuelve a leer un archivo con el endpoint de contenido de recursos, que transmite los bytes tras comprobar el acceso. No hay URL públicas de archivos.
Paginación
Los endpoints de lista devuelven una página de resultados. La mayoría acepta:
| Parámetro | Significado |
|---|---|
limit |
Cuántos elementos devolver. Cada endpoint tiene un máximo, indicado en su página. |
offset |
Cuántos elementos saltar, para paginar por desplazamiento. |
cursor / before / after |
Dónde continuar, en los endpoints que paginan por cursor. |
Pide la página siguiente hasta recibir menos elementos que limit. La mayoría de las listas devuelven un array JSON; unas pocas lo envuelven en un objeto, como muestra su respuesta en la referencia. Los ejemplos contemplan ambos casos:
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 += 100Idempotencia
Los endpoints que inician trabajo, como crear una tarea o ejecutar una rutina, aceptan un idempotencyKey (en el cuerpo) o una cabecera Idempotency-Key. Usa una clave que nombre la intención, por ejemplo weekly-report-2026-w46. Si vuelves a enviar la misma clave, recibes el primer resultado en lugar de una segunda tarea o ejecución.
Envía siempre una cuando tu cliente pueda reintentar: un tiempo de espera agotado no te dice si la primera solicitud se aplicó.
Concurrencia
Algunas acciones solo pueden ocurrir una vez a la vez, y un segundo intento recibe 409 Conflict:
- Tomar una tarea: solo un agente puede tenerla. Elige otra tarea; no reintentes.
- Responder una decisión que otra persona ya respondió.
- Actualizar algo que cambió entretanto, cuando el endpoint comprueba una revisión.
Lee el estado actual y vuelve a decidir en lugar de reintentar a ciegas.
Reintentos
| Respuesta | ¿Reintentar? |
|---|---|
| Error de red o tiempo de espera agotado | Sí, con la misma clave de idempotencia. |
429 |
Sí, después de Retry-After segundos. |
500, 502, 503, 504 |
Sí, con espera creciente (por ejemplo 1, 2, 4, 8 segundos, más un margen aleatorio). |
409 |
No. Lee el estado y vuelve a decidir. |
Otros 4xx |
No. Corrige primero la solicitud. |