API

スクリプトやアプリから短縮リンクを作成・管理できます。API は無料です。ダッシュボードの API キーでキーを作り、ベアラートークンとして送ってください。

認証

Authorization: Bearer gz_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

キーは一度しか表示されません。パスワードと同じように扱ってください。キーを持つ人は誰でも、あなたのアカウントでリンクを作成・編集できます。漏れたキーはダッシュボードから失効させてください。

制限

• キーごとに 1 分あたり 60 リクエスト。
• アカウントごとに 1 日 500 本の新規リンク。
• 転送先は Google Safe Browsing と当サービスのブロックリストで照合します。他の URL 短縮サービスは転送先に指定できません。

リンクを作成する

curl -X POST https://gozi.to/api/my/links \
  -H "Authorization: Bearer $GOZI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/launch", "code": "launch"}'

code は省略できます（4〜32 文字の英字、数字、-、_）。省略するとランダムな 7 文字のコードになります。レスポンス 201:

{
  "link": {
    "code": "launch",
    "shortUrl": "https://gozi.to/launch",
    "url": "https://example.com/launch",
    "status": "active",
    "statusReason": null,
    "custom": true,
    "createdAt": 1790000000000,
    "expiresAt": null
  }
}

リンクの一覧

GET /api/my/links?limit=25&cursor=<nextCursor>&q=<search>&clicks=1

新しい順です。前のページの nextCursor を渡すと次のページを取得できます。clicks=1 を付けると、人によるクリック数の累計が加わります。

取得、編集、削除

GET    /api/my/links/{code}
PATCH  /api/my/links/{code}   {"url": "https://new.example"}  or  {"status": "disabled" | "active"}
DELETE /api/my/links/{code}

アナリティクス

GET /api/my/links/{code}/stats

直近 90 日と累計の人によるクリック数、日ごとのクリック数、上位の国・参照元・デバイス・ブラウザ・OS を返します。ボットとリンクプレビュー（Slack、WhatsApp など）は botClicks に分けて数えます。結果は約 5 分間キャッシュされます。

エラー

エラーは HTTP ステータスコードと JSON のボディで返します:

{ "error": { "code": "slug_taken", "message": "That custom link is already taken." } }

• 400 入力が不正（invalid_url、invalid_slug など）
• 401 キーがない、無効、または失効している
• 409 そのカスタムリンクは使用済み
• 422 転送先が許可されていない（destination_blocked）
• 429 レート制限または 1 日の上限に到達

すべてのエンドポイントの機械可読な定義は /openapi.json にあります。