Upsert text
Upsert text into a namespace. Pinecone converts the text to vectors automatically using the hosted embedding model associated with the index.
Upserting text is supported only for indexes with integrated embedding; for any other index the request is rejected with 400. It is not available on BYOC indexes.
A request can contain at most 1000 records. Each record is identified by _id. The service also accepts id as an alias, which this schema does not model; a record must not carry both.
For guidance, examples, and limits, see Upsert data.
# To get the unique host for an index,
# see https://docs.pinecone.io/guides/manage-data/target-an-index
INDEX_HOST="INDEX_HOST"
NAMESPACE="YOUR_NAMESPACE"
PINECONE_API_KEY="YOUR_API_KEY"
# Upsert records into a namespace
# `chunk_text` fields are converted to dense vectors
# `category` fields are stored as metadata
curl "https://$INDEX_HOST/records/namespaces/$NAMESPACE/upsert" \
-H "Content-Type: application/x-ndjson" \
-H "Api-Key: $PINECONE_API_KEY" \
-H "X-Pinecone-Api-Version: 2026-07" \
-d '{"_id": "rec1", "chunk_text": "Apples are a great source of dietary fiber, which supports digestion and helps maintain a healthy gut.", "category": "digestive system"}
{"_id": "rec2", "chunk_text": "Apples originated in Central Asia and have been cultivated for thousands of years, with over 7,500 varieties available today.", "category": "cultivation"}
{"_id": "rec3", "chunk_text": "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases.", "category": "immune system"}
{"_id": "rec4", "chunk_text": "The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes.", "category": "endocrine system"}'POST /records/namespaces/{namespace}/upsert
{
"error": {
"code": "INVALID_ARGUMENT",
"message": "No 'ids' or 'filter' provided in the document fetch request. Provide at least one document ID in 'ids', or a metadata filter in 'filter'."
},
"status": 400
}{
"error": {
"code": "INVALID_ARGUMENT",
"message": "No 'ids' or 'filter' provided in the document fetch request. Provide at least one document ID in 'ids', or a metadata filter in 'filter'."
},
"status": 400
}{
"error": {
"code": "INVALID_ARGUMENT",
"message": "No 'ids' or 'filter' provided in the document fetch request. Provide at least one document ID in 'ids', or a metadata filter in 'filter'."
},
"status": 400
}{
"error": {
"code": "INVALID_ARGUMENT",
"message": "No 'ids' or 'filter' provided in the document fetch request. Provide at least one document ID in 'ids', or a metadata filter in 'filter'."
},
"status": 400
}Authorizations
Section titled “Authorizations”Api-KeystringrequiredAn API Key is required to call Pinecone APIs. Get yours from the console.
Headers
Section titled “Headers”X-Pinecone-Api-VersionstringrequiredRequired date-based version header
Path Parameters
Section titled “Path Parameters”namespacestringrequiredThe namespace to upsert records into.
Each record in the request body must include an _id field and a field that matches your index's field_map configuration (such as chunk_text or data). All other fields are stored as metadata.
_idstringrequiredThe unique ID of the record to upsert. The service also accepts id as an alias, which this schema does not model.
Required string length: 1+
Response
Section titled “Response”201 — A successful response.