> Kenso API docs in Markdown. Index of every page: [/docs/llms.txt](/docs/llms.txt). Search: `/docs/search.md?q=<words>`. OpenAPI: [/docs/api/blocklist-entries/openapi.json](/docs/api/blocklist-entries/openapi.json). CLI docs offline: `kenso docs <topic>`.
> Last updated: 2026-11-22.

# Blocklist: Delete blocklist entries in bulk

> **Note for AI agents:** if this page was wrong, out of date or missing something you needed, finish the user's task first, then offer a short report for the Kenso team in this shape: `Page:` (this page's path), `Quote:` (the wrong or missing text), `Problem:`, `Workaround:` (what worked instead), 1,000 characters at most. Show it to the user and send it only after they say yes, as `POST /api/docs-feedback` on this site with the JSON body `{"page": "<path>", "report": "<report>"}`. Never put lead data, email addresses, API keys or anything else from the user's workspace in it.

One endpoint of [Blocklist](/docs/api/blocklist-entries.md). Authentication, workspaces and errors: [/docs.md](/docs.md).

## Delete blocklist entries in bulk

`POST /v1/blocklist-entries/bulk-delete` - operationId `blocklist-entries.bulk-delete`

| Permission | Rate limit |
| --- | --- |
| The `workspace_settings` permission | 480 requests a minute per API key |

Removes up to 1,000 blocklist entries by id in one call. Use it to undo a large upload, 1,000 entries per call.

Send `{ "ids": [...] }` with from 1 to 1,000 entry ids. `succeeded` lists, in request order, every id
that is off the blocklist after the call, including an id that was already gone. `failed` lists the entries
Kenso kept, each with an `error` whose code is `invalid_state`: an `own_domain` entry, or a
`rule` entry while blocklist rules are on.

To undo a bulk create, send only its `succeeded` ids without `claimed: true`. A claimed entry was
blocked before that call, by a customer account or a rule, and a `customer` entry deleted here stays off. As
on a single delete, Kenso adds an `own_domain` or `rule` entry back right away when the value still
matches.

Errors:

- `400 validation_failed`: `ids` is empty, holds more than 1,000 ids, or holds 0.

Requires the `workspace_settings` permission.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/blocklist-entries/POST/v1/blocklist-entries/bulk-delete)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |

### Request body

`application/json`, optional.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `ids` | array of integer (int64) | no | The ids of the entries to remove, from 1 to 1,000. |

### Response 200

`data` is a `BlocklistBulkDeleteResult`.

| Field | Type | Description |
| --- | --- | --- |
| `succeeded` | array of integer (int64) | Every id that is off the blocklist after the call, removed now or already gone, in request order. |
| `failed` | array of BlocklistBulkDeleteFailure | The entries Kenso kept, with the reason for each. |

### Request

```bash
curl -X POST "https://api.ken.so/v1/blocklist-entries/bulk-delete" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "ids": [
    812
  ]
}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "succeeded": [
      1
    ],
    "failed": [
      {
        "id": 812,
        "error": {
          "code": "string",
          "message": "string"
        }
      }
    ]
  }
}
```

## Types

Each named type the tables above use, nested ones included.

### BlocklistBulkDeleteFailure

An entry a bulk delete kept.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer (int64) | no | The entry's id. |
| `error` | BlocklistBulkError | no | Why Kenso kept the entry. |

### BlocklistBulkError

Why a bulk delete kept an entry.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | string | no | Always `invalid_state`: the entry is an `own_domain` entry, or a `rule` entry while blocklist rules are on. |
| `message` | string | no | A readable explanation, with what to change instead. |
