docs(phase-6): research n8n API access

Phase 6: n8n API Access - n8n REST API capabilities identified - Authentication patterns documented (X-N8N-API-KEY header) - Workflow CRUD operations researched - Execution history access patterns found - Common pitfalls catalogued (activation timeout, public vs private endpoints) - No official SDK exists - raw HTTP client required Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-02-03 08:04:36 -05:00
parent c6abf62021
commit bc26a7bc88
1 changed files with 413 additions and 0 deletions
@@ -0,0 +1,413 @@
 # Phase 6: n8n API Access - Research
 **Researched:** 2026-02-03
 **Domain:** n8n REST API integration, workflow automation API
 **Confidence:** MEDIUM
 ## Summary
 n8n provides a public REST API that allows programmatic access to workflows, executions, and credentials. The API is available on self-hosted instances (including Docker deployments) and requires API key authentication via the X-N8N-API-KEY header.
 **Primary recommendation:** Use n8n's native REST API with a simple HTTP client (axios or node-fetch) to read workflow JSON, update workflows, and query execution history. No SDK exists, but the API is straightforward RESTful JSON. Create API key through UI (Settings > n8n API), store securely, and use for all Claude Code operations.
 **Key finding:** There is NO official n8n API client library/SDK. All API interactions will be raw HTTP requests (curl, axios, fetch). The API documentation exists but is not comprehensive - expect to discover endpoints through community examples and experimentation.
 ## Standard Stack
 The established libraries/tools for n8n API integration:
 ### Core
 | Library | Version | Purpose | Why Standard |
 |---------|---------|---------|--------------|
 | n8n REST API | Native | Workflow CRUD, execution history | Built-in to all n8n instances |
 | axios | ^1.6.0 | HTTP client for API calls | Most common in Node.js ecosystem, better error handling than fetch |
 | node-fetch | ^3.3.0 | Alternative HTTP client | Native fetch API, simpler than axios |
 ### Supporting
 | Library | Version | Purpose | When to Use |
 |---------|---------|---------|-------------|
 | dotenv | ^16.0.0 | Environment variable management | Store API key and n8n host URL |
 | @types/node | ^20.0.0 | TypeScript types for Node.js | If writing TypeScript helper scripts |
 ### Alternatives Considered
 | Instead of | Could Use | Tradeoff |
 |------------|-----------|----------|
 | REST API | n8n MCP server | MCP is overkill for v1.1 (marked out of scope in REQUIREMENTS.md) |
 | axios | curl via bash | Less maintainable, harder error handling, but requires no dependencies |
 | API key auth | OAuth | n8n doesn't support OAuth for its own API, only for external integrations |
 **Installation:**
 ```bash
 # For helper scripts (if needed)
 npm install axios dotenv
 # Or for native fetch approach (Node.js 18+)
 npm install node-fetch
 ```
 **Note:** For Claude Code workflow iterations, curl is sufficient and requires no installation.
 ## Architecture Patterns
 ### Recommended Project Structure
 ```
 scripts/
 ├── n8n-api/
 │   ├── config.js           # API key, host URL configuration
 │   ├── client.js           # Reusable HTTP client wrapper
 │   ├── workflows.js        # Workflow CRUD operations
 │   └── executions.js       # Execution history queries
 .env                        # API credentials (gitignored)
 ```
 ### Pattern 1: API Key Authentication
 **What:** Pass API key in X-N8N-API-KEY header for all requests
 **When to use:** Every n8n API call
 **Example:**
 ```bash
 # Source: Community examples + official docs
 curl -X GET 'http://localhost:5678/api/v1/workflows' \
  -H 'accept: application/json' \
  -H 'X-N8N-API-KEY: your-api-key-here'
 ```
 **TypeScript/JavaScript:**
 ```javascript
 // Source: Community patterns
 const axios = require('axios');
 const n8nClient = axios.create({
  baseURL: process.env.N8N_HOST || 'http://localhost:5678',
  headers: {
    'X-N8N-API-KEY': process.env.N8N_API_KEY,
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  }
 });
 // Get all workflows
 const workflows = await n8nClient.get('/api/v1/workflows');
 // Get specific workflow
 const workflow = await n8nClient.get(`/api/v1/workflows/${workflowId}`);
 // Update workflow
 const updated = await n8nClient.patch(`/api/v1/workflows/${workflowId}`, {
  nodes: [...],
  connections: {...}
 });
 ```
 ### Pattern 2: Workflow Read-Modify-Write
 **What:** Fetch current workflow JSON, modify locally, push back via API
 **When to use:** Making incremental changes to existing workflows
 **Example:**
 ```javascript
 // Source: Community workflow manager patterns
 async function updateWorkflowNode(workflowId, nodeName, newParams) {
  // 1. Fetch current workflow
  const { data: workflow } = await n8nClient.get(`/api/v1/workflows/${workflowId}`);
  // 2. Find and modify node
  const node = workflow.nodes.find(n => n.name === nodeName);
  if (node) {
    node.parameters = { ...node.parameters, ...newParams };
  }
  // 3. Push updated workflow
  const { data: updated } = await n8nClient.patch(`/api/v1/workflows/${workflowId}`, {
    nodes: workflow.nodes,
    connections: workflow.connections,
    settings: workflow.settings
  });
  return updated;
 }
 ```
 ### Pattern 3: Execution History Query
 **What:** Query recent executions to verify workflow behavior
 **When to use:** Testing after workflow updates, debugging failures
 **Example:**
 ```javascript
 // Source: Community patterns for execution monitoring
 async function getRecentExecutions(workflowId, limit = 10) {
  const { data } = await n8nClient.get('/api/v1/executions', {
    params: {
      workflowId: workflowId,
      limit: limit,
      // Filter by status if needed: status=success, status=error
    }
  });
  return data.data.map(exec => ({
    id: exec.id,
    status: exec.finished ? 'success' : exec.stoppedAt ? 'error' : 'running',
    startedAt: exec.startedAt,
    stoppedAt: exec.stoppedAt,
    error: exec.data?.resultData?.error
  }));
 }
 ```
 ### Anti-Patterns to Avoid
 - **Direct workflow.json file editing:** Changes won't take effect until n8n restarts; use API instead
 - **Storing API key in workflow:** Use environment variables or secure credential store
 - **Polling for execution completion:** n8n executions can be long-running; better to check status on-demand
 - **Activating workflows via API during updates:** Known timeout issues; update workflow while inactive, activate manually via UI
 ## Don't Hand-Roll
 Problems that look simple but have existing solutions:
 | Problem | Don't Build | Use Instead | Why |
 |---------|-------------|-------------|-----|
 | API key management | Hardcoded keys in scripts | Environment variables (.env + dotenv) | Security, portability, secrets rotation |
 | HTTP retry logic | Manual retry loops | axios-retry or built-in retry config | Handles exponential backoff, max retries, error detection |
 | Workflow JSON validation | Custom schema validator | n8n API validation on PATCH | n8n will reject invalid workflow structure |
 | Execution log parsing | Custom log processors | n8n API returns structured execution data | Execution data already includes node outputs, errors, timestamps |
 **Key insight:** n8n API has limited documentation, but attempting operations and reading error responses is often more reliable than trying to find docs. The API is forgiving - invalid requests return clear JSON error messages.
 ## Common Pitfalls
 ### Pitfall 1: API Not Enabled on Self-Hosted
 **What goes wrong:** API calls return 404 or unauthorized even with valid key
 **Why it happens:** User assumes API is enabled by default on self-hosted instances
 **How to avoid:**
 - API is enabled by default on modern n8n versions (v1.0+)
 - Create API key via UI: Settings > n8n API > Create an API key
 - No environment variable needed to "enable" API - it's always available
 - If Settings > n8n API is missing, n8n version may be too old (upgrade to v1.0+)
 **Warning signs:** 404 on `/api/v1/workflows`, "API access blocked" messages
 ### Pitfall 2: Using Private vs Public Endpoints
 **What goes wrong:** Found endpoint pattern in n8n source code that returns 401/403
 **Why it happens:** n8n has both public API endpoints (/api/v1/*) and private internal endpoints (/rest/*)
 **How to avoid:**
 - Use `/api/v1/*` endpoints for public API access
 - Avoid `/rest/*` endpoints (internal, may require different auth or be restricted)
 - Community examples sometimes reference `/rest/workflows` - this is NOT the public API
 - Official public API base: `http(s)://your-n8n-host/api/v1/`
 **Warning signs:** Authorization errors despite valid API key, endpoints working in browser but not via API
 ### Pitfall 3: Workflow Activation via API Timeout
 **What goes wrong:** PATCH request to activate workflow times out, workflow stays inactive
 **Why it happens:** Known n8n issue (GitHub #7258) - activation via API can timeout on some instances
 **How to avoid:**
 - Update workflow while inactive
 - Activate manually via n8n UI after making changes
 - If automation is critical, use n8n's built-in n8n node to activate workflows from another workflow
 - Monitor for timeout (>30s response time), fallback to manual activation
 **Warning signs:** API request hangs, workflow.active: true in response but UI shows inactive
 ### Pitfall 4: Missing Execution Logs
 **What goes wrong:** `/api/v1/executions` returns empty or stale data
 **Why it happens:** n8n execution pruning deletes old executions (default: 14 days)
 **How to avoid:**
 - Check execution retention settings: Environment variable `EXECUTIONS_DATA_PRUNE_MAX_AGE` (default: 336 hours = 14 days)
 - For recent executions (<14 days), verify workflow has actually run
 - Execution data is only saved if workflow execution completes (running workflows won't appear)
 - Use `?limit=N` parameter to control result count (default: 20, max: 250)
 **Warning signs:** Executions list is empty but workflow has run recently, old executions missing
 ### Pitfall 5: Credentials in Workflow JSON
 **What goes wrong:** API returns workflow with credential IDs but not actual credential values
 **Why it happens:** n8n API protects credential values from exposure
 **How to avoid:**
 - Workflow JSON contains credential IDs, not actual keys/tokens
 - To update credentials, use separate credentials API endpoints
 - Don't try to extract credential values from workflow JSON (they're not there)
 - If cloning workflows between instances, credentials must be recreated manually
 **Warning signs:** Workflow nodes reference credentials but values are missing/null
 ## Code Examples
 Verified patterns from official sources and community:
 ### Creating API Key (UI)
 **Source:** [n8n Authentication Docs](https://docs.n8n.io/api/authentication/)
 ```
 1. Log in to n8n
 2. Go to Settings > n8n API
 3. Select "Create an API key"
 4. Choose a Label (e.g., "Claude Code")
 5. Set Expiration time (or "Never" for development)
 6. Copy "My API Key" - this is shown ONCE
 7. Store in secure location (.env file, password manager)
 ```
 ### Get All Workflows
 ```bash
 # Source: Community examples, Hostinger tutorial
 curl -X GET 'http://localhost:5678/api/v1/workflows' \
  -H 'accept: application/json' \
  -H 'X-N8N-API-KEY: n8n_api_1234567890abcdef...'
 ```
 **Response:**
 ```json
 {
  "data": [
    {
      "id": "1",
      "name": "Telegram Docker Bot",
      "active": true,
      "createdAt": "2026-01-15T10:30:00.000Z",
      "updatedAt": "2026-02-01T14:20:00.000Z",
      "nodes": [...],
      "connections": {...}
    }
  ]
 }
 ```
 ### Get Specific Workflow
 ```bash
 # Source: Community patterns
 curl -X GET 'http://localhost:5678/api/v1/workflows/1' \
  -H 'accept: application/json' \
  -H 'X-N8N-API-KEY: n8n_api_...'
 ```
 ### Update Workflow (Partial)
 ```bash
 # Source: Community workflow manager patterns
 curl -X PATCH 'http://localhost:5678/api/v1/workflows/1' \
  -H 'accept: application/json' \
  -H 'X-N8N-API-KEY: n8n_api_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "nodes": [...updated nodes array...],
    "connections": {...updated connections...}
  }'
 ```
 ### Get Execution History
 ```bash
 # Source: Community monitoring patterns
 curl -X GET 'http://localhost:5678/api/v1/executions?workflowId=1&limit=10' \
  -H 'accept: application/json' \
  -H 'X-N8N-API-KEY: n8n_api_...'
 ```
 **Response:**
 ```json
 {
  "data": [
    {
      "id": "123",
      "finished": true,
      "mode": "webhook",
      "startedAt": "2026-02-03T08:15:00.000Z",
      "stoppedAt": "2026-02-03T08:15:02.000Z",
      "workflowId": "1",
      "status": "success"
    }
  ],
  "nextCursor": "eyJsYXN0SWQiOiIxMjMifQ=="
 }
 ```
 ### Pagination Pattern
 **Source:** [n8n API Pagination Docs](https://docs.n8n.io/api/pagination/)
 ```javascript
 // n8n uses cursor-based pagination
 async function getAllExecutions(workflowId) {
  let allExecutions = [];
  let cursor = null;
  do {
    const params = { workflowId, limit: 100 };
    if (cursor) params.cursor = cursor;
    const { data } = await n8nClient.get('/api/v1/executions', { params });
    allExecutions.push(...data.data);
    cursor = data.nextCursor;
  } while (cursor);
  return allExecutions;
 }
 ```
 **Note:** Default page size is 100, maximum is 250.
 ## State of the Art
 | Old Approach | Current Approach | When Changed | Impact |
 |--------------|------------------|--------------|--------|
 | Manual workflow JSON editing | REST API for workflow updates | n8n v1.0 (2023) | API-first workflow management is now standard |
 | No public API | Public REST API with API keys | n8n v1.0 (2023) | Programmatic access without database manipulation |
 | Polling for executions | Cursor-based pagination | Recent (2025+) | Efficient execution history retrieval |
 | Webhook-only workflow triggers | API playground for testing | Recent (2025+) | Interactive API testing built-in |
 **Deprecated/outdated:**
 - `/rest/*` endpoint patterns (internal API, not public) - Use `/api/v1/*` instead
 - Trial user API access (no longer available) - Self-hosted or paid plans only
 - API key via environment variable - Create via UI Settings instead
 ## Open Questions
 Things that couldn't be fully resolved:
 1. **API Endpoint Versioning**
   - What we know: Current endpoints are `/api/v1/*`
   - What's unclear: Will n8n introduce `/api/v2/*`? How to handle version transitions?
   - Recommendation: Stick with v1 endpoints, monitor n8n release notes for API changes
 2. **Rate Limiting on Self-Hosted**
   - What we know: n8n Cloud has rate limits, self-hosted documentation mentions limits exist
   - What's unclear: Exact limits for self-hosted API, whether configurable
   - Recommendation: Assume conservative limit (~100 req/min), add retry logic, monitor for 429 responses
 3. **Workflow Activation Reliability**
   - What we know: GitHub issue #7258 shows activation via API can timeout
   - What's unclear: Is this fixed in recent versions? Workarounds?
   - Recommendation: Test on target n8n version, fallback to manual activation if needed
 4. **Execution Log Detail Level**
   - What we know: Executions API returns status, timestamps, basic error info
   - What's unclear: Full node-by-node execution data available? Structured logs?
   - Recommendation: Test execution response structure, may need to fetch individual execution details
 ## Sources
 ### Primary (HIGH confidence)
 - [n8n API Documentation](https://docs.n8n.io/api/) - Official API overview
 - [n8n API Authentication](https://docs.n8n.io/api/authentication/) - API key creation and usage
 - [n8n API Pagination](https://docs.n8n.io/api/pagination/) - Cursor-based pagination
 - [n8n API Playground](https://docs.n8n.io/api/using-api-playground/) - Interactive API testing
 - [n8n API Reference](https://docs.n8n.io/api/api-reference/) - Endpoint documentation
 ### Secondary (MEDIUM confidence)
 - [n8n API Integration Guide (Hostinger)](https://www.hostinger.com/tutorials/n8n-api) - Self-hosted setup examples
 - [n8n Workflow Manager Template](https://n8n.io/workflows/4166-n8n-workflow-manager-api/) - Community workflow management patterns
 - [Create Dynamic Workflows via API](https://n8n.io/workflows/4544-create-dynamic-workflows-programmatically-via-webhooks-and-n8n-api/) - Programmatic workflow creation examples
 - [n8n API Rate Limits Guide (Refactix)](https://refactix.com/ai-automation-productivity/n8n-api-pagination-rate-limits-retries) - Rate limiting best practices
 - [7 Common n8n Workflow Mistakes (Medium, 2026)](https://medium.com/@juanm.acebal/7-common-n8n-workflow-mistakes-that-can-break-your-automations-9638903fb076) - Error handling patterns
 ### Tertiary (LOW confidence)
 - [n8n GitHub Issue #7258](https://github.com/n8n-io/n8n/issues/7258) - Workflow activation timeout issue
 - [n8n GitHub Issue #14748](https://github.com/n8n-io/n8n/issues/14748) - GET /executions status filtering issue
 - Community forum discussions on `/rest/workflows` API access issues
 ## Metadata
 **Confidence breakdown:**
 - Standard stack: MEDIUM - No official SDK exists, patterns derived from community usage
 - Architecture: MEDIUM - Verified endpoint patterns from docs, response structures from community examples
 - Pitfalls: MEDIUM - Mix of documented issues (GitHub) and community-reported problems
 **Research date:** 2026-02-03
 **Valid until:** ~30 days (n8n API is relatively stable, check release notes for breaking changes)
 **Notes:**
 - n8n API documentation is sparse - expect to discover endpoint behavior through experimentation
 - Community forum and GitHub issues are valuable sources for undocumented behavior
 - Official OpenAPI spec does not exist; API playground is interactive but not exportable
 - This research assumes n8n v1.0+ (self-hosted via Docker on Unraid)