# Delete Vectors by Metadata

`POST /vectors/{collection}/delete` · Core · Data, Queries & Vectors

Deletes the rows of a `_`-prefixed vector collection that match every equality in `filters`, and answers `{ deleted, collection }` with the count removed.

`filters` must include at least one `metadata.<key>` equality. `id`, `contentHash` and `source.<key>` can narrow it but are refused on their own, and an empty `filters` is refused rather than deleting everything.

Each row goes with its vector, text, metadata and content hash. Needs the same `vectors write` grant on the collection as an upsert. Each call writes one audit event with the collection and the count, never the filter.

## Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `collection` | path | yes | The derived collection's name. It starts with `_`. Example: `"_context_chunks"`. |
| `projectSlug` | path | yes | The project's slug: the path segment after `@`. It is unique within the org. Example: `"storefront"`. |

## Request body

| Field | Type | Required | Description |
|---|---|---|---|
| `filters` | object | yes | Equality filters; every one must match. At least one `metadata.<key>` path is required. `id`, `contentHash` and `source.<key>` may be added to narrow it. Each key is a path and each value the string, number or boolean it must equal. An empty object, or one with no `metadata.<key>` path, gets 400 `K9O_INVALID_FIELD_VALUE`: an empty filter never deletes everything. |

## Responses

- **200**: Success

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | object | yes |  |
| `data.deleted` | integer | yes | How many chunks were removed, with their stored text, vectors and content hashes. 0 when nothing matched. |
| `data.collection` | string | yes | The derived collection deleted from. |
| `meta` | object | yes | Request metadata: request id, trace id, timing and cost. |


## Errors

| HTTP | Code | When |
|---|---|---|
| 400 | `K9O_INVALID_FIELD_VALUE` | The project identifier in the request path is not valid. |
| 403 | `K9O_RESERVED_COLUMN_WRITE_PROHIBITED` | Vector deletes are only allowed in an extension's own '_'-prefixed derived collection; this collection name is not one. |
| 400 | `K9O_INVALID_FIELD_VALUE` | filters is empty or has no metadata.<key> equality; id, contentHash and source.<key> can only narrow one. |
| 400 | `K9O_INVALID_FIELD_VALUE` | The filters object referenced an unsupported path; only id, contentHash, source.<key>, and metadata.<key> are allowed. |
| 403 | `K9O_ACCESS_DENIED` | The caller is not a member of this project. |
| 403 | `K9O_EXTENSION_PERMISSION_DENIED` | An extension token without the vectors write grant on this collection. |
| 404 | `K9O_COLLECTION_NOT_FOUND` | This derived vector collection has never been upserted into, so there is nothing to delete. |
| 403 | `K9O_IAM_POLICY_DENIED` | The caller's project role can read vector data but not change it (reason read_only_role): only admin, editor, member and author roles write, as for storage objects. |

## Code samples

### cURL

```bash
curl -X POST 'https://<org>.api-<region>.k9o.io/@storefront/vectors/products/delete' \
  -H 'Authorization: Bearer $K9O_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

### fetch

```javascript
const res = await fetch('https://<org>.api-<region>.k9o.io/@storefront/vectors/products/delete', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.K9O_TOKEN}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({}),
});
const { data, meta } = await res.json();
```


Canonical page: https://docs.kilimanjaro.dev/api-playground/core/delete-vectors-by-metadata
