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

---
phase: 06-n8n-api-access
plan: 01
type: execute
wave: 1
depends_on: []
files_modified: []
autonomous: false
user_setup:
  - service: n8n
    why: "API authentication for workflow access"
    env_vars:
      - name: N8N_API_KEY
        source: "n8n UI: Settings > n8n API > Create an API key"
      - name: N8N_HOST
        source: "n8n instance URL (e.g., http://192.168.1.x:5678)"
    dashboard_config:
      - task: "Create API key with label 'Claude Code'"
        location: "n8n UI > Settings > n8n API"

must_haves:
  truths:
    - "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"
  artifacts:
    - path: ".env.n8n-api"
      provides: "API credentials for n8n access"
      contains: "N8N_API_KEY"
  key_links:
    - from: "curl command"
      to: "n8n /api/v1/workflows"
      via: "X-N8N-API-KEY header"
      pattern: "X-N8N-API-KEY.*n8n_api"
    - from: "curl command"
      to: "n8n /api/v1/executions"
      via: "X-N8N-API-KEY header"
      pattern: "X-N8N-API-KEY.*n8n_api"
---

<objective>
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
</objective>

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

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/06-n8n-api-access/06-RESEARCH.md
</context>

<tasks>

<task type="checkpoint:human-action" gate="blocking">
  <name>Task 1: Create n8n API Key</name>
  <action>
    User must create an API key in n8n UI. This cannot be automated - first API key must be created through the web interface.
  </action>
  <instructions>
    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_)
  </instructions>
  <resume-signal>Provide N8N_HOST and N8N_API_KEY values</resume-signal>
</task>

<task type="auto">
  <name>Task 2: Verify API Access and Document Commands</name>
  <files>.env.n8n-api</files>
  <action>
    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.
  </action>
  <verify>
    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
  </verify>
  <done>
    - 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)
  </done>
</task>

</tasks>

<verification>
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
</verification>

<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>

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