Pinecone’s new API gives you the same great vector database but with a drastically improved developer experience over the legacy API. This page summarizes the most important changes. For a comprehensive list, see the Python client v3 migration guide and Node.js client v2 migration guide. Docs for the legacy API remain available at https://docs.pinecone.io/legacy.

​
Improvements

​
Serverless indexes

The new API lets you create serverless indexes for storing and querying your vector data. With serverless indexes, you don’t configure or manage compute and storage resources. You just load your data and your indexes scale automatically based on usage. Likewise, you don’t pay for dedicated resources that may sometimes lay idle. Instead, the pricing model for serverless indexes is consumption-based: You pay only for the amount of data stored and operations performed, with no minimums. You can still create pod-based indexes on the new API as well, and you can also continue to access indexes you created previously on the legacy API. For guidance on creating serverless indexes, see Create indexes. For more on how costs are calculated for serverless indexes, see Understanding cost.
Serverless indexes are in public preview and are available only on AWS in the us-west-2 and us-east-1 regions. Check the current limitations and test thoroughly before using it in production.

​
Multi-region projects

On the legacy API, all indexes in a project are hosted in a single cloud region. On the new API, you have the flexibility to choose a different cloud region for each index. This makes it possible to consolidate related work across regions in a single project.

​
Global URL for control plane operations

On the new API, the global URL for all control plane operations like create_index, describe_index, and list_indexes is https://api.pinecone.io. You use this URL regardless of the cloud environment where an index is hosted. This simplifes the experience compared to the legacy API, where each environment has a unique URL: https://controller.{environment}.pinecone.io.

​
Changes

​
Updated clients

To use the new API, existing users of Pinecone clients must upgrade to new client versions and adapt some code. This page summarizes the most important changes. For a comprehensive list, see the Python client v3 migration guide and Node.js client v2 migration guide.
Python To install the new version of the Python client, run the following command:
Shell
pip install pinecone-client
If you already have the Python client, run the following command:
Shell
pip install pinecone-client --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

​
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). New API Using the new API, you initialize a client object just with your project API key: 
from pinecone import Pinecone

pc = Pinecone(api_key='YOUR_API_KEY')
Legacy API Using the legacy API, you initialize a client with your project API key and environment: 
import pinecone

pinecone.init(api_key="YOUR_API_KEY", environment="YOUR_ENVIRONMENT")

​
Creating indexes

Now that you can create multiple types of indexes (serverless, pod-based, and starter), the syntax for defining indexes has changed compared to the legacy API.

​
Creating a serverless index

Serverless indexes are in public preview and are available only on AWS in the us-west-2 and us-east-1 regions. Check the current limitations and test thoroughly before using it in production.
New API Using the new API, you create a serverless index by importing the ServerlessSpec class and using the spec parameter to define the cloud and region where the index should be deployed: 
from pinecone import Pinecone, ServerlessSpec

pc = Pinecone(api_key="YOUR_API_KEY")

pc.create_index(
    name="serverless-index",
    dimension=1536,
    metric="cosine",
    spec=ServerlessSpec(
        cloud='aws', 
        region='us-west-2'
    ) 
)
Legacy API Serverless indexes cannot be created on the legacy API. You must use the new API.

​
Creating a pod-based index

New API Using the new API, you create a pod-based index by importing the PodSpec class and using the spec parameter to define the environment where the index should be deployed, the pod type and size to use, and other index characteristics: 
from pinecone import 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
    )
)

​
Creating a starter index

On the free Starter plan, you get one project and one pod-based starter index with enough resources to support 100,000 vectors. Although the Starter plan does not support all Pinecone features, it’s easy to upgrade when you’re ready. Starter indexes are hosted in the gcp-starter environment, which is the us-central-1 (Iowa) region of the GCP cloud. New API Using the new API, you create a starter index by importing the PodSpec class and setting environment="gcp-starter" in the spec parameter: 
from pinecone import Pinecone, PodSpec

pc = Pinecone(api_key="YOUR_API_KEY")

pc.create_index(
  name="starter-index",
  dimension=1536,
  metric="cosine",
  spec=PodSpec(
    environment="gcp-starter"
  )
)
Legacy API 
import pinecone

pinecone.init(api_key="YOUR_API_KEY", environment="YOUR_ENVIRONMENT")

pinecone.create_index("starter-index", dimension=1536, metric="cosine")

​
Listing indexes

Using the legacy API, the list_indexes operation returns an array of index names and no other information. Using the new API, the 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. New API 
from pinecone import 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-west-2'}},
#               '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'}}]}
Legacy API Using the legacy API, the list_indexes operation returns an array of index names and no other information. 
import pinecone

pinecone.init(
    api_key='YOUR_API_KEY', 
    environment='PROJECT_ENVIRONMENT'
)

pinecone.list_indexes()

# Response:
# ['sample-movies', 'news']

​
Describing 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 again the index. New API 
from pinecone import 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-west-2'}},
#  'status': {'ready': True, 'state': 'Ready'}}
Legacy API 
import pinecone

pinecone.init(
    api_key='YOUR_API_KEY', 
    environment='PROJECT_ENVIRONMENT'
)

pinecone.describe_index("test-index")

# # Response:
# IndexDescription(
#     name='sample-movies', 
#     metric='cosine', replicas=1, 
#     dimension=1536.0, 
#     shards=1, 
#     pods=1, 
#     pod_type='p1.x1', 
#     status={'ready': True, 'state': 'Ready'}, 
#     metadata_config=None, 
#     source_collection=''
# )

​
Serverless limitations

For serverless limitations, see Limits.

​
Get started

  • Try the Quickstart to get a vector search service up and running in minutes using the new API.