CTAurl API 將會做什麼？
CTAurl API 目前尚未提供。開放後，它可以讓你在自己的系統裡建立短網址和 QR code。它是一個精簡的 REST API，經 HTTPS 傳送 JSON 內容，地址是 https://app.ctaurl.com/api/v1。每個請求都要用工作區的 bearer token 驗證身分，可用的請求如下：
| 請求 | 用途 |
|---|---|
POST /links | 在動作網域或 ctaurl.me 上建立連結，可選填短網址後綴、標題、標籤和到期時間（expiresAt） |
GET /links/{id} | 讀取一條連結 |
PATCH /links/{id} | 停用連結（{"disabled": true}） |
POST /qr-codes | 為現有連結建立 QR code，或一次建立新連結和它的 QR code |
GET /qr-codes/{id} | 讀取一個 QR code |
PATCH /qr-codes/{id} | 更改 QR code 的顏色和樣式 |
GET /qr-codes/{id}/svg、/png | 下載 SVG 或 PNG 格式的 QR code |
API token 與權限
CTAurl API token 由工作區擁有人在 app 內的 Settings → API keys 建立。每個 token 屬於 Read only（只可讀取）或 Manage（讀取及建立）其中一種。token 只在建立時顯示一次，可隨時撤銷。每個工作區最多可有 20 個有效 token。請把 token 放在 Authorization 標頭中傳送：
Authorization: Bearer cta_live_…怎樣用 API 建立短網址
API 開放後，要建立短網址，就用你的 bearer token 發送 POST /links，附上 Idempotency-Key 和 JSON 內容。每個建立請求都要帶 Idempotency-Key：以 Unix 毫秒表示的時間、一個點，再加一個 UUID v4。如果請求逾時，在 24 小時內用同一個 key 再發送一次，你會得到原本的結果，而不會多建一條連結。
curl https://app.ctaurl.com/api/v1/links \
-H "Authorization: Bearer $CTAURL_TOKEN" \
-H "Idempotency-Key: 1761638400000.7f8c2a54-3b1e-4c6d-9a0f-2e5b8c1d4f60" \
-H "Content-Type: application/json" \
-d '{"domain":"立即購買.me","shortCode":"sneaker","destinationUrl":"https://shop.abc.yz/sneaker"}'請求成功會回傳 201 和連結資料，包括 shortUrl。如果沒有提供 shortCode，系統會自動產生短網址後綴。經 API 建立的連結，將與在 app 內建立的連結計入同一個每月額度。
請求上限與錯誤
CTAurl API 每個工作區每分鐘上限 60 次請求，錯誤會以 JSON 回傳並附固定的錯誤代碼，而且只會處理發往 app.ctaurl.com 的請求。
- 每個工作區每分鐘 60 次請求。超出上限會回傳
429和Retry-After。 - 錯誤以 JSON 回傳：
{"error": {"code": "…", "message": "…"}}，附固定代碼，例如INVALID_REQUEST、FORBIDDEN_SCOPE或RESOURCE_UNAVAILABLE。 - 只處理發往
app.ctaurl.com的請求。
API 目前還不會做的事
除了尚未開放之外，CTAurl API 也不會列出所有連結、更改連結的目的地網址（請在 app 內更改），或回傳點擊和掃描次數。目前沒有 webhook 和 SDK，自訂網域也未提供。這些功能推出時，本頁會註明。
關於 API 的常見問題
CTAurl 有 API 嗎？
還沒有。CTAurl API 已經建好，但尚未開放。開放後，它可以建立和讀取短網址及 QR code、停用連結，以及下載 SVG 或 PNG 格式的 QR code，所用的 token 由工作區擁有人在 Settings 的 API keys 建立。它不會列出連結、更改目的地、回傳點擊數或發送 webhook。
CTAurl API 有請求次數上限嗎？
有。開放後，CTAurl API 每個工作區每分鐘上限 60 次請求，超出上限的請求會收到 429 回應和 Retry-After 標頭。經 API 建立的連結，也會和在 app 內建立的一樣，計入方案的每月連結額度。