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.

:::callout{intent="note"}
Upsert replaces the whole document. For partial changes to specific fields, use [`POST /namespaces/{namespace}/documents/update`](/guides/database-2026-07-data-plane-update-documents), which patches fields per ID or in bulk by metadata filter.
:::

:::callout{intent="note"}
Each document in the `documents` array is validated against your index schema. If any document 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.
:::

:::callout{intent="note"}
To ingest many documents, use the Python SDK's `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.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-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`

:::code-group
```bash title="cURL"
curl --request POST \
  --url https://{index_host}/namespaces/{namespace}/documents/upsert \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "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"
    }
  ]
}'
```

```json title="202"
{
  "upserted_count": 2
}
```
:::

## Authorizations

- `Authorization` (header, string, required) — Bearer authentication header of the form `Bearer <token>`.

## Path Parameters

- `namespace` (path, string, required) — The namespace to upsert documents into.

## Headers

- `X-Pinecone-Api-Version` (header, string, required) — Required date-based version header

## Body

- `documents` (body, object\[], required) — The list of documents to upsert into the namespace.

## Response

- `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.

## Related pages

- [Search documents](./database-2026-07-data-plane-search-documents.md)
- [Fetch documents](./database-2026-07-data-plane-fetch-documents.md)
- [List documents](./database-2026-07-data-plane-list-documents.md)
- [Update documents](./database-2026-07-data-plane-update-documents.md)
- [Delete documents](./database-2026-07-data-plane-delete-documents.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.