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

```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 }'
```

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

:::code-group
```bash title="cURL"
curl --request POST \
  --url https://{index_host}/namespaces/{namespace}/documents/delete \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "delete_all": false
}'
```

```json title="202"
{
  "matched_records": 42
}
```
:::

## Authorizations

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

## Path Parameters

- `namespace` (path, string, required) — The namespace to delete documents from.

## Headers

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

## Body

- `ids` (body, string\[]) — A list of document IDs to delete. Mutually exclusive with `filter` and `delete_all`.
- `filter` (body, 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`.
- `delete_all` (body, 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.
- `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

- [Upsert documents](./database-2026-07-data-plane-upsert-documents.md)
- [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)

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