API n8n: первый запрос и получение списка workflows
Подключение к публичному API n8n на Python: ключ, GET-запрос, пагинация и обработка ошибок без изменения workflows.
Публичный API n8n позволяет читать и управлять workflows программно. Для первого знакомства получим список процессов, не изменяя и не запуская их. Это другой сценарий, чем вызов webhook конкретной автоматизации.
Мой подход. Я бы начинал с чтения списка. Так можно проверить адрес, ключ и пагинацию, не смешивая настройку соединения с изменением рабочих автоматизаций.
1. Проверь доступ и создай отдельный ключ
В n8n открой Settings → n8n API и создай ключ с понятным названием и сроком действия. В документации указано, что API недоступен во время бесплатного пробного периода. На Enterprise можно ограничить scopes; для списка нужен workflow:list. У ключей других планов область доступа шире, поэтому храни ключ как секрет. Правила авторизации n8n.
Проверь адрес своего экземпляра в браузере. Для запросов используется корень API с окончанием /api/v1. Если установка находится в подпапке, сохрани её в адресе. Не подставляй адрес страницы конкретного workflow: это URL интерфейса, а не корень API.
Не вставляй ключ в промпт или публичный пример. В приложенном клиенте он вводится скрыто через терминал и не записывается в файл.
2. Запусти готовый клиент на Python
Скачай учебный комплект, распакуй его и запусти из этой папки:
python3 n8n_read.pyНа Windows можно использовать py n8n_read.py, если Python установлен с этим launcher. Нужен Python 3.10 или новее; внешних библиотек нет. Введи полный HTTPS-адрес корня API своего экземпляра, затем ключ. Для локального n8n допускается HTTP только на localhost или 127.0.0.1.
Клиент выполняет GET /workflows?limit=100, передавая секрет в заголовке X-N8N-API-KEY. Он печатает только ID и названия workflows, а не весь JSON с настройками узлов. Перенаправления запрещены: случайный redirect не должен унести ключ на другой адрес. При неверном URL исправь ввод, а не отключай эту проверку.
Ожидаемый результат — список доступных ключу процессов. Пустой список может быть корректным. Чтобы проверить его, сравни с тем же аккаунтом в интерфейсе. Наличие HTTP 200 подтверждает ответ сервера, но не гарантирует, что выбран правильный экземпляр.
3. Не потеряй данные после первой страницы
В n8n список возвращается страницами. Если есть продолжение, ответ содержит nextCursor; его нужно передать как параметр cursor следующего запроса. Стандартная страница содержит до 100 записей, максимальный размер — 250. Документация пагинации.
Приложенный клиент проходит страницы до отсутствия курсора. Он останавливается при повторном курсоре или неожиданной структуре ответа, чтобы не выдать неполный результат за полный. ID используются для обнаружения дублей. Если workflows менялись во время обхода, такой список не следует считать снимком состояния на одну точную секунду.
Для проверки без аккаунта запусти:
python3 -m unittest -vТесты используют искусственные ответы: одну страницу, две страницы, пустой список, повторный курсор, неверную структуру и redirect. Они проверяют логику клиента; реальный доступ к твоему n8n подтверждается только запуском с действующим ключом. Мы не подменяем эти два вида проверки.
4. Разбирай ошибку по уровню
| Результат | Следующая проверка |
|---|---|
| 401 | Действует ли ключ и тот ли он для этого экземпляра |
| 403 | Права, доступность API и политики экземпляра |
| 404 | Корень API, подпапка установки и путь метода |
| 429 | Ограничение частоты; повторить позже без частого цикла |
| HTML вместо JSON | Возможно, открыт интерфейс входа или страница proxy |
| Ошибка сертификата | Проверить TLS на сервере, не отключать проверку |
Сохрани код ошибки и время. Не публикуй полный запрос с ключом. Если клиент завершился ошибкой, его частичный вывод нельзя считать полным списком; сначала устрани причину и повтори чтение.
Когда чтение стабильно работает, можно строить отчёт о процессах или сверять их наличие. Операции изменения, публикации и удаления рассматривай отдельно: там нужны другие разрешения и собственная проверка результата. Если задача — передать данные внутрь уже собранного процесса, используй webhook в n8n. Для обращения n8n к внешним таблицам есть руководство по Google Sheets.
Собери своего ИИ-агента и проверь результат
«AI Agents: от vibe coding к AI-команде»: desktop agents, MCP, skills, evals и harness. Отдельные воркшопы — от подключения инструментов до контроля качества.
7 практических воркшопов · записи · вопросы автору в чате
Посмотреть программу курса ↗