> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudservices.ecowestern.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Work with ClearLake objects

> List, inspect, and delete files by object key

## Object keys

Object keys are strings relative to a bucket. Forward slashes create folder-like organization:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
avatars/user-123.png
```

Keys are case-sensitive. Keep keys stable and predictable because the exact key is required for metadata, download, and delete requests.

## List objects

`GET /clearlake/buckets/:name/objects` requires `clearlake:read` and returns:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "objects": [
    {
      "key": "avatars/user-123.png",
      "file_name": "ACCOUNT_ID/user-uploads/avatars/user-123.png",
      "file_id": "file-id",
      "size": 245678,
      "content_type": "image/png"
    }
  ]
}
```

## Get object metadata

`GET /clearlake/buckets/:name/objects/*` requires `clearlake:read`.

Replace the wildcard with the complete object key. The response contains `key`, `file_name`, `file_id`, `size`, and `content_type`.

## Delete an object

`DELETE /clearlake/buckets/:name/objects/*` requires `clearlake:delete` and returns `204 No Content`.

Deleting an object is permanent.

## Troubleshooting

| Symptom                 | What to check                                           |
| ----------------------- | ------------------------------------------------------- |
| Object is not found     | Use the exact case-sensitive object key.                |
| Metadata does not match | List the bucket and compare the returned `key` exactly. |
| Delete is denied        | Confirm the key has `clearlake:delete`.                 |