Making requests

Headers, bodies, file uploads, pagination, idempotency, concurrency and retries when you call the Veyra Intelligence API.

Veyra Docs TeamUpdated 2 min readVersion 4 · History

This page covers how requests are shaped and how to make them safe to retry.

Headers

Header When
Authorization: Bearer <key> Always. See Authentication.
Content-Type: application/json When you send a JSON body.
Content-Type: multipart/form-data When you upload a file.
X-Veyra-Run-Id: <run id> From inside an agent run, on every change.

Bodies

Bodies are JSON objects. Send only the fields an endpoint documents: many endpoints refuse unknown fields with 400, which also catches typos. The body limit is 10 MB.

PATCH changes only the fields you send. To clear a nullable field, send null.

Files

Upload attachments with multipart/form-data and a file field. Files up to 10 MB are accepted; executables are refused, binary files must match their type, and text must be UTF-8. Read a file back with the asset content endpoint; it streams the bytes after an access check. There are no public file URLs.

Pagination

List endpoints return a page of results. Most take:

Parameter Meaning
limit How many items to return. Each endpoint has a maximum, listed on its page.
offset How many items to skip, for offset paging.
cursor / before / after Where to continue, on endpoints that page by cursor.

Ask for the next page until you get fewer items than limit. Most lists return a JSON array; a few wrap it in an object, as their response on the reference page shows. The examples handle both:

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

Idempotency

Endpoints that start work, such as creating a task or running a routine, take an idempotencyKey (in the body) or an Idempotency-Key header. Use a key that names the intent, for example weekly-report-2026-w46. If you send the same key again, you get the first result back instead of a second task or run.

Always send one when your client may retry: a timeout does not tell you whether the first request was applied.

Concurrency

Some actions can only happen once at a time, and a second attempt gets 409 Conflict:

  • Checking out a task: only one agent can hold it. Pick another task; do not retry.
  • Answering a decision someone else already answered.
  • Updating something that changed meanwhile, where the endpoint checks a revision.

Read the current state and decide again rather than retrying blindly.

Retries

Response Retry?
Network error or timeout Yes, with the same idempotency key.
429 Yes, after Retry-After seconds.
500, 502, 503, 504 Yes, with backoff (for example 1, 2, 4, 8 seconds, plus jitter).
409 No. Read the state and decide again.
Other 4xx No. Fix the request first.
APIDevelopers