Buckets:

download
raw
14.1 kB
#!/usr/bin/env python3
"""
Tool: n8n API Client
Purpose: Create, manage, and execute n8n workflows via REST API
Usage:
python tools/n8n_api.py --action list
python tools/n8n_api.py --action get --workflow-id "abc123"
python tools/n8n_api.py --action create --workflow-file "workflow.json"
python tools/n8n_api.py --action activate --workflow-id "abc123"
python tools/n8n_api.py --action execute --workflow-id "abc123" --data '{"key": "value"}'
Environment Variables Required:
- N8N_API_URL: n8n instance URL (e.g., https://seme.app.n8n.cloud)
- N8N_API_KEY: API key for authentication
"""
import os
import json
import argparse
from pathlib import Path
from typing import Optional
import urllib.error
import urllib.parse
import urllib.request
try:
import httpx # type: ignore
_HTTPX_AVAILABLE = True
except ModuleNotFoundError:
httpx = None # type: ignore
_HTTPX_AVAILABLE = False
try:
from dotenv import load_dotenv
except ModuleNotFoundError:
def load_dotenv(*args, **kwargs) -> bool: # type: ignore
return False
load_dotenv()
class HttpRequestError(Exception):
def __init__(self, status_code: int, message: str, response_text: str = "") -> None:
super().__init__(message)
self.status_code = status_code
self.response_text = response_text
def _request_json(
method: str,
url: str,
headers: dict,
*,
params: Optional[dict] = None,
json_body: Optional[dict] = None,
timeout: float = 30.0,
allow_text: bool = False,
) -> dict:
if _HTTPX_AVAILABLE:
try:
response = httpx.request( # type: ignore
method,
url,
headers=headers,
params=params,
json=json_body,
timeout=timeout,
)
response.raise_for_status()
except httpx.HTTPStatusError as e: # type: ignore
raise HttpRequestError(e.response.status_code, str(e), e.response.text) from e
except httpx.RequestError as e: # type: ignore
raise HttpRequestError(0, str(e), "") from e
try:
return response.json()
except json.JSONDecodeError:
if allow_text:
return {"status": "success", "response": response.text}
raise
if params:
query = urllib.parse.urlencode(params, doseq=True)
separator = "&" if "?" in url else "?"
url = f"{url}{separator}{query}"
body = None
if json_body is not None:
body = json.dumps(json_body).encode("utf-8")
headers = dict(headers)
headers.setdefault("Content-Type", "application/json")
request = urllib.request.Request(url, data=body, headers=headers, method=method)
try:
with urllib.request.urlopen(request, timeout=timeout) as response:
text = response.read().decode()
except urllib.error.HTTPError as e:
response_text = ""
try:
response_text = e.read().decode()
except Exception:
response_text = ""
raise HttpRequestError(e.code, f"HTTP {e.code}", response_text) from e
except urllib.error.URLError as e:
raise HttpRequestError(0, str(e), "") from e
if allow_text:
try:
return json.loads(text)
except json.JSONDecodeError:
return {"status": "success", "response": text}
return json.loads(text)
def _is_placeholder(value: str) -> bool:
if not value:
return True
lowered = value.lower()
return "your-instance" in lowered or "your-n8n-api-key" in lowered
def _load_from_mcp() -> tuple[str, str]:
mcp_path = Path(__file__).resolve().parents[1] / ".mcp.json"
if not mcp_path.exists():
return "", ""
try:
config = json.loads(mcp_path.read_text())
except json.JSONDecodeError:
return "", ""
servers = config.get("mcpServers", {})
n8n_cfg = servers.get("n8n-mcp", {})
env = n8n_cfg.get("env", {})
return env.get("N8N_API_URL", ""), env.get("N8N_API_KEY", "")
N8N_API_URL = os.getenv("N8N_API_URL", "").rstrip("/")
N8N_API_KEY = os.getenv("N8N_API_KEY", "")
if _is_placeholder(N8N_API_URL) or _is_placeholder(N8N_API_KEY):
mcp_url, mcp_key = _load_from_mcp()
if mcp_url:
N8N_API_URL = mcp_url.rstrip("/")
if mcp_key:
N8N_API_KEY = mcp_key
def get_headers() -> dict:
"""Return headers for n8n API requests."""
return {
"X-N8N-API-KEY": N8N_API_KEY,
"Content-Type": "application/json",
"Accept": "application/json",
}
def list_workflows(active_only: bool = False) -> dict:
"""
List all workflows.
Args:
active_only: If True, return only active workflows
Returns:
dict: API response with workflow list
"""
params = {"active": "true"} if active_only else {}
return _request_json(
"GET",
f"{N8N_API_URL}/api/v1/workflows",
get_headers(),
params=params,
timeout=30.0,
)
def get_workflow(workflow_id: str) -> dict:
"""
Get a specific workflow by ID.
Args:
workflow_id: The workflow ID
Returns:
dict: Workflow details
"""
return _request_json(
"GET",
f"{N8N_API_URL}/api/v1/workflows/{workflow_id}",
get_headers(),
timeout=30.0,
)
def create_workflow(workflow_data: dict) -> dict:
"""
Create a new workflow.
Args:
workflow_data: Workflow JSON object with name, nodes, connections, settings
Returns:
dict: Created workflow with ID
"""
return _request_json(
"POST",
f"{N8N_API_URL}/api/v1/workflows",
get_headers(),
json_body=workflow_data,
timeout=30.0,
)
def update_workflow(workflow_id: str, workflow_data: dict) -> dict:
"""
Update an existing workflow.
Args:
workflow_id: The workflow ID
workflow_data: Updated workflow JSON
Returns:
dict: Updated workflow
"""
return _request_json(
"PUT",
f"{N8N_API_URL}/api/v1/workflows/{workflow_id}",
get_headers(),
json_body=workflow_data,
timeout=30.0,
)
def delete_workflow(workflow_id: str) -> dict:
"""
Delete a workflow.
Args:
workflow_id: The workflow ID
Returns:
dict: Deletion confirmation
"""
_request_json(
"DELETE",
f"{N8N_API_URL}/api/v1/workflows/{workflow_id}",
get_headers(),
timeout=30.0,
)
return {"status": "deleted", "workflow_id": workflow_id}
def activate_workflow(workflow_id: str) -> dict:
"""
Activate a workflow.
Args:
workflow_id: The workflow ID
Returns:
dict: Activation result
"""
return _request_json(
"POST",
f"{N8N_API_URL}/api/v1/workflows/{workflow_id}/activate",
get_headers(),
timeout=30.0,
)
def deactivate_workflow(workflow_id: str) -> dict:
"""
Deactivate a workflow.
Args:
workflow_id: The workflow ID
Returns:
dict: Deactivation result
"""
return _request_json(
"POST",
f"{N8N_API_URL}/api/v1/workflows/{workflow_id}/deactivate",
get_headers(),
timeout=30.0,
)
def execute_workflow(workflow_id: str, data: Optional[dict] = None) -> dict:
"""
Execute a workflow with optional input data.
Args:
workflow_id: The workflow ID
data: Optional input data for the workflow
Returns:
dict: Execution result
"""
body = data or {}
return _request_json(
"POST",
f"{N8N_API_URL}/api/v1/workflows/{workflow_id}/execute",
get_headers(),
json_body=body,
timeout=120.0,
)
def trigger_webhook(webhook_path: str, data: dict, method: str = "POST") -> dict:
"""
Trigger a webhook workflow.
Args:
webhook_path: The webhook path (e.g., "my-webhook")
data: Data to send to the webhook
method: HTTP method (POST, GET)
Returns:
dict: Webhook response
"""
url = f"{N8N_API_URL}/webhook/{webhook_path}"
if method.upper() == "GET":
return _request_json(
"GET",
url,
get_headers(),
params=data,
timeout=60.0,
allow_text=True,
)
return _request_json(
"POST",
url,
get_headers(),
json_body=data,
timeout=60.0,
allow_text=True,
)
def list_executions(workflow_id: Optional[str] = None, status: Optional[str] = None) -> dict:
"""
List workflow executions.
Args:
workflow_id: Filter by workflow ID
status: Filter by status (error, success, waiting)
Returns:
dict: List of executions
"""
params = {}
if workflow_id:
params["workflowId"] = workflow_id
if status:
params["status"] = status
return _request_json(
"GET",
f"{N8N_API_URL}/api/v1/executions",
get_headers(),
params=params,
timeout=30.0,
)
def health_check() -> dict:
"""
Perform a lightweight API check to verify connectivity and auth.
Returns:
dict: Health status with workflow count (if available)
"""
data = _request_json(
"GET",
f"{N8N_API_URL}/api/v1/workflows",
get_headers(),
timeout=10.0,
)
# n8n can return either a list or an object containing data
if isinstance(data, dict) and "data" in data:
workflows = data.get("data") or []
else:
workflows = data if isinstance(data, list) else []
return {"status": "ok", "workflows": len(workflows)}
def main():
parser = argparse.ArgumentParser(description="n8n API Client")
parser.add_argument(
"--action",
required=True,
choices=[
"list",
"get",
"create",
"update",
"delete",
"activate",
"deactivate",
"execute",
"webhook",
"executions",
"health",
],
help="Action to perform",
)
parser.add_argument(
"--workflow-id", help="Workflow ID for get/update/delete/activate/deactivate/execute"
)
parser.add_argument(
"--workflow-file", help="JSON file with workflow definition for create/update"
)
parser.add_argument("--data", help="JSON data for execute/webhook")
parser.add_argument("--webhook-path", help="Webhook path for webhook action")
parser.add_argument("--active-only", action="store_true", help="List only active workflows")
parser.add_argument("--status", help="Filter executions by status")
args = parser.parse_args()
# Validate environment
if not N8N_API_URL or not N8N_API_KEY:
print(
json.dumps(
{
"status": "error",
"message": "N8N_API_URL and N8N_API_KEY must be set in environment",
}
)
)
return
try:
result = None
if args.action == "list":
result = list_workflows(active_only=args.active_only)
elif args.action == "get":
if not args.workflow_id:
raise ValueError("--workflow-id required for get action")
result = get_workflow(args.workflow_id)
elif args.action == "create":
if not args.workflow_file:
raise ValueError("--workflow-file required for create action")
with open(args.workflow_file, "r") as f:
workflow_data = json.load(f)
result = create_workflow(workflow_data)
elif args.action == "update":
if not args.workflow_id or not args.workflow_file:
raise ValueError("--workflow-id and --workflow-file required for update action")
with open(args.workflow_file, "r") as f:
workflow_data = json.load(f)
result = update_workflow(args.workflow_id, workflow_data)
elif args.action == "delete":
if not args.workflow_id:
raise ValueError("--workflow-id required for delete action")
result = delete_workflow(args.workflow_id)
elif args.action == "activate":
if not args.workflow_id:
raise ValueError("--workflow-id required for activate action")
result = activate_workflow(args.workflow_id)
elif args.action == "deactivate":
if not args.workflow_id:
raise ValueError("--workflow-id required for deactivate action")
result = deactivate_workflow(args.workflow_id)
elif args.action == "execute":
if not args.workflow_id:
raise ValueError("--workflow-id required for execute action")
data = json.loads(args.data) if args.data else None
result = execute_workflow(args.workflow_id, data)
elif args.action == "webhook":
if not args.webhook_path:
raise ValueError("--webhook-path required for webhook action")
data = json.loads(args.data) if args.data else {}
result = trigger_webhook(args.webhook_path, data)
elif args.action == "executions":
result = list_executions(workflow_id=args.workflow_id, status=args.status)
elif args.action == "health":
result = health_check()
print(json.dumps(result, indent=2))
except HttpRequestError as e:
print(
json.dumps(
{
"status": "error",
"code": e.status_code,
"message": str(e),
"response": e.response_text,
}
)
)
except Exception as e:
print(json.dumps({"status": "error", "message": str(e)}))
if __name__ == "__main__":
main()

Xet Storage Details

Size:
14.1 kB
·
Xet hash:
6d1eb24fd642c9dc2b94d602f02243b01fa22224df2252ed9f2beae2433aaaab

Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.