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

# Presigned URLs

> Generate temporary tokens for secure direct uploads.

Presigned URLs allow you to offload file handling to clients while maintaining security and path locking.

## 1. Generate Presigned Token

Create a short-lived token that locks an upload to a specific path or folder.

**Method**: `GET`\
**Path**: `/api/presigned-url`

### Authentication

Requires an API Key via `Authorization`, `X-API-Key`, or `apiKey` query parameter.

### Query Parameters

<ParamField query="path" type="string">
  If ends with `/`, locks to a folder. Otherwise, locks to a specific filename.
</ParamField>

<ParamField query="expiresAt" type="number">
  TTL for the token in seconds (default 3600).
</ParamField>

<ParamField query="randomizeName" type="boolean">
  Force UUID filenames for the upload.
</ParamField>

### Response

```json theme={null}
{
    "success": true,
    "url": "https://cdn.sacul.cloud/api/presigned-url/TOKEN",
    "expiresIn": 3600
}
```

***

## 2. Upload via Token

Upload the file content using the generated token.

**Method**: `POST`\
**Path**: `/api/presigned-url/:token`

### Headers

<ParamField header="Content-Type" type="string" default="multipart/form-data" required>
  `multipart/form-data`
</ParamField>

### Note

The token is consumed immediately after one successful upload.

## Example Flow

```bash theme={null}
# 1. Get the URL
curl "https://cdn.sacul.cloud/api/presigned-url?path=avatars/&randomizeName=true" \
    -H "Authorization: Bearer <your-api-key>"

# 2. Upload using the resulting URL
curl -X POST https://cdn.sacul.cloud/api/presigned-url/YOUR_TOKEN \
    -F "files=@avatar.png"
```