> ## 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.

# Upload and download with ClearLake

> Use short-lived URLs for direct object transfers

ClearLake keeps file bytes out of ordinary API responses. The API gives you a short-lived URL, and your client transfers the file directly through that URL.

## Upload an object

`POST /clearlake/buckets/:name/objects/upload-url` requires `clearlake:write`:

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

Response:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "uploadUrl": "https://files.cloudservices.ecowestern.net/upload/TICKET",
  "fileName": "ACCOUNT_ID/user-uploads/avatars/user-123.png"
}
```

The URL is valid for 300 seconds. Upload directly to `uploadUrl` and include the intended `Content-Type`.

Treat the URL as a temporary bearer credential. Do not log it, store it as a permanent credential, or reuse it after expiry.

## Download an object

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

Response:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "downloadUrl": "https://files.cloudservices.ecowestern.net/download/TICKET"
}
```

Download URLs are valid for 300 seconds. Generate a new URL when the previous one expires.

## Upload example

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
UPLOAD_URL=$(curl -s -X POST \
  https://api.cloudservices.ecowestern.net/v1/clearlake/buckets/user-uploads/objects/upload-url \
  -H "Authorization: Bearer $ECS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key":"avatars/user-123.png"}' | jq -r '.uploadUrl')

  curl -X POST "$UPLOAD_URL" \
  -H "Content-Type: image/png" \
  --data-binary @avatar.png
```

## Private and public transfers

Private objects require a valid short-lived download URL. Public objects can also be served through a Waymark custom domain. Private ClearLake buckets are not supported through Waymark custom domains.