Mattering Automations Pinecone integration
Connect Pinecone to Mattering Automations: indexes and collections, similarity search, upsert and update, namespaces, text records with integrated embedding, backups and restores, and bulk imports as workflow steps, authenticated with one project-scoped API key.
The Mattering Automations Pinecone integration puts Pinecone API version 2025-10 on your automation canvas: create, describe, configure and delete indexes, run similarity search, fetch records by id or by metadata filter, upsert and update vectors, manage namespaces, write and search text records on indexes with integrated embedding, take backups and restore from them, and run asynchronous bulk imports from object storage.
The credential is a Pinecone API key, created in the Pinecone console on a project's API keys page and sent as the Api-Key header on every request. A key is scoped to one project, so it already selects which indexes you are working with and the integration asks for no project id. Mattering also sends the X-Pinecone-Api-Version header, pinned to 2025-10, because Pinecone's versioning guide states that a request without it falls back to the oldest supported stable version. Setup takes a few minutes, and this guide walks through each step and ends with the full node reference.
One thing is different here from most integrations, and it is easier to understand up front than to hit later. Pinecone is two APIs on two hosts: index, collection and backup calls go to one global control-plane address, while every vector call goes to that index's OWN host, a different address per index that Pinecone returns from the console or the API rather than following a pattern you can assemble yourself. That is why the host is not a credential field. You connect one credential for the project, and each data-plane node carries its own Index Host field, which is a picker that lists your indexes by name and stores the host the lister already returned. One credential, then a host chosen per node.
Before you start
- A Pinecone account with a project you can create an API key in. The key is created in the Pinecone console on the project's API keys page.
- At least one index, or the intent to create one. An empty project is fine: Pinecone: Create Index and Pinecone: Create Index With Integrated Embedding both work from the canvas, and the verify path below reads cleanly against an empty project.
- A sense of which kind of index you are working with. Namespace operations and vector id listing are documented by Pinecone as serverless only, and collections are a snapshot of a pod-based index that serverless indexes do not support. Both families are built, and each node's description says which kind it applies to. Most projects will be serverless: Pinecone documents that customers who signed up for Standard or Enterprise on or after 18 August 2025 cannot create pod-based indexes.
- A Pinecone plan that covers the nodes you intend to use. Pinecone documents backups and restores as available on the Standard and Enterprise plans and not on Starter or Builder, and documents bulk imports from object storage as Standard and Enterprise only, which together is 11 of the 35 nodes. The index, search, upsert, update, delete, namespace and text record nodes work on any plan that can create a serverless index. Check Pinecone's pricing page for what your project's plan includes before you build a workflow around the backup nodes.
- A Mattering workspace with access to the Automations app.
- Not required and not stored here: any index host. Hosts are per index and belong on the nodes, not on the credential, which is what lets one key address every index in the project.
Create a Pinecone API key
Mattering authenticates to Pinecone with an API key, sent as the Api-Key header on every request to both planes. Keys belong to a project rather than to an account, so the first decision is which project this credential should reach: the key selects the project, and the index lister then returns that project's indexes. There are no scopes to compose and no host to choose at this stage.
Connect Pinecone to Mattering
Verify it works
After connecting, open any automation canvas and check the palette: a Pinecone section should list the read and action nodes. Drop Pinecone: List Indexes onto the canvas and run a test step. It is the integration's natural probe: it needs no parameters, and it returns every index in the project with its dimension, metric, deployment state, and, at data.indexes[].host, the data-plane host that every vector node needs. Note the state of the index you plan to use as well: an index still Initializing is not ready to take traffic yet.
Now try a data-plane node, because that is the half where the host matters. Drop Pinecone: Describe Index Stats onto the canvas and open its Index Host field: the picker should list your indexes BY NAME, grouped by vector type, with each one's deployment state shown. Choose an index and run the step. You get the total vector count, the dimension, and a per-namespace count. One shape to notice while you are here: data.namespaces is a MAP keyed by namespace name rather than a list, so a specific namespace is read as data.namespaces.NAME.vectorCount. Everything in this verify path is read-only, so it cannot reach the five destructive nodes and is safe to re-run whenever you rotate the key.
Node reference
35 nodes, generated from the connector itself so this reference always matches what ships.
Read and query nodes 18
Pinecone: Describe Backup
pinecone_describe_backup
Get one backup's status and contents: source index, record count, namespace count, size in bytes, dimension, metric and creation time. Poll this after Pinecone: Create Backup until status is Ready.
Pinecone: Describe Collection
pinecone_describe_collection
Get one collection's configuration and status: dimension, record count, size in bytes, environment, and whether it is Initializing, Ready or Terminating.
Pinecone: Describe Import
pinecone_describe_import
Check one import: status (Pending, InProgress, Failed, Completed or Cancelled), percent complete, records imported so far, and any error message. Poll this after Pinecone: Start Import.
Pinecone: Describe Index
pinecone_describe_index
Get one index's full configuration and deployment status: dimension, metric, vector type, spec, tags, deletion protection, any integrated embedding model, and the data-plane host at data.host. Poll this after creating or reconfiguring an index until data.status.ready is true.
Pinecone: Describe Index Stats
pinecone_describe_index_stats
Count what is actually in an index: total vectors, dimension, metric, and a per-namespace vector count. Note that data.namespaces is a MAP keyed by namespace name, not a list, so a specific namespace is read as data.namespaces.NAME.vectorCount. Index fullness is meaningful only for pod-based indexes; serverless indexes scale on their own.
Pinecone: Describe Namespace
pinecone_describe_namespace
Get one namespace's record count and its metadata schema, including which fields are indexed for filtering. Serverless indexes only.
Pinecone: Describe Restore Job
pinecone_describe_restore_job
Check how far a restore has got: status, percent complete, the backup it came from, and the target index name. Poll this after Pinecone: Create Index From Backup until status is Completed.
Pinecone: Fetch Vectors By Id
pinecone_fetch_vectors
Look up records by exact id, with their values and metadata. No similarity involved. Note that data.vectors is a MAP keyed by vector id, not a list, so one record is read as data.vectors.ID. If you only need metadata, Pinecone: Query Vectors with include_values false is often cheaper.
Pinecone: Fetch Vectors By Metadata
pinecone_fetch_vectors_by_metadata
Pull records out by metadata filter rather than by id or similarity, paginated. Useful for auditing or re-processing everything tagged a certain way. Like the id fetch, data.vectors is a MAP keyed by vector id, not a list.
Pinecone: List Collections
pinecone_list_collections
List every collection in the project, with its size, record count, dimension and status. A collection is a static snapshot of a pod-based index that a new index can be created from. Serverless indexes do not support collections; they use backups instead.
Pinecone: List Imports
pinecone_list_imports
List recent and running import operations for one index, with each one's status, progress percentage and imported record count. Paginated.
Pinecone: List Index Backups
pinecone_list_index_backups
List the backups taken from one index. Same shape as the project-wide list, scoped to a single source index, which is what a restore workflow wants.
Pinecone: List Indexes
pinecone_list_indexes
List every index in the project the API key belongs to, with each index's dimension, metric, deployment state and its data-plane host. This is the node every other Pinecone node leans on: the host it returns is what data-plane nodes need, and it is also the cheapest way to confirm a credential works.
Pinecone: List Namespaces
pinecone_list_namespaces
List the namespaces in one index, with each namespace's record count, in sorted order and paginated. This is the list-shaped namespace source: Pinecone: Describe Index Stats reports the same counts but as a map keyed by name. Serverless indexes only.
Pinecone: List Project Backups
pinecone_list_project_backups
List every backup in the project across all indexes, newest first, with each backup's source index, record count, size and status. Paginated: pass data.pagination.next back as the pagination token for the following page.
Pinecone: List Vector Ids
pinecone_list_vector_ids
Page through the record ids in one namespace, in sorted order, optionally narrowed to a common prefix. This is how you enumerate a namespace without reading vectors. Serverless indexes only.
Pinecone: Query Vectors
pinecone_query_vectors
The core similarity search. Give it a query vector (or the id of a vector already stored) and it returns the top_k nearest records in one namespace, each with a similarity score, and optionally their metadata and values. Reads nothing else and writes nothing.
Pinecone: Search Records
pinecone_search_records
Search a namespace with plain text, with a vector, or by record id, and optionally rerank the results with a hosted reranking model for better ordering. Searching by text needs an index with integrated embedding; searching by vector or by id works on any index.
Action nodes 17
Pinecone: Cancel Import
pinecone_cancel_import
Stop an import that is still running. Records already imported stay in the index, so this halts the job rather than rolling it back, and the import can simply be started again. Has no effect on an import that has already finished.
Pinecone: Configure Index
pinecone_configure_index
Change an existing index in place: scale read capacity or pod size and replicas, turn deletion protection on or off, edit tags, or attach an embedding configuration. Cloud, region, dimension and metric are fixed at creation and cannot be changed here. The call returns 202: check the index status to see when the change has landed.
Pinecone: Create Backup
pinecone_create_backup
Take a backup of an index. This is the only thing that makes Pinecone: Delete Index recoverable, so run it before any bulk rewrite or teardown. Backups are created asynchronously: poll Pinecone: Describe Backup until status is Ready. Restore with Pinecone: Create Index From Backup.
Pinecone: Create Collection
pinecone_create_collection
Snapshot a pod-based index into a new collection. The collection is static: it does not track later writes to the source index. Creation is asynchronous, so poll Pinecone: Describe Collection until status is Ready. Serverless indexes do not support collections.
Pinecone: Create Index
pinecone_create_index
Create an index. The spec object decides where and how it is deployed. Creation is asynchronous: the response comes back with status.state Initializing, and the index only accepts vectors once Pinecone: Describe Index reports ready true. The response carries the new index's data-plane host at data.host.
Pinecone: Create Index From Backup
pinecone_create_index_from_backup
Restore a backup into a NEW index. The existing index is never touched and the new name must be free, so this is safe to run against production. The response returns a restore_job_id: feed it to Pinecone: Describe Restore Job to watch progress.
Pinecone: Create Index With Integrated Embedding
pinecone_create_index_for_model
Create a serverless index that embeds text for you. Pinecone runs a hosted embedding model on write and on search, so you send text instead of vectors and use Pinecone: Upsert Text Records and Pinecone: Search Records against it. The embedding model cannot be changed after creation.
Pinecone: Create Namespace
pinecone_create_namespace
Create an empty namespace explicitly. Usually unnecessary, since upserting into a new name creates it implicitly; the reason to use this node is to set the metadata schema up front so only the fields you name are indexed for filtering. Serverless indexes only.
Pinecone: Delete Backup
pinecone_delete_backup
DESTRUCTIVE AND IRREVERSIBLE. Delete a backup. Anything the backup was the only remaining copy of becomes unrecoverable, which is exactly the situation a backup exists to prevent. Returns 202 with an empty body.
Pinecone: Delete Collection
pinecone_delete_collection
DESTRUCTIVE AND IRREVERSIBLE. Delete a collection and the snapshot it holds. Indexes already created from it are unaffected, but no new index can be seeded from it again. Returns 202 with an empty body.
Pinecone: Delete Index
pinecone_delete_index
DESTRUCTIVE AND IRREVERSIBLE. Delete an index and every vector, namespace and piece of metadata inside it. There is no undo and no trash: the data is recoverable only from a backup taken beforehand. Refused while the index has deletion protection enabled. Returns 202 with an empty body.
Pinecone: Delete Namespace
pinecone_delete_namespace
DESTRUCTIVE AND IRREVERSIBLE. Delete a namespace and every record in it. Pinecone's own guidance is explicit that this cannot be undone and the data is permanently gone. The scope is the whole namespace, however many records that turns out to be. Serverless indexes only.
Pinecone: Delete Vectors
pinecone_delete_vectors
DESTRUCTIVE AND IRREVERSIBLE. Delete records from one namespace. With ids, it removes exactly those records. With delete_all true it WIPES THE ENTIRE NAMESPACE, and with a filter it removes every matching record; in both of those cases the blast radius is whatever happens to be in the index, not a list you checked. Nothing is recoverable without a backup. Run Pinecone: Update Vector with dry_run true to count what a filter matches before deleting by it.
Pinecone: Start Import
pinecone_start_import
Kick off an asynchronous bulk load of Parquet files from object storage into an index. This is the path for large backfills that would take far too many upsert calls. Returns an import id immediately; follow it with Pinecone: Describe Import. The storage bucket must already be connected as a storage integration in the Pinecone console.
Pinecone: Update Vector
pinecone_update_vector
Change part of a record in place. OVERWRITES WHAT IT TOUCHES: values sent here replace the stored vector entirely, and each key in set_metadata replaces that key's stored value. Keys you do not send are left alone. Supplying a filter instead of an id applies the metadata change to EVERY matching record in the namespace, so run it once with dry_run true first and read the returned match count.
Pinecone: Upsert Text Records
pinecone_upsert_records
Write TEXT into an index that has integrated embedding, and let Pinecone produce the vectors with its hosted model. No embedding step of your own is needed. OVERWRITES BY ID the same way the vector upsert does. Works only on indexes made with Pinecone: Create Index With Integrated Embedding.
Pinecone: Upsert Vectors
pinecone_upsert_vectors
Write vectors into a namespace. OVERWRITES BY ID: if a record already exists at that id, its values and its metadata are replaced wholesale, with no error and no merge. Pinecone recommends batches of up to 1000 vectors per call. A namespace that does not exist yet is created implicitly.
Using the integration
On the automation canvas
Pinecone nodes chain with every other node. A webhook from your CMS can embed a changed document upstream and write it with Pinecone: Upsert Vectors, a scheduled sweep can read Pinecone: Describe Index Stats into a Mattering database and open a task when a count drifts, and Pinecone: Query Vectors can supply retrieved context to whatever step comes next. Two values do most of the wiring: the host from Pinecone: List Indexes, which every data-plane node needs, and the namespace, which the read and delete nodes offer as a picker sourced from Pinecone: List Namespaces.
From AI assistants over MCP
Every node speaks MCP, the open protocol for connecting AI assistants to tools, so Claude, ChatGPT, and Matter, the assistant built into the platform, can drive the same surface. An agent can search with Pinecone: Query Vectors or Pinecone: Search Records, look up exact records with Pinecone: Fetch Vectors By Id, and write its own findings back with Pinecone: Upsert Vectors. The read nodes plus the upsert nodes are the comfortable surface to hand an agent; keep the five destructive nodes behind conditions or approval steps. Pinecone publishes MCP servers of its own, and they are worth knowing about before you choose. Its developer MCP server ships as @pinecone-database/mcp, runs locally in your own client config, and carries nine tools: search-docs, list-indexes, describe-index, describe-index-stats, create-index-for-model, upsert-records, search-records, cascading-search and rerank-documents. Pinecone also runs a dedicated MCP server for each Pinecone Assistant. Those are developer tools, so for help writing Pinecone code, Pinecone's server is the better fit. This integration is the operations side of the same platform: 35 nodes across both planes, including namespaces, deletes, backups and restores, and bulk imports, usable as canvas steps as well as over MCP, with the credential held once in the workspace rather than in each developer's local config.
One credential, a host chosen per node
This is the wrinkle worth ten seconds of attention. The credential covers the whole Pinecone project, but each data-plane node carries its own Index Host field because a host belongs to a single index while one key addresses many. The field is a picker sourced from Pinecone: List Indexes: it shows index NAMES, groups them by vector type, and shows each index's deployment state, while the value it saves is the host string Pinecone itself returned. Nothing is resolved at run time and no address is assembled by hand. If you would rather paste, the same value appears in the Pinecone console as the HOST field on an index page, and the connector normalizes it: a bare hostname gets https:// added, a trailing slash or a pasted deeper path is trimmed back to the origin, and a plain http:// host is refused outright, because an API key sent over plain HTTP can be intercepted. Control-plane nodes never show this field, because they always go to the one global host.
Writing vectors without surprises
Neither write node is additive, and knowing which is which prevents most data loss here. Pinecone: Upsert Vectors writes at an id and REPLACES what was there, values and metadata together, with no error and no merge, so send the whole record you intend to store. Pinecone: Update Vector is the partial one: the values you send replace the stored vector, each key you send in the metadata replaces that key, and keys you do not send are left alone. Pinecone's batching guidance has two ceilings, and the second one usually binds first: send a batch as large as you can, up to 1000 records, without exceeding the 2 MB maximum request size, which with real embedding widths is reached well before 1000 records. Text record upserts through Pinecone: Upsert Text Records are capped lower again, at 96 records per call. A namespace that does not exist yet is created implicitly on write, which is why the namespace field on the upsert nodes is free text rather than a picker. Pinecone: Update Vector can also take a metadata filter instead of an id, which applies the change to every matching record in the namespace: run it once with dry run set to true, read the returned match count, and only then let it write. Pinecone documents a maximum of 100,000 records per filter-based update, which is the number the dry run count should be read against. One boundary to check before you plan around this node: Pinecone documents that indexes with integrated embedding do not support updating with text, so on those indexes the update path is the vector-shaped one.
Text records and integrated embedding
If you would rather not run an embedding model of your own, Pinecone: Create Index With Integrated Embedding makes a serverless index that embeds on write and on search with a hosted model. After that, Pinecone: Upsert Text Records takes text instead of vectors and Pinecone: Search Records takes a query string, optionally reranking the results with a hosted reranking model for better ordering, where your Pinecone plan includes hosted reranking models. Three limits to plan around. Pinecone does not document a way to change the embedding model on an existing integrated index, so treat it as a decision to make before the first write. The text path only works on indexes created this way. And Pinecone documents that indexes with integrated embedding do not support updating or importing with text, so on exactly these indexes the partial-update and bulk-import paths stay vector-shaped rather than text-shaped. Pinecone: Search Records can still search by vector or by record id on any index, so the search node is useful either way.
Backups, restores, and bulk imports
Everything in this section depends on the plan first: Pinecone documents backups and restores as available on the Standard and Enterprise plans and not on Starter or Builder, and documents bulk imports from object storage as Standard and Enterprise only. The nodes are in the palette whatever your plan, so confirm the plan itself before designing a workflow that leans on them. After that, asynchronous work follows the same shape three times: start it, then poll. Pinecone: Create Backup snapshots an index and Pinecone: Describe Backup is polled until the status reads Ready. Timing is part of correctness here: Pinecone documents that a backup only includes vectors that were in the index at least 15 minutes before the backup time, so a snapshot taken right after a bulk write will not contain that write. Take the snapshot before the writing starts, or leave a gap after it. Pinecone: Create Index From Backup restores into a NEW index (the source is never touched and the new name must be free, so it is safe to run against production) and returns a restore job id for Pinecone: Describe Restore Job. Pinecone: Start Import bulk loads Parquet files from object storage, Pinecone: Describe Import and Pinecone: List Imports track progress, and Pinecone: Cancel Import halts a job in flight. Cancelling is not an undo: Pinecone documents the status moving to Cancelled but documents no rollback, so treat a cancelled import as partial rather than undone and check the index before restarting it. Storage setup depends on the source. Pinecone requires the bucket to be connected as a storage integration in the console for a SECURE data source, which is console-only setup the API cannot do for you, and explicitly does not require an integration for a public data source.
The five destructive nodes, gated
Pinecone: Delete Index removes an index and every vector, namespace and piece of metadata inside it, with no undo and no trash, recoverable only from a backup taken beforehand. Pinecone: Delete Namespace does the same at namespace scope, and Pinecone's own guidance is explicit that it cannot be undone. Pinecone: Delete Vectors is the subtle one: with ids it removes exactly those records, but with delete all set it wipes the whole namespace and with a metadata filter it removes every match, so in those two forms its scope is whatever is in the index right then. Pinecone: Delete Collection and Pinecone: Delete Backup destroy the only remaining copy of what they hold, and the backup delete is the worst in practice because it removes the recovery path for everything else. The pattern for all five is the same: back up first, gate the delete behind a condition or an approval task rather than a bare trigger, and use the dry run count on Pinecone: Update Vector to size a filter before anything deletes by it. Two caveats on the back-up-first half of that advice. Pinecone documents backups as a Standard and Enterprise feature, so on Starter or Builder there is no snapshot to take and the gating and your source of truth are the whole recovery story. And Pinecone documents that a backup only includes vectors that were in the index at least 15 minutes before the backup time, so a snapshot taken immediately after a write does not protect that write: leave a gap before snapshotting if the workflow just wrote to the index.
Serverless and pod-based, and what differs
Pod-based indexes are still supported, but most readers will be on serverless and may not have the choice: Pinecone documents that customers who signed up for Standard or Enterprise on or after 18 August 2025 cannot create pod-based indexes. Several data-plane operations do not exist for the pod-based ones. Pinecone: List Namespaces, Pinecone: Create Namespace, Pinecone: Describe Namespace, Pinecone: Delete Namespace and Pinecone: List Vector Ids are serverless only, per Pinecone's own notes, and each node says so in its description. One visible consequence: the namespace picker on other nodes is sourced from Pinecone: List Namespaces, so on a pod-based index it will not populate and the field has to be typed. Collections run the other way: Pinecone: Create Collection takes a static snapshot of a POD-BASED index, and serverless indexes do not support collections at all. On a serverless index the backup nodes are the snapshot mechanism instead, on the plans where Pinecone offers them, which is Standard and Enterprise rather than Starter or Builder, so the two are not interchangeable and a Starter project has neither. Index fullness from Pinecone: Describe Index Stats is likewise meaningful only for pod-based indexes.
Troubleshooting
Test Connection fails with a 401 error
A vector node fails while the index and backup nodes work fine
The connector refuses an index host I pasted
A newly created index rejects vectors
A template reading a list of vectors or namespaces resolves to nothing
An upsert wiped metadata that was already on the record
Delete Index returns an error instead of deleting
The namespace picker is empty on an index that definitely has namespaces
Search by text fails on an index that queries fine by vector
Related
The Pinecone MCP
What connecting Pinecone unlocks for AI agents and automations, with common uses and FAQs.
More guides
All Automations documentation
Every integration guide, plus how connectors, credentials, and workflows fit together.
Pinecone is a trademark of its respective owner. Mattering uses platform names to identify the services these integrations connect to; no endorsement or affiliation is implied.