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

# Pinecone (external store)

> Connect your existing Pinecone index — REST-based, works for serverless and pod-based indexes alike.

# Pinecone

Agentheya calls Pinecone's REST API directly (no SDK). For every chat turn the runtime:

1. Embeds the user query with the embedding provider you configured.
2. Sends `POST https://<your-host>/query` with the vector + your topK + optional filter.
3. Maps the resulting matches into the agent's retrieval context to ground its answer.

## Connection settings

| Field                | Required | Notes                                                                                                                                                                              |
| -------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pinecone_host`      | yes      | Per-index host from the Pinecone console. Looks like `my-index-abc.svc.aped-us-east-1-fkj4.pinecone.io`. Works for both serverless and pod-based indexes. Copy without `https://`. |
| `pinecone_index`     | yes      | Logical index name (e.g. `docs`). Pinecone resolves the same data as the host header, but the field is required so the trace stays readable.                                       |
| `pinecone_namespace` | no       | Optional namespace inside the index. Empty = default namespace.                                                                                                                    |
| `pinecone_api_key`   | yes      | Pinecone API key. Encrypted at rest.                                                                                                                                               |
| `text_field`         | yes      | Name of the metadata field on each vector that holds the original chunk text. Defaults to `text` — change to match your indexing convention.                                       |
| `title_field`        | no       | Optional metadata field used as the citation title. Falls back to the vector's `id`.                                                                                               |
| `source_field`       | no       | Optional metadata field with a URL / origin path for citations.                                                                                                                    |
| `top_k`              | no       | Hits to request per query (1–50, default 8).                                                                                                                                       |
| `filter`             | no       | Native Pinecone metadata filter object. Passed verbatim. Example: `{"tenant": "acme"}`.                                                                                            |

## Embedding settings

Pinecone does not embed on its own — you supply a query vector with each `POST /query`. Agentheya needs the same embedding provider + model your data was indexed with, plus an API key.

| Field                  | Notes                                                                                                                                                                                            |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `embedding_provider`   | One of `openai`, `voyage`, `cohere`.                                                                                                                                                             |
| `embedding_model`      | Model id (e.g. `text-embedding-3-small`, `voyage-3.5`, `embed-english-v3.0`). Must match what your data was indexed with — query and index vectors share the same vector space.                  |
| `embedding_api_key`    | API key for the embedding provider. Encrypted at rest. The owner pays this provider directly; Agentheya does not bill for these calls.                                                           |
| `embedding_dimensions` | Optional sanity check. When set, vectors with the wrong dimension count are rejected before reaching Pinecone (e.g. catches a `text-embedding-3-large` model being used against a 1536-D index). |

## Common shapes

**Standard 1536-D OpenAI setup**:

```json theme={null}
{
  "kind": "pinecone",
  "name": "Acme docs",
  "pinecone_host": "acme-docs-abc.svc.aped-us-east-1-fkj4.pinecone.io",
  "pinecone_index": "acme-docs",
  "pinecone_api_key": "pcsk_...",
  "embedding_provider": "openai",
  "embedding_model": "text-embedding-3-small",
  "embedding_api_key": "sk-...",
  "embedding_dimensions": 1536,
  "text_field": "text",
  "title_field": "title",
  "source_field": "url",
  "top_k": 8
}
```

**Multi-tenant namespace + filter**:

```json theme={null}
{
  "kind": "pinecone",
  "name": "Acme knowledge (tenant=acme)",
  "pinecone_host": "shared-knowledge-abc.svc.aped-us-east-1-fkj4.pinecone.io",
  "pinecone_index": "shared-knowledge",
  "pinecone_namespace": "acme",
  "pinecone_api_key": "pcsk_...",
  "embedding_provider": "voyage",
  "embedding_model": "voyage-3.5",
  "embedding_api_key": "pa-...",
  "filter": { "$or": [ { "category": "public" }, { "owner": "acme" } ] },
  "text_field": "text",
  "top_k": 12
}
```

## "Test connection" button

Hits `POST https://<host>/describe_index_stats` first. If credentials work, the editor runs a one-shot embedding round-trip (when embedding fields are filled in) so a dimension mismatch is caught immediately. Both halves of the result are surfaced inline; either passing is enough to write the connection, but you usually want both.

## Gotchas

* **Wrong host**: Pinecone returns 404 if the host is right but the index name is wrong, and `ENOTFOUND` / connection refused if the host itself is wrong. The "Test connection" button surfaces the raw error.
* **Dimension mismatch**: querying a 1536-D index with `text-embedding-3-large` (3072-D) returns a 400 from Pinecone. Setting `embedding_dimensions` makes Agentheya fail-fast before the request, with a clearer error.
* **Filter syntax**: Pinecone uses MongoDB-flavored filter language (`$and`, `$or`, `$eq`, `$in`, …). Mistakes here surface at chat time, not save time — test with the dashboard editor's connection check.
* **Subscriber scoping**: if you store per-tenant content in one index, use `filter` to scope. Agentheya does not automatically inject `power_user_id` into Pinecone queries today.