Making requests
Headers, bodies, file uploads, pagination, idempotency, concurrency and retries when you call the Veyra Intelligence API.
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:
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 += 100Idempotency
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. |