N8n rest api

N8n REST API: Полное руководство по интеграции и автоматизации

N8n REST API представляет собой программный интерфейс, который позволяет взаимодействовать с платформой автоматизации n8n извне. Этот API открывает возможности для управления рабочими процессами (workflows), их выполнения, мониторинга, а также для интеграции n8n в более крупные системы и скрипты. В отличие от графического интерфейса, API предоставляет машиночитаемый способ полного контроля над инстанцией n8n, что критически важно для DevOps, CI/CD пайплайнов и создания кастомных панелей управления.

Архитектура и базовые концепции N8n API

API n8n построен по принципам REST и использует стандартные HTTP-методы (GET, POST, PUT, PATCH, DELETE) для операций с ресурсами. Основные сущности, с которыми работает API, — это Workflows (рабочие процессы), Executions (запуски), Credentials (учетные данные) и Webhooks (внешние триггеры). Аутентификация в API по умолчанию осуществляется с помощью секретного ключа, который генерируется в настройках экземпляра n8n. Важно понимать, что n8n может работать в двух режимах: как изолированный сервис и как встраиваемая библиотека, и возможности API в этих сценариях могут различаться.

Аутентификация и безопасность

Для вызова большинства эндпоинтов API n8n требуется заголовок аутентификации. Основной метод — использование заголовка X-N8N-API-KEY, значением которого является сгенерированный API-ключ. Альтернативно, можно использовать базовую HTTP-аутентификацию (Basic Auth) или сессионные куки после входа в UI. Настоятельно рекомендуется использовать HTTPS для защиты передаваемых данных и хранить API-ключи в безопасном месте, например, в переменных окружения.

Методы аутентификации в N8n REST API

Метод	Заголовок/Параметр	Пример	Использование
API Key	X-N8N-API-KEY	X-N8N-API-KEY: your_secret_api_key_here	Рекомендуемый способ для сервер-сервер взаимодействия.
Basic Auth	Authorization: Basic	Authorization: Basic base64(email:password)	Альтернативный способ, использует учетные данные пользователя.
Session Cookie	Cookie	Cookie: n8n-session=session_id_value	Используется после входа через веб-интерфейс, чаще для браузерных скриптов.

Ключевые эндпоинты API и их использование

Управление рабочими процессами (Workflows)

Эндпоинты для работы с рабочими процессами являются центральными. Они позволяют создавать, читать, обновлять, удалять, активировать и деактивировать workflows.

• GET /api/v1/workflows: Получение списка всех рабочих процессов. Поддерживает пагинацию, фильтрацию и выбор полей.
• GET /api/v1/workflows/{id}: Получение полной информации о конкретном workflow, включая его узлы (nodes) и связи.
• POST /api/v1/workflows: Создание нового рабочего процесса. Тело запроса должно содержать полное JSON-представление workflow.
• PUT /api/v1/workflows/{id}: Полное обновление существующего workflow.
• PATCH /api/v1/workflows/{id}: Частичное обновление (например, только активация).
• DELETE /api/v1/workflows/{id}: Удаление рабочего процесса.
• POST /api/v1/workflows/{id}/activate: Активация workflow (перевод его в активное состояние, чтобы он мог запускаться по триггерам).
• POST /api/v1/workflows/{id}/deactivate: Деактивация workflow.

Запуск и мониторинг выполнения (Executions)

Executions представляют собой отдельные запуски рабочего процесса. API позволяет запускать workflow вручную и получать детальную информацию о прошлых выполнениях.

• GET /api/v1/executions: Получение списка всех выполнений с возможностью фильтрации по workflow ID, статусу и дате.
• GET /api/v1/executions/{id}: Получение деталей конкретного выполнения, включая данные на каждом узле (если включено сохранение данных).
• POST /api/v1/workflows/{id}/run: Синхронный запуск workflow. API дожидается окончания выполнения и возвращает его результат. Важно для интеграций, требующих немедленного ответа.
• POST /api/v1/workflows/{id}/execute: Асинхронный запуск workflow. API немедленно возвращает ID запущенного выполнения, а сам процесс работает в фоне. Предпочтительнее для длительных операций.
• DELETE /api/v1/executions/{id}: Удаление записи о выполнении.

Управление учетными данными (Credentials)

Учетные данные хранятся в зашифрованном виде. API предоставляет ограниченный доступ к ним для обеспечения безопасности.

• GET /api/v1/credentials: Получение списка метаданных учетных записей (без самих секретов).
• GET /api/v1/credentials/{id}: Получение метаданных конкретной учетной записи.
• POST /api/v1/credentials: Создание новых учетных данных. Секретная часть должна быть передана в соответствующем поле.
• PATCH /api/v1/credentials/{id}: Обновление учетных данных. Можно обновить как название, так и сам секрет.
• DELETE /api/v1/credentials/{id}: Удаление учетных данных.

Практические примеры использования API

Пример 1: Создание и активация рабочего процесса через API

Следующий пример на Python демонстрирует, как создать простой workflow, который отправляет HTTP-запрос, и активировать его.

import requests
import json

API_KEY = "your_n8n_api_key"
N8N_URL = "https://your-n8n-instance.com"

headers = {"X-N8N-API-KEY": API_KEY, "Content-Type": "application/json"}

1. Создание workflow
workflow_data = {
    "name": "API Created Workflow",
    "nodes": [
        {
            "name": "HTTP Request Node",
            "type": "n8n-nodes-base.httpRequest",
            "parameters": {
                "url": "https://api.example.com/data",
                "method": "GET"
            },
            "position": [250, 300]
        }
    ],
    "connections": {},
    "settings": {},
    "triggerOnActivation": True
}

response = requests.post(f"{N8N_URL}/api/v1/workflows", json=workflow_data, headers=headers)
new_workflow_id = response.json()["data"]["id"]
print(f"Created workflow ID: {new_workflow_id}")

2. Активация workflow
activate_response = requests.post(f"{N8N_URL}/api/v1/workflows/{new_workflow_id}/activate", headers=headers)
if activate_response.status_code == 200:
    print("Workflow activated successfully.")

Пример 2: Синхронный запуск workflow с передачей входных данных

Многие workflows ожидают входные данные. Их можно передать через тело запроса при запуске.

run_payload = {
    "workflowData": {
        
Данные для первого узла (обычно триггера или узла "Webhook").
        "startNode": "Webhook Node", 
Имя узла, принимающего данные
        "nodeData": {
            "Webhook Node": [
                [
                    {
                        "json": {"orderId": 12345, "customer": "John Doe"},
                        "binary": {}
                    }
                ]
            ]
        }
    }
}

response = requests.post(f"{N8N_URL}/api/v1/workflows/{new_workflow_id}/run", json=run_payload, headers=headers)
print(json.dumps(response.json(), indent=2))

Интеграция с внешними системами и вебхуки

N8n может не только вызывать внешние API, но и сам выступать в качестве вебхук-приемника. Для этого в workflow используется узел «Webhook». После активации такого workflow n8n предоставляет уникальный URL, на который можно отправлять POST, GET или другие HTTP-запросы для запуска процесса. Управление этими вебхуками также частично доступно через API, например, через получение информации о workflow. Для создания сложных интеграционных панелей можно использовать API для сбора статистики по выполнениям, статусам workflows и оперативного управления ими.

Ограничения, квоты и лучшие практики

Производительность API зависит от конфигурации сервера n8n и базы данных. При работе с большим количеством execution записей необходимо использовать пагинацию. Для предотвращения случайного удаления или деактивации критичных процессов рекомендуется использовать систему тегирования или вести внешний журнал изменений. Синхронный запуск (/run) имеет таймаут, который может быть настроен в конфигурации n8n. Для длительных операций всегда используйте асинхронный эндпоинт (/execute). Регулярно делайте бэкапы workflows через API (GET запросы) и храните их в системе контроля версий.

Сравнение эндпоинтов запуска workflow

Эндпоинт	Тип запуска	Возвращаемый ответ	Таймаут	Использование
POST /api/v1/workflows/{id}/run	Синхронный	Данные результата выполнения всего workflow.	Да (настраивается)	Быстрые операции, где результат нужен немедленно (генерация отчета, проверка).
POST /api/v1/workflows/{id}/execute	Асинхронный	ID выполнения (executionId).	Нет	Длительные процессы (обработка файлов, массовая рассылка).

Ответы на часто задаваемые вопросы (FAQ)

Как получить API-ключ в n8n?

В веб-интерфейсе n8n перейдите в раздел «Settings» (Настройки) -> «API». Нажмите «Create new API key». Скопируйте сгенерированный ключ и сохраните его в безопасном месте, так как позже его будет невозможно просмотреть полностью, только перегенерировать.

Можно ли запустить workflow с определенной версией?

Да, n8n поддерживает версионирование workflows. При обновлении workflow через API создается новая версия. Для запуска конкретной версии можно использовать параметр versionId в теле запроса к эндпоинту /run или /execute.

Как отслеживать статус асинхронного выполнения?

После асинхронного запуска вы получите executionId. Для проверки статуса периодически опрашивайте эндпоинт GET /api/v1/executions/{executionId}. В ответе будет поле status (например, «running», «success», «error», «waiting»).

Как передавать файлы (бинарные данные) при запуске workflow через API?

Для передачи файлов необходимо кодировать их в base64 и включать в поле binary объекта данных узла. Структура должна соответствовать ожиданиям узла, принимающего файлы (например, «Read Binary Files»).

Почему мой запрос к API возвращает ошибку 401?

Наиболее частая причина — отсутствие, неверный или просроченный API-ключ в заголовке X-N8N-API-KEY. Убедитесь, что ключ указан верно и что у пользователя, для которого создан ключ, есть необходимые права доступа.

Можно ли использовать n8n API для массового импорта/экспорта workflows?

Да, это одна из сильных сторон API. Вы можете получить все workflows (GET /api/v1/workflows), а затем использовать полученные JSON-определения для восстановления на другой инстанции n8n через POST запрос. Это основа для переноса конфигураций между средами (dev/stage/prod).

Как ограничить доступ к API для определенных IP-адресов?

Эта функциональность не реализована на уровне самого n8n. Необходимо настраивать брандмауэр, обратный прокси-сервер (например, nginx) или использовать сетевые политики на уровне инфраструктуры для ограничения доступа к порту, на котором работает n8n.

Заключение

REST API n8n является мощным инструментом, который трансформирует платформу из инструмента визуальной автоматизации в полноценный компонент корпоративной ИТ-инфраструктуры. Он позволяет программировать жизненный цикл рабочих процессов, интегрировать их выполнение в сторонние системы и создавать сложные управляющие надстройки. Понимание и грамотное использование эндпоинтов для управления workflows, executions и credentials открывает путь к построению отказоустойчивых, масштабируемых и легко управляемых конвейеров автоматизации. Для успешного применения необходимо уделять внимание безопасности (API-ключи, HTTPS), выбирать правильный метод запуска (синхронный/асинхронный) и реализовывать обработку ошибок в клиентском коде.