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 in the tag field when the notification is sent. Deletion affects only notifications sent by this same application.

The operation is available only with 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

Examples

curl — OAuth application

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

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 success, the API returns HTTP status 204 No Content with an empty body — check the status code to confirm success.

Response example

HTTP/1.1 204 No Content

Error response example

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

{
  "success": false,
  "error": {
    "code": "BITRIX_ACCESS_DENIED",
    "message": "Access denied! Client ID not specified",
    "hint": "Bitrix24 refused this call; the cause is not determined.",
    "cause": "unknown",
    "fix": {
      "action": "none"
    }
  }
}

Errors

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

• Send a notification
• Delete by id
• Errors