Upsert documents
Upsert documents into a namespace.
Each document must include an _id field and at least one field defined in the index schema; metadata fields may be
provided alongside them.
Any metadata field you provide that is not declared in the schema is stored on the document, returned via include_fields, and
automatically indexed for filtering.
If a document with the same _id already exists, it is completely replaced. Documents become searchable within approximately one minute. The namespace is auto-created on first upsert; use "__default__" if you don't need partitioning.
# pip install --upgrade pinecone
import os
from pinecone import Pinecone
pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"])
index = pc.Index(name="articles")
NAMESPACE = "example-namespace"
docs = [
{"_id": "doc1", "title": "Machine learning in 2024", "body": "Machine learning models are revolutionizing natural language processing", "category": "technology", "year": 2024},
{"_id": "doc2", "title": "Vector databases", "body": "Vector databases enable fast similarity search across embeddings", "category": "technology", "year": 2023},
{"_id": "doc3", "title": "Quantum computing", "body": "Quantum computers leverage superposition for faster computation", "category": "science", "year": 2024},
]
index.documents.upsert(
namespace=NAMESPACE,
documents=docs,
)PINECONE_API_KEY="YOUR_API_KEY"
INDEX_HOST="articles-abc123.svc.us-east-1.pinecone.io"
curl "https://$INDEX_HOST/namespaces/__default__/documents/upsert" \
-H "Api-Key: $PINECONE_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Pinecone-Api-Version: 2026-07" \
-d '{
"documents": [
{
"_id": "doc1",
"title": "Machine learning in 2024",
"body": "Machine learning models are revolutionizing natural language processing",
"category": "technology",
"year": 2024
},
{
"_id": "doc2",
"title": "Vector databases",
"body": "Vector databases enable fast similarity search across embeddings",
"category": "technology",
"year": 2023
},
{
"_id": "doc3",
"title": "Quantum computing",
"body": "Quantum computers leverage superposition for faster computation",
"category": "science",
"year": 2024
}
]
}'POST /namespaces/{namespace}/documents/upsert
Parameters
Section titled “Parameters”X-Pinecone-Api-Version(header, string, required) — Required date-based version headernamespace(path, string, required) — The namespace to upsert documents into.
Request body
Section titled “Request body”documents(body, object[], required) — The list of documents to upsert into the namespace.
Responses
Section titled “Responses”202— The documents were successfully accepted for upsert.400— Bad request. The request body included invalid request parameters.401— Unauthorized. Possible causes: missing or invalid API key.4XX— An unexpected error response.5XX— An unexpected error response.