# Quink

> Quink (https://quink.jp) はファイルをアップロードして URL で共有するサービスです。
> API キーを使えば curl・スクリプト・AI エージェント・自動化ツールから直接利用できます。
> API キーはマイページ (https://quink.jp/login) → プロフィールセクションで取得してください。

---

## Authentication

すべての認証付きリクエストに次のヘッダーを付けます。

```
X-API-Key: quink_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

ゲスト（API キーなし）でもアップロード可能ですが制限があります：
- 最大 100 MB / 1 ファイル
- 1 分に 1 ファイル
- 3 日間保存

---

## Upload

### POST /upload — multipart/form-data

```
POST https://quink.jp/upload
X-API-Key: quink_xxxxx          # 省略可（ゲスト扱い）

Form fields:
  file               (required)  アップロードするファイル
  comment            (optional)  受取人に表示するコメント（任意）
  download_password  (optional)  ダウンロードパスワード（任意）
```

**Response 200**
```json
{
  "url": "https://quink.jp/f/abc123def",
  "expires_at": "2026-06-21T12:34:56+00:00"
}
```

**curl 例**
```bash
# 基本
curl -X POST https://quink.jp/upload \
  -H "X-API-Key: quink_xxxxx" \
  -F "file=@report.pdf"

# コメント・パスワード付き
curl -X POST https://quink.jp/upload \
  -H "X-API-Key: quink_xxxxx" \
  -F "file=@report.pdf" \
  -F "comment=月次レポート" \
  -F "download_password=secret123"
```

**PowerShell 例**
```powershell
$headers = @{ "X-API-Key" = "quink_xxxxx" }
$form    = @{ file = Get-Item "report.pdf" }
$r = Invoke-RestMethod -Uri "https://quink.jp/upload" -Method Post -Headers $headers -Form $form
Write-Host $r.url
```

**Python 例**
```python
import requests
r = requests.post(
    "https://quink.jp/upload",
    headers={"X-API-Key": "quink_xxxxx"},
    files={"file": open("report.pdf", "rb")},
    data={"comment": "月次レポート"}
)
print(r.json()["url"])
```

### POST /upload/raw — ストリーミング（大容量ファイル向け）

10 GB 超など大容量ファイルを送る場合はこちら。
メタデータはすべてリクエストヘッダーで渡します（フォームデータは使いません）。

```
POST https://quink.jp/upload/raw
X-API-Key: quink_xxxxx
X-Filename: report.pdf              # ファイル名（percent-encode 推奨）
Content-Type: application/octet-stream
Content-Length: <bytes>
X-Comment: コメント                  (optional)
X-Download-Password: pass            (optional)

Body: raw file bytes
```

---

## File Management

### GET /myfiles — ファイル一覧取得

```
GET https://quink.jp/myfiles
X-API-Key: quink_xxxxx
```

**Response 200** — 配列
```json
[
  {
    "id": "abc123def",
    "filename": "report.pdf",
    "size": 1048576,
    "uploaded_at": "2026-05-22T10:00:00+00:00",
    "expires_at":  "2026-06-22T10:00:00+00:00",
    "remaining_days": 31,
    "expired": false,
    "download_count": 3,
    "comment": "月次レポート",
    "has_password": false,
    "ip_allowlist": []
  }
]
```

### PATCH /f/{id}/meta — コメント・パスワード・IP制限を更新

```
PATCH https://quink.jp/f/{id}/meta
X-API-Key: quink_xxxxx
Content-Type: application/json

{
  "comment": "新しいコメント",
  "download_password": "newpass",
  "ip_allowlist": ["192.168.1.0/24"]
}
```

すべてのフィールドは省略可能です。指定したフィールドのみ更新されます。

**Response 200**
```json
{ "updated": "abc123def" }
```

### DELETE /f/{id} — ファイル削除

```
DELETE https://quink.jp/f/{id}
X-API-Key: quink_xxxxx
```

**Response 200**
```json
{ "deleted": "abc123def" }
```

---

## Quota / Usage

### GET /quota — 使用量・上限確認

```
GET https://quink.jp/quota
X-API-Key: quink_xxxxx
```

**Response 200**
```json
{
  "username": "user@example.com",
  "used_bytes": 52428800,
  "max_mb": 5120,
  "file_max_mb": 2048
}
```

- `used_bytes`  : 現在の使用量（バイト）
- `max_mb`      : ストレージ合計上限（MB）
- `file_max_mb` : 1 ファイルあたりの上限（MB）

### GET /upload_limit — 1 ファイルあたりの上限確認（認証不要）

```
GET https://quink.jp/upload_limit
X-API-Key: quink_xxxxx    # 省略するとゲスト上限を返す
```

**Response 200**
```json
{ "file_max_mb": 2048 }
```

---

## Download

アップロードで返った URL をそのまま共有すればブラウザでダウンロードページが開きます。

```
# ダウンロードページ（ブラウザ向け）
https://quink.jp/f/{id}

# 直接ダウンロード（リダイレクト）
https://quink.jp/f/{id}/direct
```

---

## Error Responses

すべてのエラーは次の形式で返ります。

```json
{ "detail": "エラーの説明（日本語または英語）" }
```

| HTTP ステータス | 意味 |
|---|---|
| 400 | リクエスト不正（ファイル未添付など） |
| 401 | API キーが無効または未指定 |
| 403 | 権限なし（他のユーザーのファイルを操作しようとした等） |
| 404 | ファイルが見つからない（削除済み・期限切れを含む） |
| 413 | ファイルサイズ超過またはストレージ上限超過 |
| 429 | レートリミット超過（`Retry-After` ヘッダーで待機秒数を確認） |

---

## Notes

- ファイル ID (`{id}`) は英数字 9〜12 文字程度のランダム文字列です。
- 保存期間・容量上限はプランによって異なります。
- API キーはマイページのプロフィールセクションで確認・再発行できます。
- このファイルは https://quink.jp/llms.txt で最新版を取得できます。