toui.io API

用程式建立短連結、查詢網址中繼資料、讀取點擊統計。一個基於 HTTPS 的精簡 REST API，外加官方 toui-js SDK（支援 JavaScript 與 TypeScript）。

快速開始

安裝 SDK，一分鐘內縮短你的第一條連結。想用原生 HTTP？切到 curl 分頁——每個端點都能在任何語言中使用。

npm install toui-js

curl -X POST https://toui.io/api/v1/shorten \
  -H "Authorization: Bearer toui_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/a-very-long-link"}'

import { Toui } from 'toui-js';

const toui = new Toui({ apiKey: process.env.TOUI_API_KEY! });

const { short_url } = await toui.shorten({ url: 'https://example.com/a-very-long-link' });
console.log(short_url); // https://toui.io/aBcD3f

你需要先有 API key——請見驗證。

在你的 AI 工具裡用 toui

toui 在 https://mcp.toui.io 提供遠端 MCP server——在 Claude、ChatGPT、Cursor、Cline 或任何支援 MCP 的 agent 裡直接縮網址，不用離開對話。免 API key，走 OAuth。

Cursor — 一鍵

或手動加到 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "toui": { "url": "https://mcp.toui.io" }
  }
}

Cline、Claude、ChatGPT 等 agent：把 https://mcp.toui.io 貼為自訂 MCP/connector。參考設定指南。

toui 也收錄於 MCP server registry Smithery。

驗證

所有請求都使用 Bearer token 驗證。在你的後台 → API Keys 建立金鑰，並放入 Authorization 標頭：

Authorization: Bearer toui_YOUR_API_KEY

金鑰只在建立時顯示一次。請當成密碼般保管，切勿嵌入前端程式碼。所有端點的 base URL 為 https://toui.io/api/v1。

建立短網址

POST /api/v1/shorten

建立一條短連結。只有 url 為必填。custom_code 為付費方案專屬；Open Graph 欄位（og_title、og_description、og_image_url）所有方案皆可用，用於控制社群分享預覽。

curl -X POST https://toui.io/api/v1/shorten \
  -H "Authorization: Bearer toui_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/long",
    "custom_code": "promo",
    "title": "Spring sale",
    "og_title": "Spring sale",
    "og_description": "Up to 50% off",
    "og_image_url": "https://example.com/banner.png"
  }'

const url = await toui.shorten({
  url: 'https://example.com/long',
  custom_code: 'promo',        // paid plans only
  title: 'Spring sale',
  og_title: 'Spring sale',
  og_description: 'Up to 50% off',
  og_image_url: 'https://example.com/banner.png',
});

回應 · 201 Created

{
  "short_url": "https://toui.io/aBcD3f",
  "short_code": "aBcD3f",
  "target_url": "https://example.com/long",
  "created_at": "2026-06-04T08:00:00.000Z"
}

查詢短網址

GET /api/v1/urls/:code

回傳你擁有的短碼的中繼資料與累計點擊數。若該短碼不在你的 team 中，回傳 404。

curl https://toui.io/api/v1/urls/aBcD3f \
  -H "Authorization: Bearer toui_YOUR_API_KEY"

const url = await toui.get('aBcD3f');
console.log(url.click_count, url.target_url);

回應 · 200 OK

{
  "short_code": "aBcD3f",
  "target_url": "https://example.com/long",
  "title": "Spring sale",
  "click_count": 42,
  "created_at": "2026-06-04T08:00:00.000Z",
  "is_active": true,
  "og_title": null,
  "og_description": null,
  "og_image_url": null
}

查詢統計

GET /api/v1/urls/:code/stats?days=30

回傳每日點擊與國家分布。days 區間受方案的資料保留期上限限制（Free 30、Pro 90、Business 365 天）。付費方案（含進階分析）會在同一回應中額外取得來源與裝置分布。

curl "https://toui.io/api/v1/urls/aBcD3f/stats?days=30" \
  -H "Authorization: Bearer toui_YOUR_API_KEY"

const stats = await toui.stats('aBcD3f', { days: 30 });
console.log(stats.total_clicks);
for (const day of stats.daily) {
  console.log(day.date, day.clicks, day.unique_visitors);
}

回應 · 200 OK

{
  "short_code": "aBcD3f",
  "target_url": "https://example.com/long",
  "total_clicks": 128,
  "daily": [
    { "date": "2026-06-01", "clicks": 5, "unique_visitors": 4 }
  ],
  "countries": [
    { "country": "TW", "clicks": 80 }
  ]
}

SDK (toui-js)

toui-js 是官方 TypeScript SDK——零相依、原生 fetch，可在 Node 18+、Bun、Deno、Cloudflare Workers 與瀏覽器中執行。原始碼在 GitHub，已發佈於 npm。

npm install toui-js

用 new Toui({ apiKey, baseUrl?, fetch? }) 建立 client，再呼叫 shorten()、get() 或 stats()。錯誤會丟出帶有 HTTP status 的 TouiError：

import { Toui, TouiError } from 'toui-js';

try {
  await toui.shorten({ url: 'not-a-url' });
} catch (err) {
  if (err instanceof TouiError) {
    console.error(err.status, err.message); // 400 …
  }
}

錯誤

錯誤會回傳含 error 訊息的 JSON 與標準 HTTP 狀態碼。速率限制回應會額外帶上描述限制的欄位。

狀態	意義
`400`	請求無效——缺少/無效的 `url`，或在免費方案使用 `custom_code`
`401`	缺少、格式錯誤或已撤銷的 API key
`404`	短碼不在你的 team 中
`429`	超過速率限制或配額（見速率限制）

速率限制

分兩層：每分鐘 burst 限制，以及每月/每日配額。每個回應都含 X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset 標頭。新的免費帳號在前 48 小時內會被限流。

方案	Burst (req/min)	每月配額	每日配額
Free	60	5,000	500
Pro	200	500,000	Unlimited
Business	600	2,000,000	Unlimited

429 burst 回應含 retry_after（秒）；配額回應含 resets_at（ISO 時間戳）。