> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pinecone.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Upsert documents
> Upsert documents into a namespace.
Each document must include an `_id` field and the fields required by the index type (for example, `_values` for dense indexes or text fields for full-text search indexes).
[Full-text search](/guides/search/full-text-search) is in [public
preview](/release-notes/feature-availability) 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.
```python Python theme={null}
# 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,
)
```
```shell curl theme={null}
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-01.alpha" \
-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
}
]
}'
```
```jsonc curl theme={null}
// Status: 202 Accepted
{
"upserted_count": 3
}
```
## OpenAPI
````yaml https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-01.alpha/db_data_2026-01.alpha.oas.yaml post /namespaces/{namespace}/documents/upsert
openapi: 3.0.3
info:
title: Pinecone Data Plane API
description: >-
Pinecone is a vector database that makes it easy to search and retrieve
billions of high-dimensional vectors.
contact:
name: Pinecone Support
url: https://support.pinecone.io
email: support@pinecone.io
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
version: 2026-01.alpha
servers:
- url: https://{index_host}
variables:
index_host:
default: unknown
description: host of the index
security:
- ApiKeyAuth: []
tags:
- name: Vector Operations
- name: Bulk Operations
- name: Namespace Operations
- name: Document Operations
externalDocs:
description: More Pinecone.io API docs
url: https://docs.pinecone.io/introduction
paths:
/namespaces/{namespace}/documents/upsert:
post:
tags:
- Document Operations
summary: Upsert documents
description: >-
Upsert documents into a namespace.
Each document must include an `_id` field and the fields required by the
index type (for example, `_values` for dense indexes or text fields for
full-text search indexes).
operationId: upsertDocuments
parameters:
- in: header
name: X-Pinecone-Api-Version
description: Required date-based version header
required: true
schema:
default: 2026-01.alpha
type: string
style: simple
- in: path
name: namespace
description: The namespace to upsert documents into.
required: true
schema:
type: string
style: simple
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpsertDocumentsRequest'
required: true
responses:
'202':
description: The documents were successfully accepted for upsert.
content:
application/json:
schema:
$ref: '#/components/schemas/UpsertDocumentsResponse'
'400':
description: Bad request. The request body included invalid request parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
4XX:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
5XX:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
components:
schemas:
UpsertDocumentsRequest:
example:
documents:
- _id: doc-1
content: Machine learning is a subset of artificial intelligence.
title: Introduction to Machine Learning
- _id: doc-2
content: Deep learning uses neural networks with many layers.
title: Deep Learning Fundamentals
description: The request for the `upsert_documents` operation.
type: object
properties:
documents:
description: The list of documents to upsert into the namespace.
type: array
items:
$ref: '#/components/schemas/DocumentRecord'
minItems: 1
maxItems: 1000
required:
- documents
UpsertDocumentsResponse:
example:
upserted_count: 2
description: The response for the `upsert_documents` operation.
type: object
properties:
upserted_count:
example: 2
description: The number of documents successfully upserted.
type: integer
format: int64
required:
- upserted_count
rpcStatus:
type: object
properties:
code:
type: integer
format: int32
message:
type: string
details:
type: array
items:
$ref: '#/components/schemas/protobufAny'
DocumentRecord:
example:
_id: doc-1
content: Machine learning is a subset of artificial intelligence.
title: Introduction to Machine Learning
description: A document with a unique identifier and arbitrary field values.
type: object
properties:
_id:
description: The unique identifier for the document.
type: string
required:
- _id
additionalProperties: true
protobufAny:
type: object
properties:
typeUrl:
type: string
value:
type: string
format: byte
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: Api-Key
description: >-
An API Key is required to call Pinecone APIs. Get yours from the
[console](https://app.pinecone.io/).
````