toui.io API

クイックスタート

SDKをインストールすれば、1分もかからずに最初のリンクを短縮できます。生の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キーが必要です——認証をご覧ください。

AIツールの中で toui を使う

toui は https://mcp.toui.io でリモート MCP サーバーを提供しています。Claude、ChatGPT、Cursor、Cline、その他 MCP に対応したエージェントの中で、会話を離れることなく、リンクの短縮、チャネルのタグ付け、キャンペーンへの分類、クリック成果の確認ができます。APIキーは不要で、OAuthで接続します。

Cursor — ワンクリック

または ~/.cursor/mcp.json に手動で追加します：

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

Claude では、設定 → コネクタ →「Discover」で toui を検索するか、Claude のコネクタディレクトリにある toui を直接開きます。

Cline、ChatGPT などのエージェントでは、https://mcp.toui.io をカスタムMCP／コネクタとして貼り付けます。設定ガイドもあわせてご覧ください。

toui は MCP サーバーレジストリ Smithery にも登録されています。

認証

すべてのリクエストは Bearer トークンで認証します。 ダッシュボード → API でキーを作成し、Authorization ヘッダーに入れてください：

Authorization: Bearer toui_YOUR_API_KEY

キーが表示されるのは作成時の一度きりです。パスワードと同じように扱い、フロントエンドのコードには決して埋め込まないでください。すべてのエンドポイントのベースURLは https://toui.io/api/v1 です。

短縮リンクの作成

POST /api/v1/shorten

短縮リンクを1本作成します。必須は url だけです。custom_code は有料プラン限定で、Open Graph の各項目（og_title、og_description、og_image_url）はどのプランでも利用でき、SNSでの共有プレビューを制御できます。

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',
});

有料プランでは、1本のリンクを訪問者のデバイスと地域で振り分けられます。ios、android（リンク先URL）と geo（ISO 3166-1 alpha-2 の国コードとURLの対応表）を追加してください。訪問者は上から順に照合され——iOS → Android → geo → 既定の url——iPhoneのユーザーは App Store へ、Android のユーザーは Google Play へ、各国の訪問者はそれぞれのページへ届きます。

デバイスと地域による振り分け · Pro+

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/download",
    "ios": "https://apps.apple.com/app/id000000000",
    "android": "https://play.google.com/store/apps/details?id=com.example",
    "geo": { "US": "https://example.com/us", "JP": "https://example.com/jp" }
  }'

const url = await toui.shorten({
  url: 'https://example.com/download',
  ios: 'https://apps.apple.com/app/id000000000',
  android: 'https://play.google.com/store/apps/details?id=com.example',
  geo: { US: 'https://example.com/us', JP: 'https://example.com/jp' },
});

レスポンス · 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"
}

GUIツールとの連携

デスクトップやスマートフォンのアプリの多く（Shortshare、Apple のショートカット、Raycast など）は、「custom service」の入力欄や HTTP アクションから任意の短縮URLサービスを呼び出せます。項目の対応は次のとおりです：

短縮リンクの取得

GET /api/v1/urls/:code

自分が保有する短縮コードのメタデータと累計クリック数を返します。そのコードが自分のチームのものでない場合は 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 60 日、Pro 180 日、Pro+ 365 日、Business 730 日）、それより大きい値はその期間までに切り詰められます。total_clicks は常に、リンク作成からの全期間の合計です。days がプランの表示期間を超えると、レスポンスの clamped が true になり、visible_from に表示期間の初日、earlier_clicks にその日より前のクリック数が入ります。それ以外のとき earlier_clicks は 0 です。visible_days はプランで見られる日数です。参照元とデバイスの内訳も同じレスポンスに含まれ、無料プランは各項目の上位3件、有料プラン（詳細分析つき）はより長い一覧を返します。

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 }
  ],
  "cities": [
    { "country": "TW", "city": "Taipei", "clicks": 52 }
  ],
  "visible_days": 60,
  "clamped": false,
  "visible_from": null,
  "earlier_clicks": 0
}

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? }) でクライアントを作り、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ステータスコードで返します。レート制限のレスポンスには、制限の内容を示す項目が追加されます。

レート制限

制限は2層です。1分あたりのバースト制限と、月次・日次のクォータです。すべてのレスポンスに X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset ヘッダーが付きます。新しい無料アカウントは、最初の48時間だけ制限が強くかかります。

バーストによる 429 のレスポンスには retry_after（秒）が、クォータによるものには resets_at（ISO形式のタイムスタンプ）が含まれます。