# TinyDisk — LLM / Agent API Guide

TinyDisk is a temporary file sharing service. Files expire automatically.
Read this file before interacting with any TinyDisk instance.

## Quick Start

1. GET /api/info — discover limits and endpoints
2. POST /api/upload — upload file(s), receive auto-generated token
3. GET /api/download/<token> — download file(s) before expiry

## Server Discovery

GET /api/info

Returns JSON with capacity, expiry, and endpoint map.

GET /api/capacity

Returns used/total storage and expiry settings.

## Upload

POST /api/upload
Content-Type: multipart/form-data

Fields:
- files: one or more file parts (field name "files" or legacy "file")

Do NOT send a token. The server auto-generates an 8-character download token
to prevent token collision attacks.

Success response (JSON):
{
  "ok": true,
  "token": "a1b2c3d4",
  "count": 1,
  "download_url": "https://host/api/download/a1b2c3d4",
  "download_url_web": "https://host/download/a1b2c3d4",
  "expire_seconds": 3600,
  "expire_at": 1719900000.0
}

Error response:
{"ok": false, "error": "..."}

Notes:
- Single file → downloaded as original filename
- Multiple files → downloaded as ZIP (tinydisk-<token>.zip)
- Files over 10 MB may fail on low-bandwidth servers (client-side warning only)
- Empty files are skipped
- Total storage is a shared pool across all uploads

## Download

GET /api/download/<token>
GET /download/<token>  (same, web-friendly URL)

Returns file stream or ZIP. On failure returns JSON:
{"ok": false, "error": "口令无效或文件已过期"}

## Configuration (Environment Variables)

Base units: seconds for expiry, KB for capacity.
Plain numbers use base units. Suffix units are also supported.

Expiry (priority order):
- TINYDISK_EXPIRE_SECONDS — e.g. "3600", "1h", "7d", "2w", "1mo", "1y"
- TINYDISK_EXPIRE_HOURS — legacy, converted to seconds

Capacity (priority order):
- TINYDISK_MAX_CAPACITY_KB — e.g. "102400", "100MB", "1GB", "2TB"
- TINYDISK_MAX_CAPACITY_MB — legacy, converted to KB

Port:
- TINYDISK_PORT — default 9999

Supported time suffixes: s, m/min, h/hr, d/day, w/week, mo/month, y/year
(and Chinese: 秒, 分/分钟, 时/小时, 天, 周, 月, 年)

Supported size suffixes: B, KB, MB, GB, TB (case-insensitive)

## Example: curl upload

curl -F "files=@report.pdf" https://example.com/api/upload

## Example: curl download

curl -OJ "https://example.com/api/download/a1b2c3d4"

## Example: Python upload

import requests
with open("data.csv", "rb") as f:
    r = requests.post("https://example.com/api/upload", files={"files": f})
    data = r.json()
    token = data["token"]
    url = data["download_url"]

## Security Model

- Access control is token-only (no accounts)
- Tokens are server-generated random 8-char strings [a-z0-9]
- Tokens are stored in plain text (short-lived temporary files)
- Do not use TinyDisk for sensitive long-term storage