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

# Delete documents

> Delete documents from a namespace. Exactly one of `ids`, `filter`, or `delete_all` must be specified.

- `ids`: Delete documents with the given IDs.
- `filter`: Delete every document matching a metadata filter expression. Text-match operators (`$match_phrase`, `$match_all`, `$match_any`) are not supported in a filtered delete; they are only supported in search. The response reports `matched_records`, the number of documents the filter matched.
- `delete_all`: Delete all documents in the namespace.

<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"

  # Delete by IDs
  index.documents.delete(namespace=NAMESPACE, ids=["doc1", "doc2"])

  # Delete by metadata filter
  index.documents.delete(namespace=NAMESPACE, filter={"category": {"$eq": "news"}})

  # Delete every document in the namespace
  index.documents.delete(namespace=NAMESPACE, delete_all=True)
  ```

  ```shell curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_HOST="articles-abc123.svc.us-east-1.pinecone.io"

  # EXAMPLE REQUEST 1: Delete by IDs
  curl "https://$INDEX_HOST/namespaces/__default__/documents/delete" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "Content-Type: application/json" \
    -H "X-Pinecone-Api-Version: 2026-07" \
    -d '{ "ids": ["doc1", "doc2"] }'

  # EXAMPLE REQUEST 2: Delete by metadata filter
  curl "https://$INDEX_HOST/namespaces/__default__/documents/delete" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "Content-Type: application/json" \
    -H "X-Pinecone-Api-Version: 2026-07" \
    -d '{ "filter": { "category": { "$eq": "news" } } }'

  # EXAMPLE REQUEST 3: Delete all documents in a namespace
  curl "https://$INDEX_HOST/namespaces/__default__/documents/delete" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "Content-Type: application/json" \
    -H "X-Pinecone-Api-Version: 2026-07" \
    -d '{ "delete_all": true }'
  ```
</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/delete
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/delete:
    post:
      tags:
        - Document Operations
      summary: Delete documents
      description: >-
        Delete documents from a namespace. Exactly one of `ids`, `filter`, or
        `delete_all` must be specified.


        - `ids`: Delete documents with the given IDs.

        - `filter`: Delete every document matching a metadata filter expression.
        Text-match operators (`$match_phrase`, `$match_all`, `$match_any`) are
        not supported in a filtered delete; they are only supported in search.
        The response reports `matched_records`, the number of documents the
        filter matched.

        - `delete_all`: Delete all documents in the namespace.
      operationId: deleteDocuments
      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 delete documents from.
          required: true
          schema:
            type: string
          style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteDocumentsRequest'
            examples:
              by_ids:
                summary: Delete specific documents by ID
                value:
                  ids:
                    - doc-1
                    - doc-2
              by_filter:
                summary: Delete every document matching a metadata filter
                value:
                  filter:
                    category:
                      $eq: news
              delete_all:
                summary: Delete every document in the namespace
                value:
                  delete_all: true
        required: true
      responses:
        '202':
          description: The delete request was successfully accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteDocumentsResponse'
              examples:
                by_filter:
                  summary: >-
                    A filtered delete, reporting how many documents the filter
                    matched
                  value:
                    matched_records: 42
                by_ids:
                  summary: A delete by ID or `delete_all`, which reports no count
                  value: {}
        '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:
    DeleteDocumentsRequest:
      description: >-
        The request for the `delete_documents` operation. Exactly one of `ids`,
        `filter`, or `delete_all` must be specified.
      type: object
      properties:
        ids:
          description: >-
            A list of document IDs to delete. Mutually exclusive with `filter`
            and `delete_all`.
          type: array
          items:
            type: string
            pattern: ^[\x01-\x7F]+$
            minLength: 1
            maxLength: 512
          minItems: 1
          maxItems: 1000
        filter:
          example:
            category:
              $eq: news
          description: >-
            A metadata filter expression selecting the documents to delete. Must
            not be empty; an empty filter is rejected rather than matching every
            document. To delete every document in the namespace, set
            `delete_all`. Text-match operators (`$match_phrase`, `$match_all`,
            `$match_any`) are not supported here, since documents are selected
            on metadata alone. Mutually exclusive with `ids` and `delete_all`.
          type: object
          minProperties: 1
        delete_all:
          description: >-
            If `true`, delete all documents in the namespace. Mutually exclusive
            with `ids` and `filter`. `false` is treated as if the field were
            omitted.
          type: boolean
      anyOf:
        - title: By ID
          properties:
            delete_all:
              enum:
                - false
          required:
            - ids
          not:
            required:
              - filter
        - title: By filter
          properties:
            delete_all:
              enum:
                - false
          required:
            - filter
          not:
            required:
              - ids
        - title: Whole namespace
          properties:
            delete_all:
              enum:
                - true
          required:
            - delete_all
          not:
            anyOf:
              - required:
                  - ids
              - required:
                  - filter
    DeleteDocumentsResponse:
      description: The response for the `delete_documents` operation.
      type: object
      properties:
        matched_records:
          example: 42
          description: >-
            The number of documents that matched `filter` when the delete was
            accepted. Only returned for a filtered delete, and omitted when the
            count could not be read in time; `0` means the filter matched no
            documents. The delete is applied asynchronously, so this is a
            point-in-time count rather than a guarantee of the number of
            documents ultimately deleted.
          type: integer
          format: int32
    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
  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/).

````