unraid-docker-manager/.planning/phases/06-n8n-api-access/06-01-PLAN.md

phase, plan, type, wave, depends_on, files_modified, autonomous, user_setup, must_haves

phase	plan	type	wave	depends_on	files_modified	autonomous	user_setup	must_haves
06-n8n-api-access	01	execute	1			false	service why env_vars dashboard_config n8n API authentication for workflow access name source N8N_API_KEY n8n UI: Settings > n8n API > Create an API key name source N8N_HOST n8n instance URL (e.g., http://192.168.1.x:5678) task location Create API key with label 'Claude Code' n8n UI > Settings > n8n API	truths artifacts key_links Claude Code can authenticate against n8n API with API key Claude Code can retrieve current workflow JSON Claude Code can push workflow changes that take effect Claude Code can view execution history with success/failure status path provides contains .env.n8n-api API credentials for n8n access N8N_API_KEY from to via pattern curl command n8n /api/v1/workflows X-N8N-API-KEY header X-N8N-API-KEY.*n8n_api from to via pattern curl command n8n /api/v1/executions X-N8N-API-KEY header X-N8N-API-KEY.*n8n_api

Enable Claude Code to programmatically access n8n workflows via REST API

Purpose: Faster development iteration on all subsequent phases. Instead of manual n8n UI changes, Claude can read, modify, and verify workflows directly.

Output: Verified API access with documented curl commands for workflow CRUD and execution history

<execution_context> @/home/luc/.claude/get-shit-done/workflows/execute-plan.md @/home/luc/.claude/get-shit-done/templates/summary.md </execution_context>

@.planning/PROJECT.md @.planning/ROADMAP.md @.planning/STATE.md @.planning/phases/06-n8n-api-access/06-RESEARCH.md Task 1: Create n8n API Key User must create an API key in n8n UI. This cannot be automated - first API key must be created through the web interface. 1. Open n8n in your browser (e.g., http://192.168.1.x:5678) 2. Go to Settings > n8n API 3. Click "Create an API key" 4. Set Label: "Claude Code" 5. Set Expiration: "Never" (for development) or your preferred duration 6. Copy the API key - it is shown ONCE and cannot be retrieved later 7. Provide the following to continue: - N8N_HOST: Your n8n URL (e.g., http://192.168.1.100:5678) - N8N_API_KEY: The API key you just created (starts with n8n_api_) Provide N8N_HOST and N8N_API_KEY values Task 2: Verify API Access and Document Commands .env.n8n-api Using the provided N8N_HOST and N8N_API_KEY, verify all 4 API requirements:

1. **API-01: Authentication** - Test that API key authenticates successfully
   ```bash
   curl -s -X GET "${N8N_HOST}/api/v1/workflows" \
     -H "accept: application/json" \
     -H "X-N8N-API-KEY: ${N8N_API_KEY}" | head -c 200
   ```
   Expected: JSON response with workflow data (not 401/403 error)

2. **API-02: Read Workflow** - Retrieve current Telegram Docker Bot workflow
   ```bash
   # First, list workflows to find the ID
   curl -s -X GET "${N8N_HOST}/api/v1/workflows" \
     -H "accept: application/json" \
     -H "X-N8N-API-KEY: ${N8N_API_KEY}" | jq '.data[] | {id, name}'

   # Then fetch specific workflow
   curl -s -X GET "${N8N_HOST}/api/v1/workflows/{WORKFLOW_ID}" \
     -H "accept: application/json" \
     -H "X-N8N-API-KEY: ${N8N_API_KEY}" | jq '.name, .nodes | length'
   ```
   Expected: Workflow name and node count returned

3. **API-03: Update Workflow** - Test write access with a no-op update
   ```bash
   # Get current workflow, modify nothing substantive, push back
   WORKFLOW=$(curl -s -X GET "${N8N_HOST}/api/v1/workflows/{WORKFLOW_ID}" \
     -H "accept: application/json" \
     -H "X-N8N-API-KEY: ${N8N_API_KEY}")

   # PATCH with same nodes/connections (no-op update to verify write access)
   echo "$WORKFLOW" | jq '{nodes: .nodes, connections: .connections}' | \
     curl -s -X PATCH "${N8N_HOST}/api/v1/workflows/{WORKFLOW_ID}" \
       -H "accept: application/json" \
       -H "X-N8N-API-KEY: ${N8N_API_KEY}" \
       -H "Content-Type: application/json" \
       -d @- | jq '.updatedAt'
   ```
   Expected: Updated timestamp returned (workflow accepted the PATCH)

4. **API-04: Execution History** - View recent workflow runs
   ```bash
   curl -s -X GET "${N8N_HOST}/api/v1/executions?workflowId={WORKFLOW_ID}&limit=5" \
     -H "accept: application/json" \
     -H "X-N8N-API-KEY: ${N8N_API_KEY}" | jq '.data[] | {id, status, startedAt}'
   ```
   Expected: Recent execution records with status (success/error/running)

After verification, create `.env.n8n-api` file (gitignored) with:
```
N8N_HOST=<provided value>
N8N_API_KEY=<provided value>
```

Also update `.gitignore` to include `.env.n8n-api` if not already present.

All 4 curl commands return successful JSON responses: - GET /api/v1/workflows returns 200 with workflow list - GET /api/v1/workflows/{id} returns 200 with full workflow JSON - PATCH /api/v1/workflows/{id} returns 200 with updated timestamp - GET /api/v1/executions returns 200 with execution records - API-01: API key authenticates successfully (no 401/403) - API-02: Can read full workflow JSON including nodes and connections - API-03: Can push workflow changes (PATCH accepted, updatedAt changed) - API-04: Can view execution history with status for each run - .env.n8n-api created with credentials (gitignored) Run the 4 verification curl commands and confirm: 1. Authentication works (no auth errors) 2. Can read the Telegram Docker Bot workflow by ID 3. Can update the workflow (even if just re-pushing same content) 4. Can see execution history for recent bot interactions

<success_criteria> All 4 requirements verified with working curl commands:

• API-01: n8n API key created and accessible (curl returns 200)
• API-02: Claude Code can read workflow via API (full JSON retrieved)
• API-03: Claude Code can update workflow via API (PATCH succeeds)
• API-04: Claude Code can view execution history and logs (executions listed) </success_criteria>

After completion, create `.planning/phases/06-n8n-api-access/06-01-SUMMARY.md`