n8n

What this integration is for

Use the Calypso n8n community node when you want workflow automation without writing a custom integration.

The node lets n8n flows:

• ask grounded Calypso agents through the Responses API
• choose API-key scoped named profiles such as calypso-rag-agent:support
• view the buckets connected to a selected named profile
• upload one file or a batch of files into an authenticated knowledge bucket

Package

Install the public community-node package:

npm install @calypsohq/n8n-nodes-calypso

Package links:

• npm: @calypsohq/n8n-nodes-calypso
• GitHub: calypso-so/n8n-nodes-calypso

The default API base URL is:

https://api.calypso.so/v1

Only override the base URL when you are targeting a self-hosted or environment-specific Calypso-compatible deployment.

Install in n8n Cloud

1. Open Settings.
2. Go to Community nodes.
3. Install @calypsohq/n8n-nodes-calypso.
4. Search for Calypso in the node panel.

Install in self-hosted n8n

Install the package in the same environment where n8n loads community nodes:

npm install @calypsohq/n8n-nodes-calypso

Restart n8n after installation, then search for Calypso in the node panel.

Credentials

Create a Calypso API credential with:

• API Key: a Calypso project API key
• Base URL: https://api.calypso.so/v1

The project API key determines the workspace, available named profiles, bucket access, and upload permissions for the node.

Operations

Ask Agent

Use Ask Agent to send a grounded request to Calypso.

Model options:

• Default Agent uses calypso-rag-agent
• Named Profile loads profile options from the connected API key and shows full model IDs such as calypso-rag-agent:support

When you choose a named profile, the node also shows Agent Bucket Context below the selector. This is an informational list of the buckets connected to that profile and the current file count for each bucket.

Upload File

Use Upload File when each incoming n8n item contains one binary file.

Configure:

• Bucket Name or ID: loaded from the active buckets available to the connected API key
• Binary Property Name: usually data
• optional title, tags, metadata, and idempotency key

The operation creates an upload session, sends the binary file directly to storage, finalizes the session, and returns the Calypso knowledge file response.

Upload Batch

Use Upload Batch when a workflow has multiple incoming items and you want one durable batch request.

Configure:

• Bucket Name or ID: loaded from the active buckets available to the connected API key
• Binary Property Name: usually data
• Batch Idempotency Key: a stable retry key for the batch
• optional tags and metadata

The operation builds a batch upload-session request, sends each accepted file directly to storage, finalizes the batch session, and returns one batch response item.

Why this path is useful

It lets operations teams and integrators reuse the same grounded Calypso agent inside broader automation without copying retrieval, bucket policy, or upload logic into n8n.

Best practices

• Validate the agent in Playground before automating it.
• Use named profiles for workflows that need a stable bucket or policy scope.
• Use Upload File for one-file-per-item flows.
• Use Upload Batch for multi-item imports that should be accepted as one retryable batch.
• Treat upload responses as durable acceptance. Newly uploaded knowledge may still need indexing time before it is ready for agent answers.

Common flow shape

1. Trigger a workflow from a form, webhook, schedule, CRM event, or file source.
2. Add the Calypso node.
3. Choose Upload File, Upload Batch, or Ask Agent.
4. Select the project-scoped bucket or named profile from the dynamic dropdown.
5. Pass the Calypso result into the next n8n step.