Первый запрос к API

Внешний API позволяет управлять сбором данных из вашей программы: создавать сайты и сценарии, запускать прогоны, задавать расписания, настраивать прокси и выгрузки. Он использует те же права и лимиты, что и интерфейс.

Адрес и заголовки

Базовый путь: /api/v1 на домене вашей установки. Локально: http://localhost:8701/api/v1. На публичной установке используйте HTTPS.

1. Откройте Токены → API-ключи в нужном пространстве.
2. Создайте ключ. Для чтения оставьте разрешение на изменения выключенным.
3. Скопируйте секрет: полностью он показывается только при создании.
4. Передавайте его в заголовке Authorization: Bearer …. Не включайте секрет в адрес.

curl "$BASE/api/v1/sites" \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Accept: application/json'

Здесь BASE: адрес установки без завершающего слеша, API_KEY: ваш ключ. Сохраните их в защищённых переменных окружения. Cookie, пароль пользователя и браузерный CSRF-токен не нужны.

Для JSON-запросов добавьте Content-Type: application/json. Идентификаторы берите из ответов своей установки, а не из примеров документации.

UUID и совместимость

Для новой интеграции выбирайте /api/v2: он возвращает публичные UUID по умолчанию. Действующий v1-клиент сохраняет числовые ответы без дополнительного заголовка. X-Identifier-Format: uuid включает UUID в v1. Ссылки на ресурсы также принимают короткую форму ~Base58. Форматы идентификаторов и переход.

OpenAPI и Postman

Нажмите «Скачать» рядом с версией документации или «Открыть» на баннере. В диалоге доступны полная спецификация OpenAPI 3.1 JSON, коллекция Postman и необязательный шаблон окружения для выбранного выпуска. Выберите формат: следите за процентом загрузки. После её завершения автоматически откроется стандартное сохранение файла. Баннер можно скрыть крестиком. Кнопка у версии останется доступной. Язык файлов соответствует языку страницы. Числовой контракт v1 без нового заголовка сохраняется. В скачиваемом файле также есть методы v2 с UUID-схемами.

Postman распределяет запросы по папкам и создаёт переменные коллекции при импорте. Заполните base_url, api_key, export_token и нужные идентификаторы ресурсов. Ключи и пароли в файлах пустые. Вводите их только в своих инструментах. Шаблон окружения импортируется отдельно; секретные переменные в нём помечены. OpenAPI использует тематические группы и переменные сервера protocol и host.

Query-параметры без примера сначала выключены. Переменные JSON-тела имеют префикс операции и body_; массивы и объекты задаются JSON-значением. Перед отправкой скрипт собирает тело с правильными типами и экранированием, пропускает пустые необязательные переменные и требует обязательные. Для допускающего null поля задайте null, для пустой строки укажите "". Запрос выполняется только после нажатия «Отправить». Перед изменяющей операцией проверьте состав запроса.

Два разных вида токенов

Токен выгрузки не даёт управление системой. API-ключ не заменяет токен прямого endpoint каталога.

Дальше: права и безопасность, полный цикл сбора.