# Delete objects and folders

Delete selected objects, or a folder with everything under it, from the console, the CLI or the API.

Replace _example-uploads_ with your bucket's name. In a versioned bucket a delete adds a delete
marker that hides the object, and its versions stay (see
[Restore an earlier version](restore-an-object-version.md)); without versioning the objects are
gone for good.

## Prerequisites

- Permission for `s3:DeleteObject` on the objects. Without it the console's **Delete** is
  unavailable and says "Deleting needs s3:DeleteObject, which your policies do not grant."
- For a folder, the console's count of what it holds also needs `s3:ListBucketVersions`.
- In the console, also `s3:GetBucket` on the bucket to open it (without it the bucket's page says
  "Access denied").
- The bucket is not one the platform writes.

## Delete objects

**Console**
1. Open **Object Storage**, open the bucket, then choose **Objects**.
2. Select the objects and folders to delete, then choose **Delete**. The dialog (for example
   "Delete 2 objects and 1 folder with 41 objects in it?") lists the names; for a folder it counts
   what it holds ("The folder holds 41 objects (12 MB), all deleted with it.") and says what
   versioning does with them.
3. Choose **Delete**.

To delete one object or folder, choose **Delete** or **Delete folder** in its row's menu.

**CLI**
```sh
dcloud s3 bucket-objects delete example-uploads --keys photos/cat.jpg --keys photos/dog.jpg
```

**API**
```http
POST /s3/api/buckets/example-uploads/objects/delete
{ "keys": ["photos/cat.jpg", "photos/dog.jpg"] }
```

Up to 1000 keys per call. A key that does not exist counts as deleted, as in S3. If your IAM
policies refuse `s3:DeleteObject` on any one of the keys, the whole call is refused with `403`
and nothing is deleted. Otherwise the answer lists `deleted` and, under `errors`, the keys that
stayed: those the bucket policy keeps, and any key storage still lists after the delete ("The
storage reported this deleted, but still lists it: …").

## Delete a folder over the API

`POST /s3/api/buckets/example-uploads/objects/delete-prefix` with `{ "prefix": "photos/",
"allVersions": false }` deletes the current objects under the folder, as the console's folder
delete does. Each call works for about 20 seconds; while it answers `done: false`, call again with
the `cursor` it returned. `GET /s3/api/buckets/example-uploads/objects/count?prefix=photos/` says
what the folder holds first (`s3:ListBucketVersions`; it reads at most 10,000 entries, and
`complete: false` means the numbers are a floor). To remove every version too, see
[Empty a bucket](empty-a-bucket.md#delete-one-folder).

## With an S3 client

`aws s3 rm s3://example-uploads/photos/ --recursive` removes the current objects under a prefix.
`DeleteObjects` takes up to 1000 keys; an entry with a `VersionId` deletes that version for good
and needs `s3:DeleteObjectVersion`.

## Related

- [Empty a bucket](empty-a-bucket.md)
- `s3.bucket-objects.delete` · `dcloud s3 bucket-objects delete`
