# Story 7.2: Workflows API Reference Documentation

**Epic:** Epic 7 - API Reference Documentation
**Story Points:** 6
**Priority:** High
**Status:** Ready for Implementation
**Estimated Page Count:** 12-16 pages

---

## User Story

**As a** developer working with the n8n MCP server API
**I want** complete API reference for all workflow operations
**So that** I can programmatically create, manage, and deploy n8n workflows

---

## Story Description

### Current System

With Story 7.1 completed:
- ✅ Architecture overview documented
- ✅ System components explained
- ❌ No detailed API reference for workflows
- ❌ No request/response schemas
- ❌ No code examples for each endpoint
- ❌ No error response documentation

### Enhancement

Create comprehensive Workflows API reference documentation covering all 8 workflow operations:
- **list_workflows** - List workflows with filtering and pagination
- **get_workflow** - Get complete workflow definition
- **create_workflow** - Create new workflow
- **update_workflow** - Update existing workflow
- **delete_workflow** - Delete workflow
- **activate_workflow** - Enable workflow execution
- **deactivate_workflow** - Disable workflow execution
- **execute_workflow** - Manual workflow execution (with limitations)

Each operation documented with:
- Purpose and use cases
- Request parameters (required/optional)
- Response schema
- TypeScript interfaces
- Code examples (multiple languages)
- Error responses
- Rate limiting
- Best practices

---

## Acceptance Criteria

### AC1: list_workflows API Reference
**Given** developers wanting to list workflows
**When** reading the API reference
**Then** they should have complete documentation:

#### 1.1 list_workflows Documentation

**Document:** `docs/api/workflows-api.md#list_workflows`

```markdown
# Workflows API Reference

Complete API reference for all workflow operations (8 methods).

---

## list_workflows

List workflows with optional filtering and pagination.

### Purpose

Retrieve workflow metadata from an n8n instance. This operation returns streamlined metadata only (no full node definitions) for performance (Epic 2 optimization).

### Use Cases

- Dashboard workflow listing
- Inventory management
- Finding workflows by tag
- Monitoring active workflows
- Pre-flight checks before operations

---

### Request

**MCP Tool Name:** `list_workflows`

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| instance | string | No | Instance identifier (uses default if not provided) |
| active | boolean | No | Filter by active status |
| tags | string[] | No | Filter by tag names (AND logic) |
| limit | number | No | Max workflows to return (1-250, default: 100) |
| cursor | string | No | Pagination cursor from previous response |

**TypeScript Interface:**

\`\`\`typescript
interface ListWorkflowsParams {
  instance?: string;
  active?: boolean;
  tags?: string[];
  limit?: number;
  cursor?: string;
}
\`\`\`

**JSON-RPC Request:**

\`\`\`json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_workflows",
    "arguments": {
      "instance": "production",
      "active": true,
      "tags": ["production", "critical"],
      "limit": 50
    }
  }
}
\`\`\`

---

### Response

**Success Response:**

**TypeScript Interface:**

\`\`\`typescript
interface WorkflowListResponse {
  data: Array<{
    id: string;
    name: string;
    active: boolean;
    createdAt: string;      // ISO 8601
    updatedAt: string;      // ISO 8601
    nodes?: number;         // Node count (if available)
    tags?: Array<{
      id: string;
      name: string;
    }>;
  }>;
  nextCursor?: string;      // Present if more data available
}
\`\`\`

**JSON Example:**

\`\`\`json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{
      "type": "text",
      "text": "{
  \"data\": [
    {
      \"id\": \"123\",
      \"name\": \"Email Campaign Automation\",
      \"active\": true,
      \"createdAt\": \"2024-12-15T10:30:00Z\",
      \"updatedAt\": \"2025-01-10T14:20:00Z\",
      \"nodes\": 12,
      \"tags\": [
        { \"id\": \"1\", \"name\": \"production\" },
        { \"id\": \"2\", \"name\": \"marketing\" }
      ]
    },
    {
      \"id\": \"456\",
      \"name\": \"Slack Error Notifications\",
      \"active\": true,
      \"createdAt\": \"2024-11-20T08:15:00Z\",
      \"updatedAt\": \"2024-12-05T16:45:00Z\",
      \"nodes\": 5,
      \"tags\": [
        { \"id\": \"1\", \"name\": \"production\" },
        { \"id\": \"3\", \"name\": \"monitoring\" }
      ]
    }
  ],
  \"nextCursor\": \"eyJvZmZzZXQiOjUwfQ==\"
}"
    }]
  }
}
\`\`\`

**Field Descriptions:**

- **id**: Unique workflow identifier
- **name**: Workflow name (user-defined)
- **active**: Whether workflow is enabled for execution
- **createdAt**: Workflow creation timestamp (UTC)
- **updatedAt**: Last modification timestamp (UTC)
- **nodes**: Number of nodes in workflow (performance optimization)
- **tags**: Array of associated tags
- **nextCursor**: Opaque pagination cursor (base64 encoded)

---

### Pagination

**Cursor-Based Pagination:**

Workflows API uses cursor-based pagination (not offset-based) for stability when data changes.

**First Page:**

\`\`\`json
{
  "limit": 50
}
\`\`\`

**Subsequent Pages:**

\`\`\`json
{
  "limit": 50,
  "cursor": "eyJvZmZzZXQiOjUwfQ=="
}
\`\`\`

**Complete Pagination Example:**

\`\`\`typescript
async function getAllWorkflows(instance?: string): Promise<Workflow[]> {
  const allWorkflows: Workflow[] = [];
  let cursor: string | undefined;

  do {
    const response = await callMCPTool('list_workflows', {
      instance,
      limit: 100,
      cursor
    });

    allWorkflows.push(...response.data);
    cursor = response.nextCursor;
  } while (cursor);

  return allWorkflows;
}
\`\`\`

---

### Error Responses

**Instance Not Found (400):**

\`\`\`json
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Instance 'nonexistent' not found. Available: production, staging"
  }
}
\`\`\`

**Authentication Failed (401):**

\`\`\`json
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32000,
    "message": "API call failed for instance 'production': Authentication failed"
  }
}
\`\`\`

**Invalid Parameters (400):**

\`\`\`json
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Invalid limit: must be between 1 and 250"
  }
}
\`\`\`

---

### Rate Limiting

**n8n API Limits:**
- No official published rate limits
- Recommended: <100 requests/second per instance
- Large result sets may timeout (use pagination)

**Best Practices:**
- Use `limit` parameter to control response size
- Implement exponential backoff on errors
- Cache results when appropriate

---

### Code Examples

**JavaScript/TypeScript:**

\`\`\`typescript
import { Client } from '@modelcontextprotocol/sdk/client/index.js';

const client = new Client({
  name: 'n8n-workflow-manager',
  version: '1.0.0'
});

// List active production workflows
const response = await client.callTool({
  name: 'list_workflows',
  arguments: {
    instance: 'production',
    active: true,
    limit: 50
  }
});

const result = JSON.parse(response.content[0].text);
console.log(`Found ${result.data.length} active workflows`);
\`\`\`

**Python:**

\`\`\`python
import json
import subprocess

def list_workflows(instance=None, active=None, limit=100):
    request = {
        "jsonrpc": "2.0",
        "id": 1,
        "method": "tools/call",
        "params": {
            "name": "list_workflows",
            "arguments": {
                "instance": instance,
                "active": active,
                "limit": limit
            }
        }
    }

    # Send to MCP server via stdio
    result = subprocess.run(
        ['npx', '@bmad-labs/mcp-n8n-workflow-builder'],
        input=json.dumps(request),
        capture_output=True,
        text=True
    )

    response = json.loads(result.stdout)
    return json.loads(response['result']['content'][0]['text'])

# Usage
workflows = list_workflows(instance='production', active=True)
print(f"Found {len(workflows['data'])} workflows")
\`\`\`

---

### Best Practices

**1. Use Appropriate Filters:**

\`\`\`typescript
// ✅ Good: Filter on server side
const active = await list({ active: true });

// ❌ Avoid: Filter on client side
const all = await list({});
const active = all.filter(w => w.active);
\`\`\`

**2. Implement Pagination:**

\`\`\`typescript
// ✅ Good: Paginate through results
let cursor;
do {
  const page = await list({ limit: 100, cursor });
  processWorkflows(page.data);
  cursor = page.nextCursor;
} while (cursor);

// ❌ Avoid: Requesting all at once
const all = await list({ limit: 9999 });  // May timeout/crash
\`\`\`

**3. Cache Results:**

\`\`\`typescript
// ✅ Good: Cache workflow list
const cache = new Map();
const cacheKey = `${instance}-${active}`;

if (cache.has(cacheKey)) {
  return cache.get(cacheKey);
}

const workflows = await list({ instance, active });
cache.set(cacheKey, workflows, { ttl: 60000 });  // 1 minute
return workflows;
\`\`\`

---

## create_workflow

Create a new workflow in an n8n instance.

### Purpose

Programmatically create workflows with nodes, connections, and configuration.

### Use Cases

- Workflow templates and generators
- CI/CD workflow deployment
- Bulk workflow creation
- Workflow cloning across instances

---

### Request

**MCP Tool Name:** `create_workflow`

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| instance | string | No | Instance identifier |
| name | string | Yes | Workflow name |
| nodes | Node[] | Yes | Array of workflow nodes |
| connections | Connections | No | Node connections |
| settings | object | No | Workflow settings |
| staticData | object | No | Static workflow data |
| tags | string[] | No | Tag IDs to assign |
| active | boolean | No | Activate after creation (default: false) |

**TypeScript Interface:**

\`\`\`typescript
interface CreateWorkflowParams {
  instance?: string;
  name: string;
  nodes: Array<{
    name: string;
    type: string;
    typeVersion: number;
    position: [number, number];
    parameters?: Record<string, any>;
    credentials?: Record<string, { id: string; name: string }>;
  }>;
  connections?: {
    [nodeName: string]: {
      main: Array<Array<{
        node: string;
        type: string;
        index: number;
      }>>;
    };
  };
  settings?: {
    timezone?: string;
    errorWorkflow?: string;
    callerPolicy?: string;
  };
  staticData?: Record<string, any>;
  tags?: string[];
  active?: boolean;
}
\`\`\`

**JSON Example:**

\`\`\`json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "create_workflow",
    "arguments": {
      "instance": "staging",
      "name": "Customer Welcome Email",
      "nodes": [
        {
          "name": "Webhook",
          "type": "n8n-nodes-base.webhook",
          "typeVersion": 1,
          "position": [250, 300],
          "parameters": {
            "path": "customer-welcome",
            "responseMode": "onReceived"
          }
        },
        {
          "name": "Send Email",
          "type": "n8n-nodes-base.emailSend",
          "typeVersion": 2,
          "position": [450, 300],
          "parameters": {
            "fromEmail": "welcome@company.com",
            "toEmail": "={{ $json.email }}",
            "subject": "Welcome!",
            "text": "Welcome to our platform, {{ $json.name }}!"
          },
          "credentials": {
            "smtp": {
              "id": "1",
              "name": "Company SMTP"
            }
          }
        }
      ],
      "connections": {
        "Webhook": {
          "main": [[{
            "node": "Send Email",
            "type": "main",
            "index": 0
          }]]
        }
      },
      "active": false
    }
  }
}
\`\`\`

---

### Response

**Success Response:**

Returns complete workflow definition including generated ID.

\`\`\`typescript
interface CreateWorkflowResponse {
  id: string;
  name: string;
  active: boolean;
  nodes: Node[];
  connections: Connections;
  createdAt: string;
  updatedAt: string;
  tags?: Tag[];
  settings?: object;
  staticData?: object;
}
\`\`\`

**JSON Example:**

\`\`\`json
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [{
      "type": "text",
      "text": "{
  \"id\": \"789\",
  \"name\": \"Customer Welcome Email\",
  \"active\": false,
  \"nodes\": [...],
  \"connections\": {...},
  \"createdAt\": \"2025-01-15T10:00:00Z\",
  \"updatedAt\": \"2025-01-15T10:00:00Z\"
}"
    }]
  }
}
\`\`\`

---

### Validation Rules

**Required Fields:**
- `name`: Non-empty string
- `nodes`: Array with at least 1 node

**Node Validation:**
- Each node must have: name, type, typeVersion, position
- Node names must be unique within workflow
- Position must be `[x, y]` array of numbers

**Connection Validation:**
- Referenced nodes must exist
- Connection indices must be valid

**Activation Validation:**
- If `active: true`, workflow must have valid trigger node
- manualTrigger NOT accepted (Epic 1 limitation)
- Valid triggers: scheduleTrigger, webhook, service triggers

---

### Error Responses

**Validation Error:**

\`\`\`json
{
  "jsonrpc": "2.0",
  "id": 2,
  "error": {
    "code": -32602,
    "message": "Workflow validation failed: missing required trigger node"
  }
}
\`\`\`

**Invalid Node Type:**

\`\`\`json
{
  "error": {
    "code": -32000,
    "message": "Unknown node type: 'n8n-nodes-base.invalid'"
  }
}
\`\`\`

---

### Code Examples

**TypeScript - Template Generator:**

\`\`\`typescript
function generateWebhookWorkflow(
  name: string,
  webhookPath: string,
  action: string
): CreateWorkflowParams {
  return {
    name,
    nodes: [
      {
        name: 'Webhook',
        type: 'n8n-nodes-base.webhook',
        typeVersion: 1,
        position: [250, 300],
        parameters: {
          path: webhookPath,
          responseMode: 'onReceived'
        }
      },
      {
        name: 'Process',
        type: 'n8n-nodes-base.code',
        typeVersion: 2,
        position: [450, 300],
        parameters: {
          jsCode: `// ${action}\\nreturn $input.all();`
        }
      }
    ],
    connections: {
      'Webhook': {
        main: [[{ node: 'Process', type: 'main', index: 0 }]]
      }
    },
    active: false
  };
}

// Usage
const workflow = generateWebhookWorkflow(
  'Order Processing',
  'process-order',
  'Validate and store order'
);

await client.callTool({
  name: 'create_workflow',
  arguments: workflow
});
\`\`\`

---

### Best Practices

**1. Validate Before Creating:**

\`\`\`typescript
function validateWorkflow(workflow: CreateWorkflowParams): void {
  if (!workflow.name) throw new Error('Name required');
  if (!workflow.nodes || workflow.nodes.length === 0) {
    throw new Error('At least one node required');
  }

  // Check for duplicate node names
  const names = workflow.nodes.map(n => n.name);
  const duplicates = names.filter((n, i) => names.indexOf(n) !== i);
  if (duplicates.length > 0) {
    throw new Error(`Duplicate node names: ${duplicates.join(', ')}`);
  }

  // Validate connections reference existing nodes
  if (workflow.connections) {
    for (const [source, conn] of Object.entries(workflow.connections)) {
      if (!names.includes(source)) {
        throw new Error(`Connection source '${source}' not found`);
      }
      for (const targets of conn.main) {
        for (const target of targets) {
          if (!names.includes(target.node)) {
            throw new Error(`Connection target '${target.node}' not found`);
          }
        }
      }
    }
  }
}
\`\`\`

**2. Test in Staging First:**

\`\`\`typescript
// Create in staging
const staging = await create({ instance: 'staging', ...workflow });

// Test execution
await testWorkflow(staging.id, 'staging');

// If successful, deploy to production
const production = await create({ instance: 'production', ...workflow });
\`\`\`

**3. Use Connection Transformation:**

\`\`\`typescript
import { transformConnectionsForN8N } from './utils/validation';

// If using array format
const arrayConnections = [
  { source: 'Node1', target: 'Node2', sourceOutput: 0, targetInput: 0 }
];

// Transform to n8n format
workflow.connections = transformConnectionsForN8N(arrayConnections);
\`\`\`

---

## Additional Workflow Operations

The following operations follow similar documentation patterns:

- **get_workflow** - Retrieve complete workflow definition
- **update_workflow** - Modify existing workflow (PATCH support)
- **delete_workflow** - Permanently remove workflow
- **activate_workflow** - Enable workflow for execution
- **deactivate_workflow** - Disable workflow execution
- **execute_workflow** - Manual execution (with limitations)

[Full documentation for each operation continues...]
```

---

## Technical Implementation Notes

### Documentation Structure

```
docs/api/
└── workflows-api.md
    ├── list_workflows
    ├── get_workflow
    ├── create_workflow
    ├── update_workflow
    ├── delete_workflow
    ├── activate_workflow
    ├── deactivate_workflow
    └── execute_workflow
```

### Code Example Languages

- TypeScript (primary)
- Python
- JavaScript
- Shell/curl (for HTTP examples)

---

## Dependencies

### Upstream Dependencies
- Story 7.1 (Architecture Overview)
- Epic 2 (API Implementation) - Actual API behavior
- Epic 4 Story 4.1 (Workflows Tools) - Tool specifications

### Downstream Dependencies
- Stories 7.3-7.6 (Other API references)
- Epic 8 (Deployment) - API usage in production

---

## Definition of Done

### Documentation Completeness
- [ ] All 8 workflow operations documented
- [ ] Request/response schemas for each
- [ ] TypeScript interfaces defined
- [ ] Code examples in 3+ languages
- [ ] Error responses documented
- [ ] Best practices included

### Quality Standards
- [ ] Technical review by development team
- [ ] All examples tested and work
- [ ] Schemas match implementation
- [ ] Cross-references to related docs

---

## Estimation Breakdown

**Story Points:** 6

**Effort Distribution:**
- list_workflows documentation: 0.75 SP
- create_workflow documentation: 1 SP
- get_workflow documentation: 0.75 SP
- update_workflow documentation: 0.75 SP
- Other operations (4): 1.5 SP
- Code examples & testing: 1.25 SP

**Page Count:** 12-16 pages

**Estimated Duration:** 3 days (1 technical writer)

---

## Notes

### Success Metrics
- Developers successfully use API without questions
- Code examples work without modification
- Error handling is clear
- API usage increases

### Best Practices
- ✅ Show complete request/response examples
- ✅ Include TypeScript interfaces
- ✅ Document all error conditions
- ✅ Provide code examples in multiple languages
- ✅ Link to related operations

---

**Status:** Ready for Implementation
**Related Files:**
- `docs/api/workflows-api.md`