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

:::code-group
```python Python
# 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
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 }'
```
:::

`POST /namespaces/{namespace}/documents/delete`

:::code-group
```json title="202"
{
  "matched_records": 42
}
```

```json title="400"
{
  "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
}
```

```json title="412"
{
  "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
}
```

```json title="4XX"
{
  "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
}
```

```json title="5XX"
{
  "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
}
```
:::

#### Authorizations

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `Api-Key` | `string` | - |  |

An API Key is required to call Pinecone APIs. Get yours from the [console](https://app.pinecone.io/).

#### Headers

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `X-Pinecone-Api-Version` | `string` | `2026-07` | Required date-based version header |

#### Path Parameters

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `namespace` | `string` | - | The namespace to delete documents from. |

#### Body

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `ids?` | `string[]` | - | A list of document IDs to delete. Mutually exclusive with filter and delete_all. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `filter?` | `object` | - | 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. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `delete_all?` | `boolean` | - | If true, delete all documents in the namespace. Mutually exclusive with ids and filter. false is treated as if the field were omitted. |

#### Response

`202` — The delete request was successfully accepted.

The response for the `delete_documents` operation.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `matched_records?` | `integer` | - | 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. Example: 42 |

## Related pages

- [Upsert documents](./database-data-plane-upsert-documents.md)
- [Search documents](./database-data-plane-search-documents.md)
- [Fetch documents](./database-data-plane-fetch-documents.md)
- [List documents](./database-data-plane-list-documents.md)
- [Update documents](./database-data-plane-update-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.