Upsert records
Upsert records into a namespace. If a new value is upserted for an existing record ID, it will overwrite the previous value.
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
PINECONE_API_KEY="YOUR_API_KEY"
INDEX_HOST="INDEX_HOST"
curl "https://$INDEX_HOST/vectors/upsert" \
-H "Api-Key: $PINECONE_API_KEY" \
-H 'Content-Type: application/json' \
-H "X-Pinecone-Api-Version: 2026-07" \
-d '{
"vectors": [
{
"id": "vec1",
"values": [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1],
"metadata": {"genre": "comedy", "year": 2020}
},
{
"id": "vec2",
"values": [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2],
"metadata": {"genre": "documentary", "year": 2019}
}
],
"namespace": "example-namespace"
}'POST /vectors/upsert
{
"upsertedCount": 2
}{
"code": 123,
"message": "<string>",
"details": [
{
"typeUrl": "<string>",
"value": "<string>"
}
]
}{
"code": 123,
"message": "<string>",
"details": [
{
"typeUrl": "<string>",
"value": "<string>"
}
]
}{
"code": 123,
"message": "<string>",
"details": [
{
"typeUrl": "<string>",
"value": "<string>"
}
]
}{
"code": 123,
"message": "<string>",
"details": [
{
"typeUrl": "<string>",
"value": "<string>"
}
]
}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
vectorsobject[]requiredAn array containing the vectors to upsert. Recommended batch limit is up to 1000 vectors.
Show child attributes
idstringrequiredThis is the vector's unique id.
Required string length: 1 - 512. Example: example-vector-1
values?number[]This is the vector data. On a request it must be non-empty, and at least one value must have a magnitude of 1e-8 or greater — a vector whose values are all smaller than that is rejected as containing only zeros. On a response this is an empty array whenever the record has no dense data to return: on a sparse index, and on any index when values were not requested. The array is therefore not constrained here, because this schema describes both directions.
sparseValues?objectVector sparse data. Represented as a list of indices and a list of corresponded values, which must be with the same length.
Show child attributes
indicesinteger[]requiredThe indices of the sparse data.
valuesnumber[]requiredThe corresponding values of the sparse data, which must be with the same length as the indices.
metadata?objectThis is the metadata included in the request. Field names may not begin with $, which is reserved for filter operators. Every other name is accepted, including names that are empty, non-ASCII, or begin with _.
namespace?stringThe namespace where you upsert records.
Example: example-namespace
Response
Section titled “Response”200 — A successful response.
The response for the upsert operation.
upsertedCount?integerThe number of vectors upserted.
Example: 2