Short URL
Service.

概要

本 API は、任意の URL を 7 桁の英数字識別子に変換し、https://s.pfos.school/{code} 形式でリダイレクト配信します。基盤は Cloudflare のエッジネットワーク上で稼働し、世界中から低レイテンシでアクセス可能です。

認証モデル

本サービスは 2 系統のエンドポイントを提供しています。

短縮コードの構造

認証

Authenticated API（/api/links 系）のすべてのリクエストには Authorization ヘッダで Bearer トークンを指定する必要があります。トークンの発行については管理者へお問い合わせください。

Authorization: Bearer YOUR_API_KEY

未認証あるいは無効なトークンが送信された場合、401 Unauthorized が返却されます。トークンは定数時間比較で検証されるため、タイミング攻撃の対象とはなりません。

Public Endpoint（/api/public/links）は認証不要です。IP 単位のレート制限のみが適用されます。詳細は 公開作成エンドポイント をご参照ください。

新しい短縮リンクを作成します。slug を指定しない場合は自動生成され、ttl を指定しない場合は無期限となります。認証必須。

リクエストボディ

curl -X POST https://s.pfos.school/api/links \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/very/long/path","qr":true}'

{
  "code": "Ab3xZ9q",
  "shortUrl": "https://s.pfos.school/Ab3xZ9q",
  "target": "https://example.com/very/long/path",
  "createdAt": 1747000000000,
  "custom": false,
  "qr": {
    "svg": "https://s.pfos.school/Ab3xZ9q.svg",
    "png": "https://s.pfos.school/Ab3xZ9q.png"
  }
}

createdAt は UNIX エポックミリ秒。custom はカスタムスラグ指定の有無。qr フィールドはリクエストで "qr": true を指定した場合のみ存在します。詳細は QR コード生成 を参照。

登録済みの短縮リンクを一覧取得します。カーソル型ページネーション対応。認証必須。

クエリパラメータ

curl https://s.pfos.school/api/links?limit=20 \
  -H "Authorization: Bearer $API_KEY"

{
  "links": [
    {
      "code": "Ab3xZ9q",
      "target": "https://example.com/...",
      "shortUrl": "https://s.pfos.school/Ab3xZ9q",
      "createdAt": 1747000000000,
      "custom": false,
      "public": true,
      "expiration": null
    }
  ],
  "cursor": "AAAAA..."
}

cursor が null なら全件取得完了。public は true なら Public Endpoint 経由、false なら認証 API 経由で作成されたことを示します。expiration は UNIX エポック秒（無期限の場合 null）。

指定した短縮コードに紐づく情報を取得します。認証必須。

クエリパラメータ

curl https://s.pfos.school/api/links/Ab3xZ9q?qr=true \
  -H "Authorization: Bearer $API_KEY"

{
  "code": "Ab3xZ9q",
  "target": "https://example.com/very/long/path",
  "shortUrl": "https://s.pfos.school/Ab3xZ9q",
  "createdAt": 1747000000000,
  "custom": false,
  "public": false,
  "qr": {
    "svg": "https://s.pfos.school/Ab3xZ9q.svg",
    "png": "https://s.pfos.school/Ab3xZ9q.png"
  }
}

qr フィールドはクエリで ?qr=true を指定した場合のみ存在します。

指定した短縮リンクを削除します。削除は即時反映され、以後そのコードへのアクセスは 404 となります。認証必須。

curl -X DELETE https://s.pfos.school/api/links/Ab3xZ9q \
  -H "Authorization: Bearer $API_KEY"

成功時はボディなしの 204 が返却されます。

認証不要の公開作成エンドポイントです。HTTP クライアント（curl、fetch、requests 等）から直接呼び出せます。濫用対策として IP 単位のレート制限が適用されます。

仕様上の制約

• カスタムスラグ（slug）と有効期限（ttl）は指定できません。
• s.pfos.school / pfos.school 自身を含むループ参照はブロックされます。
• IP 単位のレート制限が適用されます（Cloudflare Rate Limiting Rules）。制限超過時は 429 が返却されます。

リクエストボディ

curl -X POST https://s.pfos.school/api/public/links \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","qr":true}'

{
  "code": "Ab3xZ9q",
  "shortUrl": "https://s.pfos.school/Ab3xZ9q",
  "target": "https://example.com",
  "qr": {
    "svg": "https://s.pfos.school/Ab3xZ9q.svg",
    "png": "https://s.pfos.school/Ab3xZ9q.png"
  }
}

qr フィールドはリクエストで "qr": true を指定した場合のみ存在します。

指定した短縮コードに対応する QR コードを画像として返します。認証不要。QR が符号化するのは短縮 URL 自体（https://s.pfos.school/:code）です。エッジで 24 時間キャッシュされます。

コードが KV に存在しない場合は 404 を返します。任意の文字列に対する QR は発行されません。

クエリパラメータ

レスポンスの形式

# SVG (ベクター)
curl -O https://s.pfos.school/Ab3xZ9q.svg

# PNG (ラスター、既定 8px/モジュール)
curl -O https://s.pfos.school/Ab3xZ9q.png

# PNG 大きめ、誤り訂正レベル H
curl -O "https://s.pfos.school/Ab3xZ9q.png?s=16&ec=H"

HTML への埋め込み例

<!-- ベクターで埋め込み（推奨） -->
<img src="https://s.pfos.school/Ab3xZ9q.svg" alt="QR" width="200" height="200">

<!-- ラスター -->
<img src="https://s.pfos.school/Ab3xZ9q.png" alt="QR">

誤り訂正レベルの選択

エラーレスポンス

エラー時は適切な HTTP ステータスコードと、以下の形式のレスポンスボディを返却します。

{
  "error": "<reason>"
}

制限事項

レート制限

濫用防止のため、公開エンドポイントには IP 単位のレート制限が適用されます。制限に達した場合、429 Too Many Requests が返却されます。認証 API には現状制限を設けていませんが、必要に応じて追加します。

URL の制約

• スキームは http:// または https:// のみ受け付けます。
• s.pfos.school および pfos.school 自身を指す URL は登録できません（無限ループ防止）。

予約スラグ

以下のスラグはシステムにより予約されており、ユーザー指定はできません。

• api
• admin
• docs
• favicon.ico / robots.txt

有効期限

認証 API では ttl（秒）で有効期限を指定できます。期限が経過した短縮コードは自動削除され、以後 404 となります。最小値は 60 秒です。公開エンドポイントで作成されたリンクは無期限となります。

使用例

公開エンドポイントで作成（認証不要）

curl -X POST https://s.pfos.school/api/public/links \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'

Windows cmd での例

curl -X POST https://s.pfos.school/api/public/links ^
  -H "Content-Type: application/json" ^
  -d "{\"url\":\"https://example.com\"}"

自動生成コードで作成（認証 API）

curl -X POST https://s.pfos.school/api/links \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/article/12345"}'

カスタムスラグ・24 時間有効（認証 API）

curl -X POST https://s.pfos.school/api/links \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","slug":"campaign-2026","ttl":86400}'

QR コード付きで作成（公開エンドポイント）

curl -X POST https://s.pfos.school/api/public/links \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","qr":true}'

# レスポンスの qr.svg / qr.png を直接 GET すれば画像が取得できる

既存リンクの QR を取得

# ベクター（推奨）
curl -O https://s.pfos.school/Ab3xZ9q.svg

# 大きめの PNG（16px/モジュール、誤り訂正 H）
curl -O "https://s.pfos.school/Ab3xZ9q.png?s=16&ec=H"

一覧取得

curl https://s.pfos.school/api/links?limit=50 \
  -H "Authorization: Bearer $API_KEY"

JavaScript (fetch)

// 公開エンドポイントから作成（QR コード付き）
const res = await fetch('https://s.pfos.school/api/public/links', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ url: 'https://example.com', qr: true }),
});
const { code, shortUrl, qr } = await res.json();
// qr.svg / qr.png に画像 URL が入る

Python (requests)

import requests

# 公開エンドポイント（QR コード付き）
res = requests.post(
    'https://s.pfos.school/api/public/links',
    json={'url': 'https://example.com', 'qr': True},
)
data = res.json()
short_url = data['shortUrl']
qr_svg_url = data['qr']['svg']

# QR 画像をダウンロード
img = requests.get(qr_svg_url).content
with open('qr.svg', 'wb') as f:
    f.write(img)