Pinecone’s new API gives you the same great vector database but with a drastically improved developer experience over the legacy API.

To use the new API, existing Pinecone client users must:

If you are a new Pinecone user, try the Quickstart to get a vector search service up and running in minutes using the new API.

The legacy version of the API, which required regional URLs for control plane operations, is deprecated as of April 15, 2024 and will be removed in a future, to be announced, release. We recommend migrating to the new API as soon as possible.

Install the latest client version

Python

To install the latest version of the Python client, run the following command:

Shell
pip install pinecone-client[grpc]

# To install a minimal set of dependencies and 
# interact with Pinecone via HTTP requests, use:
# pip install pinecone

If you already have the Python client, run the following command:

Shell
pip install pinecone-client[grpc] --upgrade

Node.js

To install the new version of the Node.js client, run the following command:

Shell
npm install @pinecone-database/pinecone

If you already have the Node.js client, run the following command:

Shell
npm install @pinecone-database/pinecone@latest

Java

You can install the latest version of the Java client from Maven Central for use as a maven dependency in the following ways:

Java
// Maven
<dependency>
  <groupId>io.pinecone</groupId>
  <artifactId>pinecone-client</artifactId>
  <version>1.0.0</version>
</dependency>

// Gradle
implementation "io.pinecone:pinecone-client:1.0.0"

Adapt existing code

The new API requires some code adaptation if you are migrating from the legacy API. This section summarizes the most important changes to address.

For a comprehensive list of changes, see the Python client v3 migration guide and Node.js client v2 migration guide.

Update the URL for control plane operations

On the new API, the global URL for all control plane operations, regardless of cloud environment, is https://api.pinecone.io. The control plane is where you can list indexes, create indexes, list collections, and more.

Authentication

Authenticating with a Pinecone client or the REST API now requires only the API key for your project. The environment parameter is no longer required because you now choose a cloud environment for each index, and all control operations use a global URL (https://api.pinecone.io).

Using the new API, you initialize a client object just with your project API key:

from pinecone.grpc import PineconeGRPC as Pinecone

pc = Pinecone(api_key='YOUR_API_KEY')

Create indexes

In the new API, you can create both serverless and pod-based indexes..

Create a serverless index

To create a serverless index, use the spec parameter to define the cloud and region where the index should be deployed. For Python, you also need to import the ServerlessSpec class.

from pinecone.grpc import PineconeGRPC as Pinecone
from pinecone import ServerlessSpec

pc = Pinecone(api_key="YOUR_API_KEY")

pc.create_index(
    name="serverless-index",
    dimension=1536,
    metric="cosine",
    spec=ServerlessSpec(
        cloud='aws', 
        region='us-east-1'
    ) 
) 

Create a pod-based index

To create a pod-based index, use the spec parameter to define the environment where the index should be deployed, the pod type and size to use, and other index characteristics. For Python, you also need to import the PodSpec class.

from pinecone.grpc import PineconeGRPC as Pinecone, PodSpec

pc = Pinecone(api_key='YOUR_API_KEY')

pc.create_index(
    name='pod-index', 
    dimension=1536, 
    metric='cosine', 
    spec=PodSpec(
        environment="us-west1-gcp", 
        pod_type="p1.x1",
        pods=1
    )
)

List indexes

Using the new API, the list_indexes operation now fetches a complete description of each index. The data returned on each index is equivalent to what you get back from the describe_index operation.

from pinecone.grpc import PineconeGRPC as Pinecone

pc = Pinecone(api_key="YOUR_API_KEY")

pc.list_indexes()

# Response:
# {'indexes': [{'dimension': 1536,
#               'host': 'serverless-index-4zo0ijk.svc.us-west2-aws.pinecone.io',
#               'metric': 'cosine',
#               'name': 'serverless-index',
#               'spec': {'serverless': {'cloud': 'aws', 'region': 'us-east-1'}},
#               'status': {'ready': True, 'state': 'Ready'}},
#              {'dimension': 1536,
#               'host': 'pod-index-4zo0ijk.svc.us-west2-aws.pinecone.io',
#               'metric': 'cosine',
#               'name': 'pod-index',
#               'spec': {'pod': {'environment': 'us-west2-aws',
#                                'pod_type': 'p1.x1',
#                                'pods': 1,
#                                'replicas': 1,
#                                'shards': 1}},
#               'status': {'ready': True, 'state': 'Ready'}}]}

Describe indexes

Using the new API, the describe_index operation returns a description of an index in a different format than the legacy API. It also returns the index endpoint needed to run data plane operations against the index.

from pinecone.grpc import PineconeGRPC as Pinecone

pc = Pinecone(api_key="YOUR_API_KEY")

pc.describe_index("serverless-index")

# Response:
# {'dimension': 1536,
#  'host': 'serverless-index-4zo0ijk.svc.us-weset2-aws.pinecone.io',
#  'metric': 'cosine',
#  'name': 'serverless-index',
#  'spec': {'serverless': {'cloud': 'aws', 'region': 'us-east-1'}},
#  'status': {'ready': True, 'state': 'Ready'}}