API

從腳本和應用程式建立與管理短連結。這個 API 是免費的。在你的控制台的 API 金鑰裡建立一把金鑰，然後以 bearer token 的形式送出。

驗證

Authorization: Bearer gz_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

金鑰只會顯示一次。請把它當成密碼：任何拿到你金鑰的人，都能在你的帳號裡建立和編輯連結。金鑰外洩時，請到控制台撤銷它。

限制

• 每把金鑰每分鐘 60 次請求。
• 每個帳號每天 500 條新連結。
• 目標網址會比對 Google Safe Browsing 和我們的封鎖清單。其他短網址服務不能當作目標網址。

建立連結

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 天和全期間的真人點擊數、每日點擊數，以及排名前幾的國家、來源、裝置、瀏覽器和作業系統。機器人和連結預覽（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 已達頻率上限或每日上限

每個端點的機器可讀說明放在 /openapi.json。