Phase 14: Unraid API Access - Context

Gathered: 2026-02-08 Status: Ready for planning

## Phase Boundary

Validate GraphQL API connectivity and establish secure authentication from n8n container to Unraid host. Includes credential storage, network connectivity verification, test query execution, and container ID format documentation. Does NOT include mutation calls (Phase 15) or batch operations (Phase 16).

## Implementation Decisions

Credential management

Dual storage: .env.unraid-api file (for CLI/deploy scripts) + n8n credential (for workflow nodes)
.env.unraid-api contains both UNRAID_API_KEY and UNRAID_HOST (mirrors .env.n8n-api pattern)
Phase includes documentation for creating the Unraid API key in WebGUI with correct permissions
File is gitignored

Network connectivity

User runs Unraid on default WebGUI ports — GraphQL API assumed on same port
HTTP vs HTTPS and self-signed cert handling needs to be figured out during research/testing
Connectivity verification done purely through n8n workflow nodes — no separate test script
Host URL stored in UNRAID_HOST env var — user configures during setup

GraphQL query design

Document only the queries/mutations relevant to update sync — not the full Docker schema
Container ID format mapping needs research — we don't know how Unraid identifies containers in GraphQL yet
GraphQL API contract documented in ARCHITECTURE.md alongside existing Docker API contract

Error handling & feedback

Clear, descriptive error messages on failure (what failed, why, what to check)
Use existing error logging system — same pattern as Docker API errors, not a separate log category
Phase 14 tests connectivity only — permission validation happens naturally in Phase 15 when mutations are attempted
No user-facing Telegram health check command for Unraid API — errors surface naturally during sync failures

Claude's Discretion

n8n credential type selection (based on Unraid GraphQL API's actual auth mechanism)
Network approach for n8n container reaching Unraid host (host IP, Docker networking, etc.)
What fields to include in the test query (based on what downstream phases need)

## Specific Ideas

Mirror the .env.n8n-api pattern for credential file naming and structure
Keep the ARCHITECTURE.md GraphQL section consistent with the existing Docker API documentation style

## Deferred Ideas

None — discussion stayed within phase scope

Phase: 14-unraid-api-access Context gathered: 2026-02-08

2.6 KiB Raw Blame History