n8n

Overview

The coSPEC community node (n8n-nodes-cospec) adds a coSPEC action node and a trigger node to n8n. The action node creates runs and polls automatically until completion. The trigger node fires instantly when a run finishes via webhook.

The coSPEC node is currently available for self-hosted n8n only. n8n Cloud support is pending verification. In the meantime, Cloud users can use the REST API with n8n's HTTP Request node.

Prerequisites

coSPEC account with an API key (csk_live_...) — see API Keys
Self-hosted n8n instance

Install

Go to Settings → Community Nodes
Click Install a community node
Enter: n8n-nodes-cospec
Click Install

Connect Your API Key

In a workflow, add a coSPEC node
Click the credential dropdown → Create New Credential
Paste your API key (csk_live_...)
Click Test — n8n validates the key
Save

Where to find your key: Dashboard → API Keys → Create API Key

Optional: set a custom Base URL for self-hosted coSPEC deployments.

Nodes

Create Run

Two patterns, depending on your setup:

Pattern 1 — Action node (polling, default):

[Any Trigger] → [coSPEC: Create Run] → [Use Results]

The Create Run node waits for completion and returns the full run object. Single workflow, simple. Works everywhere including behind firewalls/NAT.

Pattern 2 — Webhook trigger (instant, no polling):

Workflow A: [Any Trigger] → [coSPEC: Create Run (wait=false)]
Workflow B: [coSPEC Trigger: Run Finished] → [Use Results]

The trigger fires instantly when a run finishes. More efficient (no polling), but requires two workflows and that coSPEC can reach your n8n instance.

Get Run

Fetches a run by ID. Returns the full run object with all output fields. Use it to check status or retrieve results for a run started with waitForCompletion: false.

Run Finished Trigger

The CospecTrigger node fires instantly when a run completes, fails, or is cancelled. Uses org webhooks — registered automatically when you activate the workflow.

Events: Completed, Failed, Cancelled (multi-select, default: all)
Delivers the full run object

AI Agent Tool

The coSPEC node can be used as a tool in n8n's AI agent workflows. An AI agent in n8n can autonomously decide to trigger coSPEC runs as part of its reasoning.

Output Fields

Outputs are grouped by type into structured objects. Each group is the first output of that type, or null if absent. If a run produces multiple outputs of the same type, use the raw outputs array.

Expression	Description
`$json.pr.url`	URL of the first pull request
`$json.pr.title`	Title of the first pull request
`$json.pr.number`	Number of the first pull request
`$json.branch.name`	Name of the created branch
`$json.issue.url`	URL of the first issue
`$json.issue.title`	Title of the first issue
`$json.issue.number`	Number of the first issue
`$json.summary`	Text content from the first text output
`$json.outputs`	Raw outputs array for runs with multiple outputs

Failed Runs

When a run fails, the Status field is failed. Two additional fields help you diagnose:

Fail Reason — why the run stopped: max_turns, max_cost, timeout, or error
Error — error details (message and code) when failReason is error

If the node is polling and the run fails, it still returns the full output with these fields (it doesn't throw an error).

Troubleshooting

Issue	Solution
"Cannot find module n8n-nodes-cospec"	Restart n8n after installing the community node.
Node times out	Increase the Timeout field. Default is 30 minutes. For long runs, consider `waitForCompletion: false` + webhook trigger pattern.
Credential test fails	Check your API key. Keys start with `csk_live_`.

On this page