Delete object

DELETE /v1/storage/objects/:key

Marks the object as deleted (soft delete). The object's deletedAt field is set to the deletion date. The physical bytes remain in storage for up to 30 days and are then removed automatically.

DELETE itself does not restore or release the object: GET, HEAD, the old anonymous URL of a PUBLIC object, and a repeated DELETE return 410 STORAGE_OBJECT_DELETED throughout the retention period. The old bytes cannot be restored through the API. A later direct upload (Path A) may write new bytes into the same row when the object has COMPLETED status and has no multipart session. Multipart upload (Path C) can also reuse an eligible personal-key COMPLETED object after this explicit DELETE. Both paths preserve its id, createdAt, key, physical address, owner tuple, and visibility, and clear deletedAt after a successful upload. Path B remains disabled with 503; ineligible deleted states return 409.

Parameters

Examples

curl — personal key

curl -s -X DELETE "https://vibecode.bitrix24.com/v1/storage/objects/docs-test%2Fverify.txt" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth app

curl -s -X DELETE "https://vibecode.bitrix24.com/v1/storage/objects/docs-test%2Fverify.txt" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

const key = encodeURIComponent('docs-test/verify.txt')
const res = await fetch(`https://vibecode.bitrix24.com/v1/storage/objects/${key}`, {
  method: 'DELETE',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})
const body = await res.json()
if (body.object?.deletedAt) {
  console.log('Object deleted:', body.object.deletedAt)
}

JavaScript — OAuth app

const key = encodeURIComponent('docs-test/verify.txt')
const res = await fetch(`https://vibecode.bitrix24.com/v1/storage/objects/${key}`, {
  method: 'DELETE',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const body = await res.json()
if (body.object?.deletedAt) {
  console.log('Object deleted:', body.object.deletedAt)
}

Response fields

Response example

{
  "object": {
    "id": "cmpfkc57v0akio510qclwfn7t",
    "key": "docs-test/verify.txt",
    "contentType": "text/plain",
    "sizeBytes": "40",
    "sha256": null,
    "visibility": "PRIVATE",
    "uploadStatus": "COMPLETED",
    "createdAt": "2026-05-21T14:05:20.092Z",
    "deletedAt": "2026-05-21T14:05:36.880Z"
  }
}

Error response example

410 — object already deleted (repeated call):

{
  "success": false,
  "error": {
    "code": "STORAGE_OBJECT_DELETED",
    "message": "Object docs-test/verify.txt was deleted"
  }
}

Errors

The full list of general API errors — Errors.

Known specifics

• Keys with / in the path. A slash in the key is not a route separator — pass it URL-encoded. In JavaScript use encodeURIComponent(key).

• A deleted object is immediately unavailable. Until an eligible Path A upload or, for a personal key after explicit DELETE, a Path C upload writes new bytes, GET and HEAD by key return 410 STORAGE_OBJECT_DELETED for the full 30-day period before physical purge. The object-list request does not include deleted objects. Reusing the row replaces the content with new bytes; it does not restore the old content.

• Do not delete source-code snapshots with this method. Objects under the source/ prefix belong to servers and applications, and their logical key is the same across owners — every one of them has source/current.tar.gz. The request matches one of the available rows by key, so an arbitrary one would be deleted. Versions are removed through source-code operations — Source code storage.

• An app key with no employee session sees only the app-shared file. Employees of an app claim logical names independently of each other, so several objects may hold one name. A request made with an app key and NO Authorization header addresses the app-shared file; if the name is held solely by per-employee files, the response is 404 STORAGE_OBJECT_NOT_FOUND. To reach an employee's file, pass that employee's session in Authorization: Bearer, or address the object by its identifier.

See also

• Download object
• List objects
• Abort multipart upload
• Public access GET