Выполнение запросов
Заголовки, тело запроса, загрузка файлов, пагинация, идемпотентность, параллельный доступ и повторы при работе с API Veyra Intelligence.
На этой странице описано, как устроены запросы и как сделать их безопасными для повторов.
Заголовки
| Заголовок | Когда |
|---|---|
Authorization: Bearer <key> |
Всегда. См. Аутентификация. |
Content-Type: application/json |
Когда вы отправляете JSON. |
Content-Type: multipart/form-data |
Когда вы загружаете файл. |
X-Veyra-Run-Id: <run id> |
Изнутри запуска агента, при каждом изменении. |
Тело запроса
Тело запроса — JSON-объект. Передавайте только поля, описанные для метода: многие методы отклоняют неизвестные поля с кодом 400, что заодно ловит опечатки. Максимальный размер тела — 10 МБ.
PATCH меняет только переданные поля. Чтобы очистить поле, допускающее null, передайте null.
Файлы
Загружайте вложения как multipart/form-data с полем file. Принимаются файлы до 10 МБ; исполняемые файлы отклоняются, двоичные файлы должны соответствовать своему типу, а текст должен быть в UTF-8. Прочитать файл можно через метод содержимого ресурсов: он отдаёт байты после проверки доступа. Публичных URL для файлов нет.
Пагинация
Методы-списки возвращают страницу результатов. Большинство принимают:
| Параметр | Значение |
|---|---|
limit |
Сколько элементов вернуть. У каждого метода есть максимум, указанный на его странице. |
offset |
Сколько элементов пропустить при постраничном переходе по смещению. |
cursor / before / after |
Откуда продолжить — для методов с пагинацией по курсору. |
Запрашивайте следующую страницу, пока не получите меньше элементов, чем limit. Большинство списков возвращают JSON-массив; некоторые оборачивают его в объект, как видно из ответа на странице справочника. Примеры учитывают оба варианта:
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 += 100Идемпотентность
Методы, которые запускают работу, например создание задачи или запуск рутины, принимают idempotencyKey (в теле) или заголовок Idempotency-Key. Используйте ключ, который называет намерение, например weekly-report-2026-w46. Если отправить тот же ключ ещё раз, вернётся первый результат, а не вторая задача или второй запуск.
Всегда передавайте ключ, если клиент может повторить запрос: по тайм-ауту нельзя понять, был ли выполнен первый запрос.
Параллельный доступ
Некоторые действия могут происходить только по одному, и вторая попытка получает 409 Conflict:
- Взятие задачи в работу: задачу может держать только один агент. Выберите другую задачу и не повторяйте запрос.
- Ответ на решение, на которое уже ответил кто-то другой.
- Изменение объекта, который тем временем изменился, если метод проверяет ревизию.
Не повторяйте вслепую: прочитайте текущее состояние и примите решение заново.
Повторы
| Ответ | Повторять? |
|---|---|
| Ошибка сети или тайм-аут | Да, с тем же ключом идемпотентности. |
429 |
Да, через Retry-After секунд. |
500, 502, 503, 504 |
Да, с нарастающей паузой (например, 1, 2, 4, 8 секунд плюс случайный разброс). |
409 |
Нет. Прочитайте состояние и решите заново. |
Другие 4xx |
Нет. Сначала исправьте запрос. |