> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudthinker.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Pinecone

> Connect a Pinecone project so agents can inspect indexes and namespaces, search records, and upsert through your Approvals

Connect a Pinecone project to let CloudThinker agents list indexes, read record counts per namespace, search records by text, and create indexes or upsert records through your [Approvals](https://docs.cloudthinker.io/guide/approvals/overview.md). The connection signs in with one Pinecone **project API key**, so it reaches the indexes of that one project only.

## Prerequisites

* A Pinecone project with the indexes you want agents to reach.
* Permission to create API keys in that project.
* For search and writes: indexes created with **integrated embedding**, meaning Pinecone generates the vectors from text using a hosted embedding model. Indexes built from vectors you embedded yourself can be listed and described, but not searched or written through this connection. Not sure which kind you have? Connect, then ask the agent which indexes use integrated embedding.

## Setup

**1. Create an API key**

In the Pinecone console, open the project agents should read and go to **API keys**. Click **Create API key** and name it `cloudthinker`. If your plan shows permission options, set the control plane and data plane to read-only unless agents should write (see [Required permissions](#required-permissions)). Click **Create key**.

**2. Copy the key**

Copy the key right away. Pinecone shows it only once.

**3. Add the connection in CloudThinker**

In the sidebar, click **More → Workspace settings → Connections**, then on the **Builtin Connections** tab select **Pinecone**. Paste the key into **PINECONE\_API\_KEY** and click **Connect**.

**Success state:** the connection shows a **Connected** status. Run the verify prompt below to confirm the key works against your project.

## Connection details

| Field | Required | Description | Example |
| - | - | - | - |
| **Alias** | No | A short name for this connection. Agents and [Rules](https://docs.cloudthinker.io/guide/approvals/rules.md) use it to tell connections apart | `search-prod` |
| **Description** | No | What this project holds. Agents read it to pick the right connection, so make it specific | `Production search indexes for the docs site` |
| **PINECONE\_API\_KEY** | Yes | The field label in the CloudThinker form. Paste the API key for one Pinecone project | `<your-api-key>` |

To reach indexes in another project, add a key from that project as a separate connection.

## Required permissions

| You want agents to | Key needs |
| - | - |
| List and describe indexes | Control plane read |
| Read index stats and search records | Data plane read |
| Create an index | Control plane write |
| Upsert records | Data plane write |

> [!TIP]
>
> Start with a read-only key if your Pinecone plan lets you narrow API key permissions. Some plans only offer full access, in which case approvals in CloudThinker are what stop unwanted writes.

## Agent capabilities

| Capability | What agents can do | Checked by Approvals |
| - | - | - |
| **Index inventory** | List indexes, read each index's configuration, dimensions, record counts, and namespaces | No |
| **Search** | Search one integrated-embedding index by text, or search several at once with deduplicated, reranked results | No |
| **Rerank** | Rerank a list of documents you supply, without an index | No |
| **Create an index** | Create a new integrated-embedding index | Yes |
| **Upsert records** | Insert or update records in a namespace of an integrated-embedding index | Yes |

The connection can't delete records, namespaces, or indexes.

Writes follow your workspace [Approvals](https://docs.cloudthinker.io/guide/approvals/overview.md) Rules and mode, like any other change. When one needs a person, the agent shows you the exact index name, namespace, embedding model, and records first. For a new index, name the cloud and region you want in your prompt, or decline and say which ones to use.

Every change an agent makes goes through your workspace's [Approvals](https://docs.cloudthinker.io/guide/approvals/overview.md) first. On the default **Auto · Rules + AI · Ask me** mode, AI judgment can let a safe change run without asking — and an Allow Rule can too, once CloudThinker turns on [Rule enforcement](https://docs.cloudthinker.io/guide/approvals/rules.md#troubleshooting) for your workspace. Choose **Manual** to approve every change yourself.

> [!WARNING]
>
> Creating a serverless index, embedding records on upsert or search, and reranking all count toward your Pinecone usage and bill. Name the cloud and region in your prompt before an agent creates an index.

### Verify the connection

```text theme={null}
List my Pinecone indexes with each one's record count and namespaces
```

Expect every index in the project with its dimension, record count, and namespaces such as `__default__`.

### Example prompts

```text theme={null}
Which Pinecone indexes use integrated embedding, and how many records does each namespace hold?
Search the docs-search index for "refund policy" and show the five best matches with scores
Upsert these three FAQ records into the faq namespace of docs-search
```

## Troubleshooting

> [accordion] Every request fails with 401
>
> The key is missing, mistyped, deleted, or from a different project. Create a new key in the right project, then edit the connection and paste it into **PINECONE\_API\_KEY**.

> [accordion] Search returns nothing, or an index can't be searched
>
> The index doesn't use integrated embedding, or the namespace is wrong. Ask the agent which indexes use integrated embedding. If you didn't name a namespace, records usually live in `__default__`.

> [accordion] The agent finds no indexes
>
> The project has no indexes yet, or the key belongs to a different project. Check the project in the Pinecone console, or ask the agent to create an integrated-embedding index.

> [accordion] A write fails after I approved it
>
> The key lacks write access, or the target index doesn't use integrated embedding. Check the key's permissions in the Pinecone console.

> [accordion] Requests return 429
>
> Pinecone is rate-limiting the project. Wait a moment, then ask again, and avoid running several large searches at once.

## Security

* **Least privilege** — grant only the permissions the agents need for your use case; start read-only and widen later.
* **Read-only by default** — use read-only credentials unless you want agents to make changes through this connection.
* **Rotate credentials** — rotate keys and tokens on your normal schedule; CloudThinker picks up the new value when you update the connection.
* **Revoke on offboarding** — remove the credential at the provider when you delete a connection or a teammate leaves.

- **One project per key**: create the key in the single project agents should reach, and delete it in Pinecone when you remove the connection.
- **Read-only where your plan allows it**: a key without write access can't create indexes or upsert, whatever gets approved.

## Related

> [card] [Approvals](https://docs.cloudthinker.io/guide/approvals/overview.md)
>
> Decide which index creations and upserts run, wait for a person, or are refused.

> [card] [Connections overview](https://docs.cloudthinker.io/guide/connections/overview.md)
>
> Rotate the key, set the environment, and see every connection.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.