Skip to main content
POST
/
namespaces
/
{namespace}
/
documents
/
upsert
# pip install --upgrade pinecone
import os
from pinecone import Pinecone

pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"])
index = pc.preview.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,
)

// Status: 202 Accepted
{
  "upserted_count": 3
}
Full-text search is in public preview and uses API version 2026-01.alpha. APIs may continue to evolve before general availability.
Inserts or updates schema-defined documents in a namespace. 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.
No partial updates. To change one field on an existing document, fetch the document, modify the fields client-side, and upsert the full document back. There is currently no per-field update endpoint.
Each item in the documents array is validated against your index schema. If any item fails validation, the entire request fails and nothing is upserted. Field names starting with _ (reserved for system-managed fields like _id and _score) or $ (reserved for filter operators) are rejected.
Ingesting many documents? The Python SDK ships index.documents.batch_upsert(documents=..., batch_size=..., max_workers=..., show_progress=...), a client-side convenience that splits a large list into batches and issues concurrent POST /namespaces/{namespace}/documents/upsert requests in the background. It’s a wrapper around this endpoint, not a separate API.
# pip install --upgrade pinecone
import os
from pinecone import Pinecone

pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"])
index = pc.preview.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,
)

// Status: 202 Accepted
{
  "upserted_count": 3
}

Authorizations

​
Api-Key
string
header
required

An API Key is required to call Pinecone APIs. Get yours from the console.

Headers

​
X-Pinecone-Api-Version
string
default:2026-01.alpha
required

Required date-based version header

Path Parameters

​
namespace
string
required

The namespace to upsert documents into.

Body

application/json

The request for the upsert_documents operation.

​
documents
object[]
required

The list of documents to upsert into the namespace.

Required array length: 1 - 1000 elements

Response

The documents were successfully accepted for upsert.

The response for the upsert_documents operation.

​
upserted_count
integer<int64>
required

The number of documents successfully upserted.

Example:

2