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:

Legacy API

Using the legacy API, you initialize a client with your project API key and 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:

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:

​
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:

Legacy API

​
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

Legacy API

Using the legacy API, the list_indexes operation returns an array of index names and no other information.

​
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

Legacy API

​
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.

Was this page helpful?