rdurl API

用程式碼建立和管理短連結

API 一般資訊

所有請求都需要 API 金鑰。請參閱驗證部分。
基礎端點是: https://rdurl.link/api
僅支援 HTTPS。
所有端點都回傳 JSON 物件。
請求以 JSON 傳送 (Content-Type: application/json)。
所有時間和時間戳相關欄位均為毫秒。
所有字元編碼均為 UTF-8。

驗證

API 透過金鑰識別請求屬於哪個帳戶。金鑰等同於帳戶密碼：任何持有金鑰的人都可以建立和刪除該帳戶的連結。

第 1 步。產生金鑰

登入儀表板，從「API 金鑰」選單產生金鑰。每次產生都會產生新金鑰，且產生後只能檢視一次。

第 2 步。在請求中加入金鑰

從以下兩種方式中任選其一。

1. Authorization: Bearer （推薦）

大多數公開 API 使用的標準驗證方式。

curl https://rdurl.link/api/link/create   -H "Authorization: Bearer rd_YOUR_TOKEN"   -H "Content-Type: application/json"   -d '{ "url": "https://example.com/very/long/url" }'

2. x-api-key 標頭

對於不方便使用 Authorization 標頭的專案更便捷。

curl https://rdurl.link/api/link/create   -H "x-api-key: rd_YOUR_TOKEN"   -H "Content-Type: application/json"   -d '{ "url": "https://example.com/very/long/url" }'

第 3 步。驗證金鑰

執行下面的命令。如果回傳連結清單，說明金鑰運作正常。

curl https://rdurl.link/api/link/list \
  -H "Authorization: Bearer rd_YOUR_TOKEN"

金鑰管理

金鑰由 rd_ 加 32 位十六進位字元組成。產生後只能檢視一次，請妥善保管。如果懷疑洩漏，請立即在儀表板中撤銷金鑰，撤銷後金鑰立即失效。

端點

POST /api/link/create

建立短連結。傳送 URL 後回傳 slug 和短連結。

參數

url要縮短的 URL（必填）
title連結標題（選填，100 字元以內）
folder連結資料夾（選填，100 字元以內 — 可依資料夾篩選清單）
domain自訂網域（可選，如 example.com）

請求

{ "url": "https://example.com/very/long/url" }

回應

{
  "success": true,
  "message": {
    "slug": "abc123",
    "short": "https://rdurl.link/abc123",
    "domain_no": 0,
    "domain": ""
  }
}

GET /api/link/list

分頁查詢我的連結，每頁 20 筆。支援搜尋與網域篩選。

參數

page頁碼（預設 1）
domain自訂網域（可選，如 example.com）
search搜尋關鍵字（slug/URL 部分比對）
folder連結資料夾（選填，100 字元以內 — 可依資料夾篩選清單）

請求

GET /api/link/list?page=1&domain=example.com&search=keyword

回應

{
  "success": true,
  "message": {
    "total": 42,
    "page": 1,
    "list": [
      {
        "slug": "abc123",
        "url": "https://example.com/very/long/url",
        "short": "https://rdurl.link/abc123",
        "clicks": 128,
        "tm": 1789379625000
      }
    ]
  }
}

GET /api/link/info

查詢單一連結的詳細資訊和點擊數。

參數

slugslug（必填）
domain自訂網域（可選，如 example.com）

請求

GET /api/link/info?slug=abc123

回應

{
  "success": true,
  "message": {
    "slug": "abc123",
    "url": "https://example.com/very/long/url",
    "short": "https://rdurl.link/abc123",
    "clicks": 128,
    "tm": 1789379625000
  }
}

GET /api/link/stats

連結點擊統計 — 查詢累計、今日和國家 TOP 10。

參數

slugslug（必填）
domain自訂網域（可選，如 example.com）

請求

GET /api/link/stats?slug=abc123

回應

{
  "success": true,
  "message": {
    "clicks": 128,
    "clicksToday": 5,
    "countries": [
      { "country": "KR", "clicks": 80 },
      { "country": "US", "clicks": 30 }
    ]
  }
}

DELETE /api/link

刪除連結。全域連結 30 天內可還原，自訂網域連結立即徹底刪除。

參數

slugslug（必填）
domain自訂網域（可選，如 example.com）

請求

DELETE /api/link
{ "slug": "abc123" }

回應

{ "success": true }

速率限制

每個 IP 每分鐘 10 次，每個帳戶每天最多 1,000 個連結。超出限制回傳 429。

錯誤代碼

失敗時回傳 success: false 和錯誤代碼。

{ "success": false, "message": "api_invalid_token" }

code	status	含義
`api_invalid_token`	401	金鑰缺失或無效
`link_invalid_url`	400	URL 無效（僅限 http/https）
`link_invalid_slug`	400	slug 格式無效
`link_not_found`	400	連結不存在
`domain_not_found`	400	自訂網域不存在
`link_own_domain`	400	不能縮短自己的網域
`link_create_failed`	400	連結建立失敗
`link_rate_limit`	429	超出請求限制