# PutPut API

## Base URL
https://putput.pages.dev/api

## Authentication
All endpoints except `POST /api/auth/guest` require: `Authorization: Bearer <token>`

## Endpoints

### POST /api/auth/guest
Get a token. No signup required.
```bash
curl -X POST https://putput.pages.dev/api/auth/guest
```
Returns:
```json
{
  "token": "pp_...",
  "claim_url": "https://putput.pages.dev/login?claim=...",
  "limits": { "storage_bytes": -1, "max_file_size_bytes": -1, "max_files": -1, "expires_at": null }
}
```
Save the `token` and `claim_url`. The claim_url lets the user upgrade to a free account later.

### POST /api/upload/presign
Get a presigned URL to upload a file directly to storage.
```bash
curl -X POST https://putput.pages.dev/api/upload/presign \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"filename": "photo.jpg", "content_type": "image/jpeg", "size_bytes": 102400}'
```
Returns: `{ "upload_id": string, "presigned_url": string, "public_name": string, "expires_at": string }`

### PUT <presigned_url>
Upload the file directly to the presigned URL.
```bash
curl -X PUT "<presigned_url>" -H "Content-Type: image/jpeg" --data-binary @photo.jpg
```

### POST /api/upload/confirm
Confirm the upload. Returns the public URL.
```bash
curl -X POST https://putput.pages.dev/api/upload/confirm \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"upload_id": "..."}'
```
Returns: `{ "file": { "id": string, "original_name": string, "public_url": string, "content_type": string, "size_bytes": number, "created_at": string } }`

### GET /api/files
List uploaded files. Supports cursor pagination: `?cursor=<id>&limit=<number>`
```bash
curl https://putput.pages.dev/api/files -H "Authorization: Bearer <token>"
```
Returns: `{ "files": [...], "cursor": string | null, "has_more": boolean }`

### DELETE /api/files/:id
Delete a file.
```bash
curl -X DELETE https://putput.pages.dev/api/files/<file_id> -H "Authorization: Bearer <token>"
```
Returns: `{ "success": true }`

## Upgrading
The `claim_url` from token creation lets the user upgrade from guest to free. Show them the URL, they enter their email, done. The token string stays the same.

## Errors
```json
{ "error": { "code": "ERROR_CODE", "message": "..." } }
```
| Code | HTTP | Meaning |
|------|------|---------|
| UNAUTHORIZED | 401 | Missing or invalid token |
| UPLOAD_NOT_FOUND | 404 | Invalid or expired upload_id |
| FILE_NOT_FOUND | 404 | File doesn't exist or already deleted |
| FILE_NOT_UPLOADED | 400 | File wasn't uploaded to storage yet |