For AI agents: markdown of this page — /docs-content-en/notifications/delete-by-tag.md documentation index — /llms.txt

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

Examples

curl — OAuth application

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

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