mvp-factory-openhands/n8n-api.md

# n8n API Complete Documentation

**Base URL:** `https://n8n.oky.sh/api/v1/`

## Authentication

Use the JWT token from `/home/bam/.n8n_api_key`:

```bash
Authorization: Bearer <token-from-.n8n_api_key>
Content-Type: application/json
```

## API Operations

### 1. List All Workflows
```bash
curl -H "Authorization: Bearer $(cat /home/bam/.n8n_api_key)" \
  https://n8n.oky.sh/api/v1/workflows
```

**Response:**
```json
[
  {
    "id": "workflow_id",
    "name": "Workflow Name",
    "active": true,
    "nodes": [...],
    "connections": {...}
  }
]
```

### 2. Create New Workflow
```bash
curl -X POST \
  -H "Authorization: Bearer $(cat /home/bam/.n8n_api_key)" \
  -H "Content-Type: application/json" \
  https://n8n.oky.sh/api/v1/workflows \
  -d '{
    "name": "My New Workflow",
    "nodes": [...],
    "connections": {...}
  }'
```

### 3. Get Specific Workflow
```bash
curl -H "Authorization: Bearer $(cat /home/bam/.n8n_api_key)" \
  https://n8n.oky.sh/api/v1/workflows/<WORKFLOW_ID>
```

### 4. Update Workflow
```bash
curl -X PUT \
  -H "Authorization: Bearer $(cat /home/bam/.n8n_api_key)" \
  -H "Content-Type: application/json" \
  https://n8n.oky.sh/api/v1/workflows/<WORKFLOW_ID> \
  -d '{
    "name": "Updated Name",
    "nodes": [...],
    "connections": {...}
  }'
```

### 5. Activate Workflow
```bash
curl -X POST \
  -H "Authorization: Bearer $(cat /home/bam/.n8n_api_key)" \
  https://n8n.oky.sh/api/v1/workflows/<WORKFLOW_ID>/activate
```

### 6. Deactivate Workflow
```bash
curl -X POST \
  -H "Authorization: Bearer $(cat /home/bam/.n8n_api_key)" \
  https://n8n.oky.sh/api/v1/workflows/<WORKFLOW_ID>/deactivate
```

### 7. Delete Workflow
```bash
curl -X DELETE \
  -H "Authorization: Bearer $(cat /home/bam/.n8n_api_key)" \
  https://n8n.oky.sh/api/v1/workflows/<WORKFLOW_ID>
```

### 8. Execute Workflow (Manual Trigger)
```bash
curl -X POST \
  -H "Authorization: Bearer $(cat /home/bam/.n8n_api_key)" \
  -H "Content-Type: application/json" \
  https://n8n.oky.sh/api/v1/workflows/<WORKFLOW_ID>/execute \
  -d '{
    "input": {
      "key": "value"
    }
  }'
```

### 9. Get Execution Details
```bash
curl -H "Authorization: Bearer $(cat /home/bam/.n8n_api_key)" \
  https://n8n.oky.sh/api/v1/executions/<EXECUTION_ID>
```

### 10. List All Executions
```bash
curl -H "Authorization: Bearer $(cat /home/bam/.n8n_api_key)" \
  https://n8n.oky.sh/api/v1/executions?filter='{"workflowId":"<WORKFLOW_ID>"}'
```

### 11. Get Workflow Credentials
```bash
curl -H "Authorization: Bearer $(cat /home/bam/.n8n_api_key)" \
  https://n8n.oky.sh/api/v1/credentials
```

## Webhook URLs

### Manual Webhook (Publicly Accessible)
```
https://n8n.oky.sh/webhook/<WEBHOOK_ID>
```

### Workflow-Specific Webhooks
Navigate to: Workflow Settings → Webhook URLs in n8n UI

## Error Codes

- **200** - Success
- **401** - Unauthorized (check API token)
- **404** - Not found (check workflow ID)
- **422** - Validation error (check request body)

## Python Example

```python
import requests

API_URL = "https://n8n.oky.sh/api/v1"
with open("/home/bam/.n8n_api_key", "r") as f:
    headers = {"Authorization": f"Bearer {f.read().strip()}"}

# List workflows
response = requests.get(f"{API_URL}/workflows", headers=headers)
workflows = response.json()
print(f"Found {len(workflows)} workflows")

# Create workflow
new_workflow = {
    "name": "My Test Workflow",
    "nodes": [...],
    "connections": {...}
}
response = requests.post(
    f"{API_URL}/workflows",
    headers=headers,
    json=new_workflow
)
workflow = response.json()
print(f"Created workflow: {workflow['id']}")

# Activate workflow
requests.post(
    f"{API_URL}/workflows/{workflow['id']}/activate",
    headers=headers
)
```

## Working with Webhooks

### Testing Webhook
```bash
curl -X POST https://n8n.oky.sh/webhook/test-webhook-id \
  -H "Content-Type: application/json" \
  -d '{"test": "data"}'
```

### Checking Executions
```bash
# List recent executions
curl -H "Authorization: Bearer $(cat /home/bam/.n8n_api_key)" \
  https://n8n.oky.sh/api/v1/executions

# Get specific execution details
curl -H "Authorization: Bearer $(cat /home/bam/.n8n_api_key)" \
  https://n8n.oky.sh/api/v1/executions/<EXECUTION_ID>
```

## Managing Workflow Data

### Using staticData
```javascript
// Store data across workflow execution
$workflow.staticData = $workflow.staticData || {};
$workflow.staticData.retry_count = ($workflow.staticData.retry_count || 0) + 1;

// Retrieve data
const retryCount = $workflow.staticData.retry_count || 0;
```

### Accessing Previous Node Data
```javascript
// SSH nodes overwrite ALL data
// Use $node to access previous node output
const repoData = $node["Extract Repo Info"].json;
const sshOutput = $json;

return {
  ...repoData,  // Preserved from previous node
  ...sshOutput  // Current node output
};
```

## API Token Location

**File:** `/home/bam/.n8n_api_key`
**Format:** JWT Token
**Permissions:** Should be 600 (readable only by owner)

```bash
# View token (DO NOT commit this file)
cat /home/bam/.n8n_api_key

# Set proper permissions
chmod 600 /home/bam/.n8n_api_key
```

---

*Last Updated: 2025-12-02*
*Complete n8n API reference*