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.
HTTP status code | Description |
---|---|
200 - OK | The request was successful. |
201 - CREATED | The request was successful and a new resource was created. |
202 - NO CONTENT | The request was successful, but there is no content to return. |
400 - INVALID ARGUMENT | The request was unsuccessful due to an invalid argument. |
401 - UNAUTHENTICATED | The API key is missing or invalid. |
403 - QUOTA_EXCEEDED | The request was unsuccessful due to an exceeded quota. |
404 - NOT FOUND | The request was unsuccessful because the resource was not found. |
409 - ALREADY EXISTS | The request was unsuccessful because the resource already exists. |
412 - FAILED PRECONDITIONS | The request was unsuccessful due to preconditions not being met. |
422 - UNPROCESSABLE ENTITY | The request was unsuccessful because the server was unable to process the contained instructions. |
429 - TOO MANY REQUESTS | The request was rate-limited. |
500 - UNKNOWN | An internal server error occurred. |
Was this page helpful?