## Remove a card by index

`DELETE /v1/pages/:pageId/blocks/:blockId/cards/:index`

Removes one card from a block's card set by its current position. The removal is irreversible.

## Parameters

| Parameter | Type | Required | Description |
|----------|-----|:-----:|----------|
| `pageId` (path) | number | yes | Page ID. List: [`GET /v1/pages`](/docs/entities/pages/list) |
| `blockId` (path) | number | yes | ID of a block on this page. List: [`GET /v1/pages/:pageId/blocks`](/docs/entities/pages/blocks/list). A block of another page returns `404` |
| `index` (path) | number | yes | Current zero-based position of the card in the set. Take it from `data.cards` in the latest response from a card method. Before the first write, the position is the ordinal number of the element with the set class in the `html` of the [`GET /v1/pages/:pageId/blocks/:blockId/content`](/docs/entities/pages/block-content) response |
| `selector` (query) | string | yes | Card set selector without `@N`, for example `.landing-block-card`. Set selectors are the keys of the `cards` object in the [`GET /v1/pages/:pageId/blocks/:blockId/content`](/docs/entities/pages/block-content) response |
| `scope` (query) | string | no | Internal landing area: `KNOWLEDGE` — knowledge base, `GROUP` — workgroup knowledge base, `MAINPAGE` — main page. Omit for a regular site |

The request has no body.

## Examples

### curl — personal key

```bash
curl -X DELETE "https://vibecode.bitrix24.com/v1/pages/42/blocks/50/cards/1?selector=.landing-block-card" \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth application

```bash
curl -X DELETE "https://vibecode.bitrix24.com/v1/pages/42/blocks/50/cards/1?selector=.landing-block-card" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

### JavaScript — personal key

```javascript
const response = await fetch("https://vibecode.bitrix24.com/v1/pages/42/blocks/50/cards/1?selector=.landing-block-card", {
  method: "DELETE",
  headers: {"X-Api-Key": "YOUR_API_KEY"},
})
const result = await response.json()
if (!response.ok) throw new Error(result.error.message)
console.log(result.data)
```

### JavaScript — OAuth application

```javascript
const response = await fetch("https://vibecode.bitrix24.com/v1/pages/42/blocks/50/cards/1?selector=.landing-block-card", {
  method: "DELETE",
  headers: {"X-Api-Key": "YOUR_APP_KEY", "Authorization": "Bearer USER_SESSION_TOKEN"},
})
const result = await response.json()
if (!response.ok) throw new Error(result.error.message)
console.log(result.data)
```

## Response fields

| Field | Type | Description |
|------|-----|----------|
| `success` | boolean | Always `true` on success |
| `data.cards` | object | Block cards after the removal. The key is the set selector, the value is the array of the set's cards in order. After the last card is removed, the array is empty |
| `data.cards.<selector>[].index` | number | Current zero-based position of the card in the set |
| `data.cards.<selector>[].content` | string | Card HTML |

## Response example

The block had the cards `First` and `Second`. The card with index `1` is removed:

```json
{
  "success": true,
  "data": {
    "cards": {
      ".landing-block-card": [
        {
          "index": 0,
          "content": "<div class=\"landing-block-card\"><h3 class=\"landing-block-node-title\">First</h3></div>"
        }
      ]
    }
  }
}
```

## Error response example

404 — the set has no card with this index, the block has no such set, or the block belongs to another page:

```json
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Page, block or card not found."
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|----------|
| 404 | `ENTITY_NOT_FOUND` | `Page, block or card not found.` — the block does not belong to page `pageId`, the block has no set with this selector, or the set has no card with index `index`. Same response if the block does not exist |
| 400 | `MISSING_REQUIRED_FIELDS` | `selector is required.` — `selector` is missing from the query, empty or whitespace-only |
| 400 | `INVALID_PARAMS` | `selector must omit the card index; DELETE uses the index path parameter.` — `selector` contains `@N`. The index goes in the path only |
| 400 | `INVALID_PARAMS` | `index must be a non-negative safe integer.` — `index` is not a non-negative integer |
| 400 | `INVALID_PARAMS` | `pageId and blockId must be positive safe integers.` — `pageId` or `blockId` is not a positive integer |
| 400 | `INVALID_PARAMS` | `Body must be a JSON object.` — a body was sent that is not a JSON object |
| 400 | `INVALID_PARAMS` | `Body contains an unsupported field.` — a body with fields was sent |
| 400 | `INVALID_SCOPE` | `scope` is not `KNOWLEDGE`, `GROUP` or `MAINPAGE` |
| 422 | `BITRIX_NO_EFFECT` | `Bitrix24 did not confirm the card action.` — Bitrix24 did not confirm the write |
| 422 | `BITRIX_NO_EFFECT` | `Bitrix24 did not return cards after the action.` — after the write, Bitrix24 did not return the block content |
| 422 | `BITRIX_NO_EFFECT` | `Bitrix24 did not persist the requested card count.` — the card count did not drop by one after the write |
| 422 | `BITRIX_ERROR` | Bitrix24 rejected the action. The error text comes from Bitrix24 |
| 502 | `BITRIX_ERROR` | `Bitrix24 returned invalid or oversized card content.` — the block markup cannot be parsed or the cards exceed 8 MiB |
| 403 | `SCOPE_DENIED` | The API key does not have the `landing` scope |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is read-only. The request is rejected before Bitrix24 is called |
| 403 | `BITRIX_ACCESS_DENIED` | The Bitrix24 user the key is issued for has no permission to edit the page |
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |
| 401 | `INVALID_API_KEY` | The key in `X-Api-Key` is not found or has been revoked |
| 401 | `TOKEN_MISSING` | The API key has no configured tokens |
| 409 | `LANDING_MODULE_NOT_ENABLED` | The Sites module is not available on the Bitrix24 account |
| 409 | `PORTAL_ADDRESS_CHANGED` | A self-hosted Bitrix24 moved to a new address, but the key's webhook was issued for the old one. Reissue the key's webhook |
| 429 | `RATE_LIMITED` | The Bitrix24 request limit is exceeded. Retry the request in 1-2 seconds |
| 502 | `BITRIX_UNAVAILABLE` | Bitrix24 did not respond or returned a server error |
| 503 | `BITRIX_TIMEOUT` | Bitrix24 did not respond in time |

Full list of common API errors — [Errors](/docs/errors).

## Known specifics

- **A stale index removes a neighboring card.** Positions shift after every write, and a card has no permanent ID. An index from an old response already points at a different card, and the method returns no error.
- **The last card can be removed.** The set becomes empty, and the block stays on the page. The card methods cannot bring a card back into an empty set: cloning and adding need a reference card and return `404`, rebuilding returns `400`.
- **A failure after the write does not undo the removal.** The `422`, `502` and `503` responses do not mean the card is still there. Before retrying, re-read the block via [`GET /v1/pages/:pageId/blocks/:blockId/content`](/docs/entities/pages/block-content): a retry with the same index removes the next card.

## See also

- [Block cards](/docs/entities/pages/cards)
- [Clone a block card](/docs/entities/pages/cards/clone)
- [Add a card with HTML](/docs/entities/pages/cards/add)
- [Rebuild a card set](/docs/entities/pages/cards/update)
- [Block content](/docs/entities/pages/block-content)