## Delete by tag

`DELETE /v1/notifications/by-tag/:tag`

Deletes all of the application's notifications with the given `tag` at once. The tag is set when sending in the `tag` field. Deletion affects only notifications sent by this same application.

The operation is available **only for an OAuth-application key** — the tag is bound to the application, so the request must carry both headers: `X-Api-Key` with the application key and `Authorization: Bearer` with the user's session token. With a personal key the request returns `403 BITRIX_ACCESS_DENIED`.

## Parameters

| Parameter | Type | Required | Description |
|----------|-----|:-----:|---------|
| `tag` (path) | string | yes | The `tag` the notifications were sent with via [`POST /v1/notifications`](./send.md) |

## Examples

### curl — OAuth application

```bash
curl -X DELETE "https://vibecode.bitrix24.com/v1/notifications/by-tag/deal-1024" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/notifications/by-tag/deal-1024', {
  method: 'DELETE',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

if (res.status === 204) {
  console.log('Notifications with the tag deleted')
}
```

## Response

On successful deletion an HTTP status `204 No Content` with an empty body is returned — success is checked by the status.

## Response example

```http
HTTP/1.1 204 No Content
```

## Error response example

403 — called with a personal key, the application tag is unavailable:

```json
{
  "success": false,
  "error": {
    "code": "BITRIX_ACCESS_DENIED",
    "message": "Access denied! Client ID not specified"
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|----------|
| 403 | `BITRIX_ACCESS_DENIED` | Called with a personal key — deletion by tag is available only for an OAuth-application key |
| 403 | `SCOPE_DENIED` | The key lacks the `im` scope |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is in read-only mode |
| 401 | `TOKEN_MISSING` | The key has no configured tokens |

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

## Known specifics

- A request for a tag with no notifications also returns `204` — the response code does not reveal how many notifications were deleted.
- Only notifications sent by the same application are deleted. One application's tag does not affect another's notifications.

## See also

- [Send a notification](./send.md)
- [Delete by id](./delete.md)
- [Errors](/docs/errors)