API v1Загрузить комплект на проверку

Загрузить комплект на проверку

Обновлено 8 октября 2026

POST/runs

Передавайте каждый файл комплекта отдельным полем files. Ответ 201 означает приём комплекта. Проверьте documents и ограничения отчёта. Если ответ потерян, повторите запрос с прежним Idempotency-Key. Изменённый запрос с прежней меткой вызывает конфликт. При 409 idempotency_pending подождите. Не создавайте новую метку для повтора.

Передайте ключ организации в заголовке Authorization: Bearer <ключ>.

Пример запроса

Используйте NK_BASE и NK_KEY из быстрого старта. Переменные в пути, например RUN_ID, замените значениями из ваших ответов API.

POST /runs

curl --fail-with-body -X POST "$NK_BASE/runs" \
  -H "Authorization: Bearer $NK_KEY" \
  -H "Idempotency-Key: object-001-v1" \
  -F "files=@AR.pdf"

Параметры

Параметр	Где / тип	Обязательный	Описание
`Idempotency-Key`	Заголовок строка	Нет	Рекомендуется всегда. при повторе сохраняйте метку. Метка отправки, уникальная для комплекта.

Тело запроса

multipart/form-data

filesмассив: строка · обязательное: Каждый файл передавайте отдельным полем files. Можно передавать архивы.
Вложенные поля
Массив элементов:
строка
kindsстрока · необязательное: JSON-строка с именами файлов и кодами разделов. Сервер игнорирует неизвестные коды и имена.
object_addressстрока · необязательное: Адрес объекта. До 500 символов.
user_requestстрока · необязательное: Задание клиента. До отправки проверьте /features. До 8000 символов.
bundle_idстрока · необязательное: Идентификатор существующего именованного комплекта. До 36 символов.
rolesстрока · необязательное: JSON-строка с точными путями файлов и ролями context или review. Роль из roles имеет приоритет над папками Context и Reviews. При разделении ролей назначьте каждый документ. Назначьте хотя бы один review.
document_namesстрока · необязательное: JSON-массив имён отдельных файлов. Порядок должен совпадать с порядком полей files. Обычно достаточно отправить архив целиком.

Ответы и ошибки

`200`

Повтор: возвращена ранее принятая проверка без второго запуска.

application/json

Поля ответа

run_idстрока · обязательное

Идентификатор проверки. Сохраните его после загрузки.

statusстрока · обязательное

queued — в очереди. running — обработка или публикация. done — результат готов. failed — проверка не завершилась. Значения: "queued", "running", "done", "failed".

documentsмассив: объект · обязательное

Документы комплекта.

Вложенные поля

Массив элементов:

indexцелое число · обязательное: Номер документа в составе комплекта, начиная с 1.
nameстрока · обязательное: Имя документа.
kindстрока / null · необязательное: Код раздела. null означает, что раздел не определён.
kind_chosenда / нет · необязательное: Раздел принят из поля kinds.
kind_guessстрока / null · необязательное: Результат распознавания, если доступен.
pagesцелое число / null · необязательное: Число страниц после подготовки.
convertedда / нет · необязательное: Документ преобразован в PDF.
page_fromцелое число / null · необязательное: Первая сквозная страница документа.
page_toцелое число / null · необязательное: Последняя сквозная страница документа.

objectобъект · необязательное

Вложенные поля

addressстрока / null · необязательное: Адрес объекта, если установлен.
worksстрока / null · необязательное: Наименование работ, если установлено.

user_requestстрока · необязательное

Сохранённое задание клиента. До 8000 символов.

bundleобъект / null · необязательное

Вложенные поля

bundle_idстрока · необязательное: Именованный комплект/проект.
revision_idстрока · необязательное: Версия состава файлов.
labelстрока · необязательное: Название комплекта.

null

volume_unitsцелое число · обязательное

Учтённый объём: 0, 1 или 2. Сверяйте с условиями подключения.

reused_from_run_idстрока / null · необязательное

Источник повторно использованного результата, если есть.

available_atстрока / null · необязательное

Время доступности, если определено.

checks_leftцелое число · обязательное

Остаток после приёма.

double_volumeда / нет · обязательное

Комплект учтён как двойной объём.

`201`

Успешный ответ.

application/json

Поля ответа

run_idстрока · обязательное

Идентификатор проверки. Сохраните его после загрузки.

statusстрока · обязательное

documentsмассив: объект · обязательное

Документы комплекта.

Вложенные поля

Массив элементов:

indexцелое число · обязательное: Номер документа в составе комплекта, начиная с 1.
nameстрока · обязательное: Имя документа.
kindстрока / null · необязательное: Код раздела. null означает, что раздел не определён.
kind_chosenда / нет · необязательное: Раздел принят из поля kinds.
kind_guessстрока / null · необязательное: Результат распознавания, если доступен.
pagesцелое число / null · необязательное: Число страниц после подготовки.
convertedда / нет · необязательное: Документ преобразован в PDF.
page_fromцелое число / null · необязательное: Первая сквозная страница документа.
page_toцелое число / null · необязательное: Последняя сквозная страница документа.

objectобъект · необязательное

Вложенные поля

addressстрока / null · необязательное: Адрес объекта, если установлен.
worksстрока / null · необязательное: Наименование работ, если установлено.

user_requestстрока · необязательное

Сохранённое задание клиента. До 8000 символов.

bundleобъект / null · необязательное

Вложенные поля

bundle_idстрока · необязательное: Именованный комплект/проект.
revision_idстрока · необязательное: Версия состава файлов.
labelстрока · необязательное: Название комплекта.

null

volume_unitsцелое число · обязательное

Учтённый объём: 0, 1 или 2. Сверяйте с условиями подключения.

reused_from_run_idстрока / null · необязательное

Источник повторно использованного результата, если есть.

available_atстрока / null · необязательное

Время доступности, если определено.

checks_leftцелое число · обязательное

Остаток после приёма.

double_volumeда / нет · обязательное

Комплект учтён как двойной объём.

`400`

Неверные параметры запроса или комплект не принят.

application/json

Поля ответа

detailобъект / массив: объект / строка · обязательное

Обычно объект с error. При ошибке проверки параметров возможен список нарушений.

Вложенные поля

errorстрока · обязательное: Машинный код ошибки. Используйте его в обработчике.
messageстрока · необязательное: Пояснение для человека. Текст может меняться.
fileстрока · необязательное: Проблемный файл, если ошибка относится к нему.

Массив элементов:

locмассив: строка / целое число · необязательное: Путь до неверного поля.
msgстрока · необязательное: Причина нарушения.
typeстрока · необязательное: Код нарушения.
inputобъект · необязательное: Переданное значение.

Текст ошибки, если сервер не вернул объект.

`401`

Ключ не передан, неверен или отозван.

application/json

Поля ответа

detailобъект / массив: объект / строка · обязательное

Обычно объект с error. При ошибке проверки параметров возможен список нарушений.

Вложенные поля

errorстрока · обязательное: Машинный код ошибки. Используйте его в обработчике.
messageстрока · необязательное: Пояснение для человека. Текст может меняться.
fileстрока · необязательное: Проблемный файл, если ошибка относится к нему.

Массив элементов:

locмассив: строка / целое число · необязательное: Путь до неверного поля.
msgстрока · необязательное: Причина нарушения.
typeстрока · необязательное: Код нарушения.
inputобъект · необязательное: Переданное значение.

Текст ошибки, если сервер не вернул объект.

`402`

Недостаточно проверок по текущему доступу.

application/json

Поля ответа

detailобъект / массив: объект / строка · обязательное

Обычно объект с error. При ошибке проверки параметров возможен список нарушений.

Вложенные поля

errorстрока · обязательное: Машинный код ошибки. Используйте его в обработчике.
messageстрока · необязательное: Пояснение для человека. Текст может меняться.
fileстрока · необязательное: Проблемный файл, если ошибка относится к нему.

Массив элементов:

locмассив: строка / целое число · необязательное: Путь до неверного поля.
msgстрока · необязательное: Причина нарушения.
typeстрока · необязательное: Код нарушения.
inputобъект · необязательное: Переданное значение.

Текст ошибки, если сервер не вернул объект.

`403`

Доступ закрыт или действие не разрешено.

application/json

Поля ответа

detailобъект / массив: объект / строка · обязательное

Обычно объект с error. При ошибке проверки параметров возможен список нарушений.

Вложенные поля

errorстрока · обязательное: Машинный код ошибки. Используйте его в обработчике.
messageстрока · необязательное: Пояснение для человека. Текст может меняться.
fileстрока · необязательное: Проблемный файл, если ошибка относится к нему.

Массив элементов:

locмассив: строка / целое число · необязательное: Путь до неверного поля.
msgстрока · необязательное: Причина нарушения.
typeстрока · необязательное: Код нарушения.
inputобъект · необязательное: Переданное значение.

Текст ошибки, если сервер не вернул объект.

`404`

Объект не найден, результат ещё не опубликован либо дополнительный метод недоступен в подключении.

application/json

Поля ответа

detailобъект / массив: объект / строка · обязательное

Обычно объект с error. При ошибке проверки параметров возможен список нарушений.

Вложенные поля

errorстрока · обязательное: Машинный код ошибки. Используйте его в обработчике.
messageстрока · необязательное: Пояснение для человека. Текст может меняться.
fileстрока · необязательное: Проблемный файл, если ошибка относится к нему.

Массив элементов:

locмассив: строка / целое число · необязательное: Путь до неверного поля.
msgстрока · необязательное: Причина нарушения.
typeстрока · необязательное: Код нарушения.
inputобъект · необязательное: Переданное значение.

Текст ошибки, если сервер не вернул объект.

`409`

Конфликт версии или метки отправки. Возможная причина для отчёта: нет привязки к запрошенному разделу.

application/json

Поля ответа

detailобъект / массив: объект / строка · обязательное

Обычно объект с error. При ошибке проверки параметров возможен список нарушений.

Вложенные поля

errorстрока · обязательное: Машинный код ошибки. Используйте его в обработчике.
messageстрока · необязательное: Пояснение для человека. Текст может меняться.
fileстрока · необязательное: Проблемный файл, если ошибка относится к нему.

Массив элементов:

locмассив: строка / целое число · необязательное: Путь до неверного поля.
msgстрока · необязательное: Причина нарушения.
typeстрока · необязательное: Код нарушения.
inputобъект · необязательное: Переданное значение.

Текст ошибки, если сервер не вернул объект.

`413`

Превышен размер запроса/комплекта. Входной сервер может вернуть HTML.

application/json

Поля ответа

detailобъект / массив: объект / строка · обязательное

Обычно объект с error. При ошибке проверки параметров возможен список нарушений.

Вложенные поля

errorстрока · обязательное: Машинный код ошибки. Используйте его в обработчике.
messageстрока · необязательное: Пояснение для человека. Текст может меняться.
fileстрока · необязательное: Проблемный файл, если ошибка относится к нему.

Массив элементов:

locмассив: строка / целое число · необязательное: Путь до неверного поля.
msgстрока · необязательное: Причина нарушения.
typeстрока · необязательное: Код нарушения.
inputобъект · необязательное: Переданное значение.

Текст ошибки, если сервер не вернул объект.

`422`

Ошибка валидации: detail содержит объект с кодом либо список нарушений.

application/json

Поля ответа

detailобъект / массив: объект / строка · обязательное

Обычно объект с error. При ошибке проверки параметров возможен список нарушений.

Вложенные поля

errorстрока · обязательное: Машинный код ошибки. Используйте его в обработчике.
messageстрока · необязательное: Пояснение для человека. Текст может меняться.
fileстрока · необязательное: Проблемный файл, если ошибка относится к нему.

Массив элементов:

locмассив: строка / целое число · необязательное: Путь до неверного поля.
msgстрока · необязательное: Причина нарушения.
typeстрока · необязательное: Код нарушения.
inputобъект · необязательное: Переданное значение.

Текст ошибки, если сервер не вернул объект.

`503`

API/подключение/PDF временно недоступны.

application/json

Поля ответа

detailобъект / массив: объект / строка · обязательное

Обычно объект с error. При ошибке проверки параметров возможен список нарушений.

Вложенные поля

errorстрока · обязательное: Машинный код ошибки. Используйте его в обработчике.
messageстрока · необязательное: Пояснение для человека. Текст может меняться.
fileстрока · необязательное: Проблемный файл, если ошибка относится к нему.

Массив элементов:

locмассив: строка / целое число · необязательное: Путь до неверного поля.
msgстрока · необязательное: Причина нарушения.
typeстрока · необязательное: Код нарушения.
inputобъект · необязательное: Переданное значение.

Текст ошибки, если сервер не вернул объект.

`507`

storage_full_retry: недостаточно места для приёма. сохраните прежний Idempotency-Key.

application/json

Поля ответа

detailобъект / массив: объект / строка · обязательное

Обычно объект с error. При ошибке проверки параметров возможен список нарушений.

Вложенные поля

errorстрока · обязательное: Машинный код ошибки. Используйте его в обработчике.
messageстрока · необязательное: Пояснение для человека. Текст может меняться.
fileстрока · необязательное: Проблемный файл, если ошибка относится к нему.

Массив элементов:

locмассив: строка / целое число · необязательное: Путь до неверного поля.
msgстрока · необязательное: Причина нарушения.
typeстрока · необязательное: Код нарушения.
inputобъект · необязательное: Переданное значение.

Текст ошибки, если сервер не вернул объект.

`Другой ответ`

Ошибка входного сервера или сети может иметь текстовое/HTML-тело. Проверяйте HTTP-статус и Content-Type.