{
  "compilerOptions": {
    "target": "ES2020",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "esModuleInterop": true,
    "types": ["node"],
    "baseUrl": ".",
    "paths": {
      "@pinecone-sdk/*": ["src/pinecone-sdk/*"]
    }
  },
  "include": ["src"]
}

3. Set the required environment variable before running your application:

export PINECONE_API_KEY=your_api_key_here

Alternatively, pass apiKey directly in the Pinecone constructor (see examples below).

4. Import from the barrel in your application code:

import { Pinecone, Index, Inference, Assistant } from './pinecone-sdk/index';

5. Node.js version: Ensure Node.js >= 20.0.0. The SDK uses modern built-in APIs.

Public API

Pinecone

class Pinecone {
  constructor(config?: { apiKey?: string });
  index(options: { host: string } | string): Index;
  createIndex(options: CreateIndexOptions): Promise<IndexModel>;
  listIndexes(): Promise<IndexList>;
  describeIndex(options: DescribeIndexOptions): Promise<IndexModel>;
  deleteIndex(options: DeleteIndexOptions): Promise<void>;
  inference: Inference;
  assistant: { Assistant(name: string): Assistant };
}

The Pinecone class is the primary entry point. Instantiate it once per process. If apiKey is omitted, it reads PINECONE_API_KEY from the environment. Use pc.index() to get a handle for vector data operations and pc.inference for embedding/reranking.

Index

class Index<T extends RecordMetadata = RecordMetadata> {
  upsert(options: UpsertOptions): Promise<void>;
  query(options: QueryOptions): Promise<QueryResponse>;
  fetch(options: FetchOptions): Promise<FetchResponse>;
  deleteOne(options: DeleteOneOptions): Promise<void>;
  deleteMany(options: DeleteManyOptions): Promise<void>;
  deleteAll(options?: DeleteAllOptions): Promise<void>;
  describeIndexStats(options?: DescribeIndexStatsOptions): Promise<IndexStatsDescription>;
  listPaginated(options?: ListOptions): Promise<ListResponse>;
  namespace(name: string): Index<T>;
  upsertRecords(options: UpsertRecordsOptions): Promise<void>;
  searchRecords(options: SearchRecordsOptions): Promise<SearchRecordsResponse>;
}

Index handles all vector-level data plane operations. Use index.namespace('my-namespace') to scope operations to a specific namespace. The generic T parameter constrains metadata types for type safety.

Inference

class Inference {
  embed(options: EmbedOptions): Promise<EmbeddingsList>;
  rerank(options: RerankOptions): Promise<RerankResult>;
  listModels(options?: ListModelsOptions): Promise<ModelInfoList>;
}

Inference provides access to Pinecone-hosted embedding and reranking models. Use embed to convert text to vectors without managing an external model provider, and rerank to score and order search results by relevance.

Assistant

class Assistant {
  chat(options: ChatOptions): Promise<ChatModel>;
  chatStream(options: ChatOptions): Promise<ChatStream>;
  chatCompletion(options: ChatCompletionOptions): Promise<ChatCompletionModel>;
  chatCompletionStream(options: ChatCompletionOptions): Promise<ChatStream>;
  context(options: ContextOptions): Promise<ContextModel>;
  uploadFile(options: UploadFileOptions): Promise<AssistantFileModel>;
  listFiles(options?: ListFilesOptions): Promise<AssistantFilesList>;
  describeFile(fileId: string): Promise<AssistantFileModel>;
  deleteFile(fileId: string): Promise<void>;
}

Assistant wraps a named Pinecone Assistant and exposes chat, context retrieval, and file management. Streaming variants return an async-iterable ChatStream.

Working examples

Scenario - Create an index and upsert vectors

Create a serverless index, upsert records with metadata, then run a nearest-neighbor query with a metadata filter.

import { Pinecone } from './pinecone-sdk/index';

const pc = new Pinecone({ apiKey: process.env.PINECONE_API_KEY! });

async function main() {
  const indexModel = await pc.createIndex({
    name: 'product-search',
    dimension: 1536,
    metric: 'cosine',
    spec: {
      serverless: { cloud: 'aws', region: 'us-east-1' },
    },
    waitUntilReady: true,
  });

  const index = pc.index({ host: indexModel.host! });

  await index.upsert({
    records: [
      { id: 'p1', values: Array(1536).fill(0.1), metadata: { category: 'shoes', price: 59 } },
      { id: 'p2', values: Array(1536).fill(0.2), metadata: { category: 'hats', price: 25 } },
    ],
  });

  const result = await index.query({
    vector: Array(1536).fill(0.1),
    topK: 5,
    filter: { category: { $eq: 'shoes' } },
    includeMetadata: true,
  });

  console.log(result.matches);
}

main();

Scenario - Embed text and search with integrated inference

Use Pinecone's hosted embedding model to convert text queries to vectors, then search without maintaining a separate embedding service.

import { Pinecone } from './pinecone-sdk/index';
import type { EmbedOptions } from './pinecone-sdk/index';

const pc = new Pinecone({ apiKey: process.env.PINECONE_API_KEY! });

async function semanticSearch(query: string) {
  const embedOptions: EmbedOptions = {
    model: 'multilingual-e5-large',
    inputs: [{ text: query }],
  };

  const embeddings = await pc.inference.embed(embedOptions);
  const queryVector = embeddings.data[0].values as number[];

  const index = pc.index({ host: process.env.INDEX_HOST! });
  const results = await index.query({
    vector: queryVector,
    topK: 10,
    includeMetadata: true,
  });

  return results.matches;
}

semanticSearch('comfortable running shoes under $100').then(console.log);

Scenario - Chat with a Pinecone Assistant using streaming

Instantiate a named Assistant, upload a document, then stream a chat response back to a client.

import { Pinecone } from './pinecone-sdk/index';
import type { ChatOptions } from './pinecone-sdk/index';
import * as fs from 'fs';

const pc = new Pinecone({ apiKey: process.env.PINECONE_API_KEY! });

async function assistantDemo() {
  // Assumes assistant named 'my-assistant' already created via pc.assistant.createAssistant(...)
  const assistant = pc.assistant.Assistant('my-assistant');

  // Upload a file for context
  await assistant.uploadFile({
    path: './docs/product-catalog.pdf',
    metadata: { source: 'catalog-2024' },
  });

  const chatOptions: ChatOptions = {
    messages: [{ role: 'user', content: 'Summarize the product catalog.' }],
  };

  const stream = await assistant.chatStream(chatOptions);

  for await (const chunk of stream) {
    if (chunk.type === 'content_chunk') {
      process.stdout.write(chunk.delta?.content ?? '');
    }
  }
}

assistantDemo();

File walkthrough

• index.ts: Public barrel; re-exports Pinecone, Index, Inference, Assistant, ChatStream, Errors, and all public types. Import everything from here.
• pinecone.ts: The Pinecone class implementation. Wires together control-plane, data-plane, inference, and assistant sub-clients.
• types.ts: Shared interfaces (IndexOptions, AssistantOptions) used internally and by sub-modules.
• version.json: Supplies the SDK version string injected into HTTP User-Agent headers.
• control/: Functions for index lifecycle (create, configure, delete, describe, list), collection management, and backup/restore job operations.
• data/: Index class implementation plus sub-modules for vector CRUD (vectors/), bulk S3 imports (bulk/), and namespace management (namespaces/).
• inference/: Inference class wrapping embed, rerank, and list-models endpoints.
• assistant/: Assistant class and ChatStream; sub-divided into control/ (CRUD for assistants) and data/ (chat, file operations, context retrieval).
• errors/: Typed Pinecone error classes (PineconeArgumentError, etc.) for structured error handling.
• utils/: Internal utilities (retry logic, HTTP helpers). Not part of the public API.
• pinecone-generated-ts-fetch/: Auto-generated fetch-based API clients for inference, db_data, and other Pinecone REST services. Do not import directly; used by SDK internals.
• integration/: Test scaffolding for integration tests. Not for production use.

Common pitfalls and fixes

• Missing PINECONE_API_KEY: The SDK throws at runtime if neither the env var nor apiKey config is provided. Always set the env var in production or pass apiKey explicitly.
• host vs index name: pc.index({ host: indexModel.host }) requires the full host string (e.g. https://my-index-xxxx.svc.pinecone.io), not just the index name. Retrieve host from describeIndex or createIndex response.
• TypeScript moduleResolution: The SDK uses NodeNext-compatible imports. Set "moduleResolution": "NodeNext" or "Bundler" in tsconfig.json; "node" (legacy) may cause resolution failures.
• Node.js version < 20: Native fetch and ReadableStream are required. Running on Node 18 may cause subtle failures; upgrade to Node >= 20.
• Streaming chunk types: ChatStream yields typed chunks (content_chunk, message_start, etc.). Always check chunk.type before accessing chunk.delta or chunk.message to avoid runtime errors.
• Index not ready: Upserting immediately after createIndex without waitUntilReady: true results in 404 or 503 errors. Pass waitUntilReady: true in createIndex options or poll describeIndex until status.ready === true.

Vibe-coding prompt template

I have the Pinecone TypeScript SDK source located at `src/pinecone-sdk/` in my project.
There is a USAGE.md file at the root of that directory explaining all available exports,
types, and working examples. The upstream package is `@pinecone-database/pinecone@7.2.0`.

Please help me integrate this SDK into my existing Node.js/TypeScript project step by step:

1. Read USAGE.md and `src/pinecone-sdk/index.ts` to understand all public exports.
2. Set up the necessary tsconfig paths so I can import from `src/pinecone-sdk/index`.
3. Create a `PineconeService` wrapper class in `src/services/pinecone.service.ts` that:
   - Initializes `Pinecone` using the `PINECONE_API_KEY` environment variable
   - Exposes typed methods for: upsert, query, embed (via inference), and deleteAll
   - Handles errors using the `Errors` namespace from the SDK
4. Wire the service into my existing Express router at `src/routes/search.ts`.
5. Add a `.env.example` entry for `PINECONE_API_KEY` and `INDEX_HOST`.
6. Show me a working end-to-end example for semantic search using the integrated
   inference embed model, querying the index, and returning results as JSON.

Use only the exports visible in USAGE.md. Do not invent new APIs.

License and credit

The Pinecone TypeScript SDK is released under the Apache 2.0 License (see source/LICENSE if present, or the upstream repository). This block wraps the unmodified SDK source from @pinecone-database/pinecone@7.2.0 published by Pinecone Systems, Inc.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

Milvus Node SDK for Vector Database Operations

Automation, Utilities & Developer Tools

Free