# n8n REST API - Полная документация

**Версия API:** v1
**Дата документации:** 2025-12-25
**Источник:** Официальная документация n8n через Context7

---

## 📋 Содержание

### Основная информация
- [00-INDEX.md](./00-INDEX.md) - Этот файл (навигация по всей документации)
- [01-OVERVIEW.md](./01-OVERVIEW.md) - Общий обзор API
- [02-AUTHENTICATION.md](./02-AUTHENTICATION.md) - Аутентификация и безопасность
- [03-PAGINATION.md](./03-PAGINATION.md) - Пагинация результатов

### API Endpoints

#### Workflows (Рабочие процессы)
- [10-WORKFLOWS-API.md](./10-WORKFLOWS-API.md) - Полная документация Workflows API
  - GET /api/v1/workflows - Получить список workflows
  - GET /api/v1/workflows/{id} - Получить конкретный workflow
  - POST /api/v1/workflows - Создать новый workflow
  - PUT /api/v1/workflows/{id} - Обновить workflow
  - PATCH /api/v1/workflows/{id} - Частично обновить workflow
  - DELETE /api/v1/workflows/{id} - Удалить workflow
  - PUT /api/v1/workflows/{id}/activate - Активировать workflow
  - PUT /api/v1/workflows/{id}/deactivate - Деактивировать workflow

#### Executions (Выполнения)
- [20-EXECUTIONS-API.md](./20-EXECUTIONS-API.md) - Полная документация Executions API
  - GET /api/v1/executions - Получить список executions
  - GET /api/v1/executions/{id} - Получить конкретный execution
  - DELETE /api/v1/executions/{id} - Удалить execution
  - POST /api/v1/executions/{id}/retry - Повторить failed execution

#### Credentials (Учетные данные)
- [30-CREDENTIALS-API.md](./30-CREDENTIALS-API.md) - Полная документация Credentials API
  - GET /api/v1/credentials - Получить список credentials
  - GET /api/v1/credentials/{id} - Получить конкретный credential
  - POST /api/v1/credentials - Создать новый credential
  - PUT /api/v1/credentials/{id} - Обновить credential
  - DELETE /api/v1/credentials/{id} - Удалить credential

#### Tags (Теги)
- [40-TAGS-API.md](./40-TAGS-API.md) - Полная документация Tags API
  - GET /api/v1/tags - Получить список tags
  - GET /api/v1/tags/{id} - Получить конкретный tag
  - POST /api/v1/tags - Создать новый tag
  - PUT /api/v1/tags/{id} - Обновить tag
  - DELETE /api/v1/tags/{id} - Удалить tag

### Дополнительные ресурсы
- [n8n API Documentation](https://docs.n8n.io/api/) - Официальная документация n8n API

---

## 🚀 Быстрый старт

### Базовый URL

**n8n Cloud:**
```
https://{instance}.app.n8n.cloud/api/v1
```

**Self-Hosted:**
```
{url}/api/v1
```

### Аутентификация

Все запросы требуют API ключ в заголовке:

```bash
curl -X GET \
  'https://your-instance.app.n8n.cloud/api/v1/workflows' \
  -H 'X-N8N-API-KEY: your_api_key_here' \
  -H 'Accept: application/json'
```

### Пример: Получить список workflows

```bash
GET https://your-instance.app.n8n.cloud/api/v1/workflows
```

**Response:**
```json
{
  "data": [
    {
      "id": "123",
      "name": "My Workflow",
      "active": true,
      "createdAt": "2025-01-01T00:00:00.000Z",
      "updatedAt": "2025-01-01T00:00:00.000Z"
    }
  ]
}
```

---

## 📊 Категории API

### Workflows API
Управление рабочими процессами (workflows):
- Создание, чтение, обновление, удаление workflows
- Активация и деактивация workflows
- Получение полной структуры workflow с узлами и связями

### Executions API
Управление выполнениями workflows:
- Просмотр истории выполнений
- Получение детальной информации о выполнении
- Удаление записей выполнений
- Повторное выполнение failed workflows

### Credentials API
Управление учетными данными:
- Создание credentials для интеграций
- Обновление API ключей и токенов
- Удаление credentials
- Управление доступом к credentials

### Tags API
Организация workflows с помощью тегов:
- Создание и управление тегами
- Присвоение тегов workflows
- Фильтрация workflows по тегам

---

## 🔑 Ключевые особенности

### 1. Полная совместимость
- Совместимость с n8n версии 1.82.3+
- Поддержка как Cloud, так и Self-Hosted инстансов

### 2. RESTful архитектура
- Стандартные HTTP методы (GET, POST, PUT, PATCH, DELETE)
- JSON формат запросов и ответов
- Понятная структура endpoints

### 3. Аутентификация через API ключ
- Простая аутентификация через заголовок X-N8N-API-KEY
- Безопасное управление доступом

### 4. Пагинация
- Поддержка pagination для больших наборов данных
- Настраиваемые лимиты результатов

### 5. Фильтрация
- Фильтрация workflows по статусу (active/inactive)
- Фильтрация по тегам
- Поиск по различным критериям

---

## 📝 Формат документации

Каждый метод API документирован в следующем формате:

### Структура документа метода

```markdown
## HTTP_METHOD /endpoint/path

### Описание
Краткое описание что делает метод

### HTTP Метод
GET | POST | PUT | PATCH | DELETE

### Endpoint
Полный путь к endpoint

### Параметры

#### Path Parameters (Параметры пути)
- **parameter_name** (тип) - Required/Optional - Описание

#### Query Parameters (Параметры запроса)
- **parameter_name** (тип) - Required/Optional - Описание

#### Request Headers (Заголовки запроса)
- **Header-Name** (тип) - Required/Optional - Описание

#### Request Body (Тело запроса)
Структура JSON для POST/PUT/PATCH запросов

### Примеры

#### Пример запроса (curl)
```bash
curl command
```

#### Пример запроса (JavaScript)
```javascript
fetch example
```

#### Пример тела запроса
```json
{...}
```

### Ответы

#### Success Response (2xx)
Описание успешного ответа с примером

#### Error Responses (4xx, 5xx)
Описание возможных ошибок

### Примечания
Дополнительная информация, ограничения, best practices
```

---

## 🎯 Структура проекта документации

```
docs/n8n-api-docs/
├── 00-INDEX.md                 # Этот файл - навигация
├── 01-OVERVIEW.md              # Общий обзор API
├── 02-AUTHENTICATION.md        # Аутентификация
├── 03-PAGINATION.md            # Пагинация
├── 10-WORKFLOWS-API.md         # Workflows API (полная)
├── 20-EXECUTIONS-API.md        # Executions API (полная)
├── 30-CREDENTIALS-API.md       # Credentials API (полная)
└── 40-TAGS-API.md              # Tags API (полная)
```

---

## 🔍 Как пользоваться документацией

### 1. Начните с обзора
Прочитайте [01-OVERVIEW.md](./01-OVERVIEW.md) для понимания общей архитектуры API.

### 2. Настройте аутентификацию
Изучите [02-AUTHENTICATION.md](./02-AUTHENTICATION.md) для настройки доступа к API.

### 3. Выберите нужный endpoint
Найдите нужный метод в соответствующем разделе:
- Работа с workflows → [10-WORKFLOWS-API.md](./10-WORKFLOWS-API.md)
- Просмотр выполнений → [20-EXECUTIONS-API.md](./20-EXECUTIONS-API.md)
- Управление credentials → [30-CREDENTIALS-API.md](./30-CREDENTIALS-API.md)
- Организация с тегами → [40-TAGS-API.md](./40-TAGS-API.md)

### 4. Изучите лучшие практики
См. документацию по конкретным API endpoints в файлах выше для рекомендаций по использованию.

---

## 📌 Важные замечания

### URL Normalization (v0.9.1+)
В нашем MCP сервере реализована автоматическая нормализация URL:
- Сервер автоматически добавляет `/api/v1` к базовому URL
- Не нужно включать `/api/v1` в конфигурацию `n8n_host`
- Поддерживается обратная совместимость

**Правильная конфигурация:**
```json
{
  "n8n_host": "https://your-instance.app.n8n.cloud",
  "n8n_api_key": "your_key"
}
```

**Неправильная конфигурация (но работает благодаря нормализации):**
```json
{
  "n8n_host": "https://your-instance.app.n8n.cloud/api/v1/",
  "n8n_api_key": "your_key"
}
```

---

## 🆘 Поддержка

### Официальная документация n8n
- [n8n API Documentation](https://docs.n8n.io/api/)
- [n8n REST API Reference](https://docs.n8n.io/api/api-reference/)

### Наш MCP сервер
- [GitHub Repository](https://github.com/salacoste/mcp-n8n-workflow-builder)
- [Issues](https://github.com/salacoste/mcp-n8n-workflow-builder/issues)

---

**Последнее обновление:** 2025-12-25
**Версия документации:** 1.0
**Подготовлено:** James (Dev Agent) с использованием Context7 MCP Server