Выполнение запросов

Заголовки, тело запроса, загрузка файлов, пагинация, идемпотентность, параллельный доступ и повторы при работе с API Veyra Intelligence.

Veyra Docs TeamОбновлено 2 мин чтенияВерсия 3 · История

На этой странице описано, как устроены запросы и как сделать их безопасными для повторов.

Заголовки

Заголовок Когда
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-массив; некоторые оборачивают его в объект, как видно из ответа на странице справочника. Примеры учитывают оба варианта:

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

Идемпотентность

Методы, которые запускают работу, например создание задачи или запуск рутины, принимают idempotencyKey (в теле) или заголовок Idempotency-Key. Используйте ключ, который называет намерение, например weekly-report-2026-w46. Если отправить тот же ключ ещё раз, вернётся первый результат, а не вторая задача или второй запуск.

Всегда передавайте ключ, если клиент может повторить запрос: по тайм-ауту нельзя понять, был ли выполнен первый запрос.

Параллельный доступ

Некоторые действия могут происходить только по одному, и вторая попытка получает 409 Conflict:

  • Взятие задачи в работу: задачу может держать только один агент. Выберите другую задачу и не повторяйте запрос.
  • Ответ на решение, на которое уже ответил кто-то другой.
  • Изменение объекта, который тем временем изменился, если метод проверяет ревизию.

Не повторяйте вслепую: прочитайте текущее состояние и примите решение заново.

Повторы

Ответ Повторять?
Ошибка сети или тайм-аут Да, с тем же ключом идемпотентности.
429 Да, через Retry-After секунд.
500, 502, 503, 504 Да, с нарастающей паузой (например, 1, 2, 4, 8 секунд плюс случайный разброс).
409 Нет. Прочитайте состояние и решите заново.
Другие 4xx Нет. Сначала исправьте запрос.
APIРазработчикам