Introduction

The Pinecone REST APIs let you interact programmatically with your Pinecone account using HTTP requests.

​

APIs

Pinecone provides three distinct APIs:

• Database API: Use the Database API to store and query records in the Pinecone vector database. This API is comprised of data plane and control plane endpoints.

  • The data plane handles requests to write and read records in indexes. Indexes are partitioned into one or more logical namespaces, and all write and read requests are scoped by namespace.

    For each index, there is a unique URL for performing data plane operations in the form of https://{index_host}/{operation}. The Pinecone SDKs construct these URLs for you. However, when using the API directly, you must explicitly specify them.

    You can get index URLs in the Pinecone console or using the describe_index operation. For more details, see Get an index endpoint.

  • The control plane handles requests to create and manage indexes and collections.

    The global URL for all control plane operations is https://api.pinecone.io. You use this URL regardless of the cloud environment where an index is hosted.

• Inference API: Use the Inference API to generate embeddings for text data such as queries or passages and to rerank items like text documents.

• Assistant API: Use the Assistant API to upload documents, ask questions, and receive responses that reference your documents. This is known as retrieval-augmented generation (RAG).

​

Authentication

All HTTP requests to Pinecone APIs must contain an Api-Key header that specifies a valid API key and must be encoded as JSON with the Content-Type: application/json header.

​

Response codes

When Pinecone receives a request to an API endpoint, a number of different HTTP status codes can be returned in the response depending on the original request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided, and codes in the 5xx range indicate an error with Pinecone’s servers.