OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add pinecone-io/skills --skill pinecone-n8n
Build n8n workflows using the Pinecone Assistant node or Pinecone Vector Store node. Use when building RAG pipelines, chat-with-docs workflows, configuring Pinecone nodes in n8n, troubleshooting Pinecone n8n nodes, or asking about best practices for Pinecone in n8n.
npx skills add pinecone-io/skills --skill pinecone-n8n
<<invoke_this_skill>>
This skill helps you build n8n workflows with Pinecone nodes following best practices. It covers two Pinecone nodes:
@pinecone-database/n8n-nodes-pinecone-assistant) — recommended for most use cases@n8n/n8n-nodes-langchain.vectorStorePinecone) — for advanced controlCore rule: Always use the node's built-in resources and operations. Never suggest using the HTTP node to call the Pinecone REST API directly.
Ask the user what they're trying to do:
Always present the Pinecone Assistant node as the recommended choice first. Do NOT skip this step based on your own inference about which node fits better — even if the use case mentions specific triggers (Google Drive, webhooks, etc.) or file types (text, markdown, PDF), those details do not determine which node to use.
Only skip this step if:
If the user has not named a node, always ask or recommend the Assistant node first. If the user said "use defaults" or you cannot ask, default to the Pinecone Assistant node and proceed with the Assistant path.
Ask the user which node they want to use, presenting these two options:
Pinecone Assistant (Recommended)
Pinecone Vector Store
@pinecone-database/n8n-nodes-pinecone-assistant.pineconeAssistant@pinecone-database/n8n-nodes-pinecone-assistant.pineconeAssistantToolThe standard pattern is a two-phase workflow:
Phase 1 — Ingestion (run once or on a schedule):
Phase 2 — Chat:
name and host fields:
https://<region>-data.<subdomain>.pinecone.io).additionalFields:
ai_tool connection — NOT mainpineconeApi credential type for both node variantsadditionalFields.metadata.metadataValues — an array of {"key": "...", "value": "..."} objects. The externalFileId is automatically added to metadata; do not include it manually. Example:
additionalFields.metadataFilter.metadataValues (same {key, value} array) for simple equality filters, or additionalFields.advancedMetadataFilter (a JSON string) for operators like $or, $ne, $in. Cannot set both at once. Example simple filter:
additionalFields.multimodalFile: true on the uploadFile node when the PDF contains images or charts that should be indexed for visual retrieval. This is required for images to be retrievable later — it is not the default.Build the workflow to match what the user actually describes — their triggers, models, data sources, and structure. Ask about anything structurally significant they haven't mentioned. Only fall back to the defaults below when the user hasn't specified a value:
n8n-assistant (use n8n-assistant-1, n8n-assistant-2, etc. for multiples; must match an existing assistant in the Pinecone Console)gpt-5-miniThe JSON below is a reference configuration showing correct parameter values, required fields, and connection types for each node. Use it as a guide for how to configure the nodes — not as a template to copy verbatim. Placeholders to substitute:
[ASSISTANT_NAME] — assistant name[ASSISTANT_HOST] — assistant host URL from the Pinecone Console (e.g. https://your-assistant-host.pinecone.io)[USER_FILE_URLS_ARRAY] — JSON array of file URL strings, e.g. ["https://example.com/doc.pdf"][USER_MODEL] — LLM model name, e.g. gpt-5-mini[USER_TOPIC] — short description of what the assistant knows, for the system message| Scenario | Operation to use |
|---|---|
| File is guaranteed to be new (never ingested before) | uploadFile |
| File may already exist in the assistant (re-ingestion, scheduled refresh) | updateFile |
updateFile is idempotent: it finds all files with the matching externalFileId, deletes them, then uploads the new version. If no file exists with that ID it behaves exactly like uploadFile. Use updateFile whenever a workflow may run more than once on the same source files.
Parameters for updateFile are identical to uploadFile: assistantData, externalFileId, inputDataFieldName, and all additionalFields including metadata, multimodalFile, and sourceTag.
Use resource: "file", operation: "listFiles" to retrieve files, optionally filtered by metadata.
For complex filters, use advancedMetadataFilter (a JSON string) instead of metadataFilter — never both:
Use resource: "contextSnippet", operation: "getContextSnippets" to retrieve relevant text or image chunks directly — useful when you need raw retrieved context as workflow data rather than a chat reply.
The same metadataFilter / advancedMetadataFilter options work on getContextSnippets to scope retrieval to files matching specific metadata. The includeBinaryContent flag only applies when includeMultimodalContext is true.
@n8n/n8n-nodes-langchain.vectorStorePinecone
Two-phase workflow with two separate vectorStorePinecone node instances:
Phase 1 — Ingestion (run once or on a schedule):
Phase 2 — Chat:
vectorStorePinecone in insert mode for ingestion and a separate one in retrieve-as-tool mode for chatai_embedding connection@n8n/n8n-nodes-langchain.embeddingsOpenAi — set dimensions to match your index (1536 for text-embedding-3-small)@n8n/n8n-nodes-langchain.textSplitterRecursiveCharacterTextSplitter — connects to the data loader@n8n/n8n-nodes-langchain.documentDefaultDataLoader — set dataType: binary and textSplittingMode: customexternal_file_url as a metadata field set to ={{ $json.urls }} so the AI Agent can cite sourcespineconeApi credential typeWhen generating a workflow, always tell the user to:
pineconeIndex value in the workflowBuild the workflow to match what the user actually describes — their triggers, embedding model, chunking strategy, data sources, and structure. Ask about anything structurally significant they haven't mentioned. Only fall back to the defaults below when the user hasn't specified a value:
n8n-index (use n8n-index-1, n8n-index-2, etc. for multiples; must match an existing Pinecone index)gpt-5-minitext-embedding-3-small (1536 dimensions)The JSON below is a reference configuration showing correct parameter values, required fields, and connection types for each node. Use it as a guide for how to configure the nodes — not as a template to copy verbatim. Placeholders to substitute:
[INDEX_NAME] — index name[USER_FILE_URLS_ARRAY] — JSON array of file URL strings, e.g. ["https://example.com/doc.pdf"][USER_MODEL] — LLM model name, e.g. gpt-5-mini[USER_TOPIC] — short description of the data, for the AI Agent system message[USER_TOOL_DESCRIPTION] — description of what data the vector store contains, for the tool nodeWhen a user reports a broken workflow, ask which node is failing and what error they see, then refer to these common issues:
| Error / Symptom | Cause | Fix |
|---|---|---|
| "Assistant not found" | assistantData.name doesn't match an existing assistant | Create the assistant in the Pinecone Console first, then match the name exactly |
| "Invalid credentials" | Pinecone API key not set or wrong credential on the node | Re-select the pineconeApi credential on each Pinecone node |
| "Dimension mismatch" | Embedding model dimensions don't match the index | Index and embeddings node must use the same dimensions (e.g., 1536 for text-embedding-3-small) |
| Tool never called by Agent | toolDescription is vague | Make the description specific: what data is in the store, what questions it can answer |
| No results returned | Ingestion didn't run, or topK too low | Run Phase 1 first; try increasing topK to 20+ |
| HTTP node calling Pinecone API | Wrong pattern | Replace with @pinecone-database/n8n-nodes-pinecone-assistant.pineconeAssistant or @n8n/n8n-nodes-langchain.vectorStorePinecone |
When reviewing an existing workflow:
assistantData includes both name and host; sourceTag is present in additionalFieldsexternal_file_url stored in the Default Data Loader metadata for source citationslistFiles and getContextSnippets use a metadata filter (not both filter fields at once) when scoping to a subset of filesmultimodalFile: true is set on uploadFile when PDFs contain images or charts — this is required to index visual content and is NOT the defaultincludeMultimodalContext: true and includeBinaryContent: true on getContextSnippets when the workflow needs image chunks alongside text