@synova-cloud/n8n-nodes-synova-cloud

This is an n8n community node that integrates Synova Cloud with your n8n workflows, so you can execute AI prompts across multiple LLM providers (OpenAI, Anthropic, Google, Azure OpenAI, DeepSeek) with a single unified interface.

Synova Cloud is a platform for managing, versioning, and executing AI prompts with built-in observability, while n8n is a fair-code licensed tool for AI workflow automation.

Table of contents

• Installation (self-hosted)
• Installation (n8n Cloud)
• Installation (development)
• Operations
• Credentials
• Compatibility
• Usage
• Resources
• Troubleshooting
• Version history

Installation (self-hosted)

To install the Synova Cloud community node from the n8n Editor UI:

1. Open your n8n instance.
2. Go to Settings > Community Nodes.
3. Select Install.
4. Enter the npm package name: @synova-cloud/n8n-nodes-synova-cloud.
5. Agree to the risks of using community nodes and select Install.

The node is now available to use in your workflows.

Installation (n8n Cloud)

If you're using n8n Cloud:

1. Go to the Canvas and open the nodes panel.
2. Search for Synova Cloud in the community node registry.
3. Click Install node to add it to your instance.

Installation (development)

Prerequisites

• Node.js: 18.x or higher
• npm: 10.x or higher

Verify your versions:

node --version  # Should be v18.x.x or higher
npm --version   # Should be 10.x.x or higher

1. Clone and Install Dependencies

git clone https://github.com/synova-cloud/n8n-nodes-synova-cloud.git
cd n8n-nodes-synova-cloud
npm install

2. Build the Node Package

npm run build

3. Link to n8n for Local Development

npm link

# In your n8n installation directory (~/.n8n or where n8n is installed)
npm link @synova-cloud/n8n-nodes-synova-cloud

Restart n8n to pick up the linked node.

Making changes

If you make any changes locally, rebuild and restart:

npm run build

Operations

This node supports the following operations:

Prompt

Operation	Description
Execute	Execute an AI prompt via the streaming endpoint for maximum reliability. Supports variables, multi-turn conversations, structured output, and all LLM parameters.
Get	Retrieve a prompt template by ID, tag, or version.

Model

Operation	Description
List	List all available models and providers. Filter by provider, type (text/image), or capability (vision, function calling, etc.).

Key Features

• Streaming under the hood — All prompt executions use the SSE streaming endpoint (/stream) for reliability, avoiding timeout issues with long-running LLM requests. The response is collected and returned as a standard n8n data item.
• Multi-provider support — OpenAI, Anthropic, Google, Azure OpenAI, DeepSeek, Replicate — switch providers by changing a single parameter.
• Prompt versioning — Execute specific prompt versions or tags (e.g., production, staging).
• Structured output — Pass a JSON Schema via Response Schema to get structured JSON responses from LLMs.
• Bring your own key — Optionally pass your own LLM provider API key per request, or use Synova managed keys.

Credentials

The node uses API key authentication:

1. Go to Credentials in n8n.
2. Create a new Synova Cloud API credential.
3. Enter your Synova Cloud API key (get one at app.synova.cloud).
4. Optionally change the Base URL (default: https://api.synova.cloud).

Compatibility

• n8n: Version 1.0.0 and higher
• Node.js: 18.x or higher

Usage

Basic Prompt Execution

1. Add the Synova Cloud node to your workflow.
2. Configure your Synova Cloud API credentials.
3. Set Resource to Prompt and Operation to Execute.
4. Enter your Prompt ID (e.g., prm_abc123).
5. Select a Provider (e.g., OpenAI) and Model (e.g., gpt-4o).
6. Optionally add Variables as JSON to fill prompt template placeholders.
7. Execute the workflow.

The node returns:

{
  "type": "message",
  "content": "The LLM response text...",
  "finishReason": "stop",
  "usage": {
    "inputTokens": 150,
    "outputTokens": 320,
    "totalTokens": 470
  }
}

Multi-turn Conversation

Pass previous messages in the Messages field as a JSON array:

[
  { "role": "user", "content": "What is TypeScript?" },
  { "role": "assistant", "content": "TypeScript is a typed superset of JavaScript..." },
  { "role": "user", "content": "How do I use generics?" }
]

Structured Output

In Additional Options > Response Schema, provide a JSON Schema:

{
  "type": "object",
  "properties": {
    "summary": { "type": "string" },
    "sentiment": { "type": "string", "enum": ["positive", "negative", "neutral"] },
    "score": { "type": "number" }
  },
  "required": ["summary", "sentiment", "score"]
}

The response will include a parsed object field conforming to your schema.

Using Prompt Tags and Versions

In Additional Options, you can specify:

• Tag — e.g., production, staging, latest
• Version — e.g., 1.2.0 (takes precedence over tag)

This allows you to safely update prompts without breaking production workflows.

Workflow Examples

Summarize emails: Gmail trigger → Synova Cloud (Execute) → Slack

Customer support: Webhook → Synova Cloud (Execute with conversation history) → HTTP Response

Data extraction: HTTP Request → Synova Cloud (Execute with structured output) → Google Sheets

Resources

• Synova Cloud Documentation
• Synova Cloud Dashboard
• Synova Cloud Node.js SDK
• n8n Community Nodes Documentation

Troubleshooting

Common issues

Authentication errors

• Verify your API key is correct in the Synova Cloud API credentials.
• Ensure the API key has not expired.

Prompt Not Found

• Verify the Prompt ID format (should start with prm_).
• Check that the prompt exists in your Synova Cloud project.

Timeout errors

• The node uses the streaming endpoint by default, which handles long-running requests well.
• If you still get timeouts, increase the Timeout value in Additional Options (default: 120000ms).

Provider errors (invalid key, rate limit)

• If using your own provider API key, verify it is correct and has sufficient quota.
• Check the error message for details from the LLM provider.

Getting help

If you encounter issues:

• Check the Synova Cloud documentation
• Review the n8n Community Nodes documentation
• Open an issue in the GitHub repository

Version history

0.1.0

• Initial release
• Prompt Execute operation (via streaming endpoint)
• Prompt Get operation
• Model List operation
• Support for variables, messages, structured output, prompt tags/versions
• Multi-provider support: OpenAI, Anthropic, Google, Azure OpenAI, DeepSeek, Replicate

License

MIT