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

<Note>
  Upsert replaces the whole document. For partial changes to specific fields, use [`POST /namespaces/{namespace}/documents/update`](/reference/api/2026-07/data-plane/update_documents), which patches fields per ID or in bulk by metadata filter.
</Note>

<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.
</Note>

<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.
</Note>

<RequestExample>
  ```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
        }
      ]
    }'
  ```
</RequestExample>


## OpenAPI

````yaml https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_data_2026-07.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-07
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
    description: >-
      Operations on documents in an index created with a document schema — one
      that declares at least one full-text-searchable string field or a
      `dense_vector` / `sparse_vector` field under a name other than the
      reserved `_values` / `_sparse_values`. Metadata fields alone do not make a
      document schema. Indexes served by the vectors API — created from
      `dimension`/`metric` on an earlier API version, or from a schema holding
      only the reserved vector fields and metadata — and indexes served by the
      records API — created with an integrated embedding model, whose schema
      holds a single `semantic_text` field — reject every document operation
      with `400` and name the API to use instead. A document index accepts only
      the document operations; the vector data operations (upsert, query, fetch,
      update, delete, list) reject it, while index stats and the namespace
      operations remain available.
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 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.
      operationId: upsertDocuments
      parameters:
        - in: header
          name: X-Pinecone-Api-Version
          description: Required date-based version header
          required: true
          schema:
            default: 2026-07
            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'
          links:
            FetchUpsertedDocument:
              description: Look up a document that was just upserted.
              operationId: fetchDocuments
              parameters:
                namespace: $request.path.namespace
            DeleteUpsertedDocument:
              description: Delete a document that was just upserted.
              operationId: deleteDocuments
              parameters:
                namespace: $request.path.namespace
            ListUpsertedDocuments:
              description: List the namespace a document was just written to.
              operationId: listDocuments
              parameters:
                namespace: $request.path.namespace
        '400':
          description: Bad request. The request body included invalid request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 'Unauthorized. Possible causes: missing or invalid API key.'
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/UnauthorizedMessage'
        4XX:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        5XX:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
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: int32
      required:
        - upserted_count
    ErrorResponse:
      example:
        error:
          code: INVALID_ARGUMENT
          message: >-
            No 'ids' or 'filter' provided in the document fetch request. Provide
            at least one document ID in 'ids', or a metadata filter in 'filter'.
        status: 400
      description: >-
        The error response shape returned by the records and documents
        operations. The vector operations return `rpcStatus` instead. Requests
        rejected by the authentication and rate-limiting layer before they reach
        the service (`401`, and the `400`, `403`, and `429` it produces) return
        a plain-text body on every operation.
      type: object
      properties:
        status:
          example: 400
          description: The HTTP status code of the error.
          type: integer
        error:
          description: Detailed information about the error that occurred.
          type: object
          properties:
            code:
              example: INVALID_ARGUMENT
              description: >-
                The error code.

                Possible values: `OK`, `UNKNOWN`, `INVALID_ARGUMENT`,
                `DEADLINE_EXCEEDED`, `NOT_FOUND`, `ALREADY_EXISTS`,
                `PERMISSION_DENIED`, `UNAUTHENTICATED`, `RESOURCE_EXHAUSTED`,
                `FAILED_PRECONDITION`, `ABORTED`, `OUT_OF_RANGE`, `INTERNAL`,
                `FORBIDDEN`, `PAYMENT_REQUIRED`, `SERVICE_UNAVAILABLE`, or
                `PAYLOAD_TOO_LARGE`.
              x-enum:
                - OK
                - UNKNOWN
                - INVALID_ARGUMENT
                - DEADLINE_EXCEEDED
                - NOT_FOUND
                - ALREADY_EXISTS
                - PERMISSION_DENIED
                - UNAUTHENTICATED
                - RESOURCE_EXHAUSTED
                - FAILED_PRECONDITION
                - ABORTED
                - OUT_OF_RANGE
                - INTERNAL
                - FORBIDDEN
                - PAYMENT_REQUIRED
                - SERVICE_UNAVAILABLE
                - PAYLOAD_TOO_LARGE
              type: string
            message:
              example: >-
                No 'ids' or 'filter' provided in the document fetch request.
                Provide at least one document ID in 'ids', or a metadata filter
                in 'filter'.
              description: >-
                A human-readable description of the error, including how to
                correct the request where possible.
              type: string
          required:
            - code
            - message
      required:
        - status
        - error
    UnauthorizedMessage:
      example: Unauthorized
      description: >-
        The plain-text body of a `401` response. Authentication failures are
        rejected before the request reaches the index, so they carry the message
        `Unauthorized` rather than an error object.
      type: string
    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 field values. Fields named in
        the index schema are validated against it; any other field is stored as
        filterable metadata. Every document must carry at least one schema field
        and every schema field the index marks required; a document with only
        `_id` and metadata is rejected. Limits: 2 MB per document and per
        request, 100 KB and 10,000 tokens per full-text-search field value.
      type: object
      properties:
        _id:
          description: The unique identifier for the document.
          type: string
          pattern: ^[\x01-\x7F]+$
          minLength: 1
          maxLength: 512
      required:
        - _id
      additionalProperties:
        $ref: '#/components/schemas/DocumentFieldValue'
    DocumentFieldValue:
      description: >-
        The value of a single document field. Scalar fields carry the same types
        as metadata ("must be a boolean, number, string, or array of strings");
        a field declared in the index schema as `dense_vector` carries an array
        of numbers, and one declared `sparse_vector` carries sparse values.
        Which names are vector fields is a property of the index, not of this
        request.
      anyOf:
        - type: string
        - type: number
        - type: boolean
        - type: array
          items:
            type: string
        - type: array
          items:
            type: number
            format: float
        - $ref: '#/components/schemas/SparseValues'
    SparseValues:
      description: >-
        Vector sparse data. Represented as a list of indices and a list of 
        corresponded values, which must be with the same length.
      type: object
      properties:
        indices:
          example:
            - 1
            - 312
            - 822
            - 14
            - 980
          description: The indices of the sparse data.
          type: array
          items:
            type: integer
            format: int64
            minimum: 0
            maximum: 4294967295
          minItems: 1
          maxItems: 2048
        values:
          example:
            - 0.1
            - 0.2
            - 0.3
            - 0.4
            - 0.5
          description: >-
            The corresponding values of the sparse data, which must be with the
            same length as the indices.
          type: array
          items:
            type: number
            format: float
          minItems: 1
          maxItems: 2048
      required:
        - indices
        - values
  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/).

````