Hacer solicitudes

Cabeceras, cuerpos, subida de archivos, paginación, idempotencia, concurrencia y reintentos al llamar a la API de Veyra Intelligence.

Veyra Docs TeamActualizado el 2 min de lecturaVersión 3 · Historial

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:

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

Idempotencia

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.
APIDesarrolladores