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

Delete list

DELETE /v1/lists/:iblockId

Deletes the entire list along with all its sections and elements. A deleted list cannot be restored through the API — create a new one if needed.

Parameters

Parameter Type Required Description
iblockId (path) string yes List ID or symbolic code. Use the ID or CODE field from List of lists
iblockTypeId (query) string no Infoblock type. Values:
lists — regular lists, default
lists_socnet — workgroup lists
bitrix_processes — internal workflows
structure — company structure type (contains the built-in absence infoblock for the absence calendar)
socnetGroupId (query) number no ID of the workgroup that contains the list. A positive integer. For a workgroup list, pass iblockTypeId=lists_socnet and the group ID from the id field returned by List workgroups. Omit it for a regular list

Examples

curl — personal key

Terminal 
curl -X DELETE "https://vibecode.bitrix24.com/v1/lists/23" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl -X DELETE "https://vibecode.bitrix24.com/v1/lists/23" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/lists/23', {
  method: 'DELETE',
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

if (res.status === 204) {
  console.log('List deleted')
}

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/lists/23', {
  method: 'DELETE',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

if (res.status === 204) {
  console.log('List deleted')
}

Response

On successful deletion, HTTP status 204 No Content is returned with an empty body. Success is indicated by the response code, not the content.

Response example

HTTP/1.1 204 No Content

Error response example

One possible response for a missing or already deleted list is 404 LIST_NOT_FOUND:

JSON 
{
  "success": false,
  "error": {
    "code": "LIST_NOT_FOUND",
    "message": "List not found"
  }
}

Errors

HTTP Code Description
404 LIST_NOT_FOUND The list does not exist or has already been deleted. Bitrix24 may return 403 BITRIX_ACCESS_DENIED instead
403 BITRIX_ACCESS_DENIED The list does not exist, has already been deleted, or is not accessible for deletion. Bitrix24 does not always distinguish a missing list from insufficient permissions
422 BITRIX_ERROR The list type does not match the request parameters, for example when socnetGroupId is passed for a regular list. The response contains b24Code: "0"
400 INVALID_IBLOCK_TYPE iblockTypeId is not one of lists, lists_socnet, bitrix_processes, structure
409 LISTS_MODULE_NOT_ENABLED The Lists module is not enabled on the Bitrix24 portal
403 WRITE_BLOCKED_READONLY_KEY The key operates in read-only mode
403 SCOPE_DENIED The key lacks the lists scope
401 TOKEN_MISSING The key has no access tokens configured

Full list of common API errors — Errors.

Known specifics

Requests after deletion. Get list returns different responses: 403 BITRIX_ACCESS_DENIED for a deleted numeric ID and 404 LIST_NOT_FOUND for a symbolic code. These responses do not mean that deletion failed. A subsequent delete request may also return either 403 BITRIX_ACCESS_DENIED or 404 LIST_NOT_FOUND: the exact code depends on the Bitrix24 response and does not confirm whether the list existed before.

See also