本文へ移動
cutty.dev
開発者向け

API と MCP サーバー

REST API、または AI アシスタント内の MCP サーバーを通じて、自分のコードから短縮リンクを作成・管理できます。

cutty には公開APIとMCPサーバーがあります。前者はコードからリンクを作成・変更するためのもの、後者はMCPプロトコルを話すAIアシスタントからそのまま使えるものです。どちらも同じAPIキーを使います。

APIキー

すべての呼び出しはヘッダーで認証します:

Authorization: Bearer ck_your_key

キーの取得先: サインインしてダッシュボード → APIキー → キーを作成 を開きます。完全なキー（ck_ で始まります）が表示されるのは作成時の一度だけなので、すぐに安全な場所に保存してください。上限はキーごとに毎分120リクエストです。

ベースURL

RESTのエンドポイントはすべて https://cutty.dev/api/v1 の下にあります。リクエストもレスポンスもJSONです。

リンクの作成

POST /api/v1/links — JSONボディには最低でも url が必要です。あとは任意です:

  • url — 行き先のアドレス（必須）
  • slug — カスタムの末尾、3〜40文字。省略するとランダムになります
  • expiresAt — ISO 8601 形式の有効期限の日付
  • maxHits — クリック数の上限（1〜1,000,000）
  • password — リンクを保護するパスワード
  • tags — ダッシュボードで整理するためのカンマ区切りのラベル
  • folder — リンクを入れるフォルダの名前
  • utmSource、utmMedium、utmCampaign — リダイレクト時に付与されるUTMパラメータ

レスポンスでは slug、shortUrl、target が返ります。

curl -X POST https://cutty.dev/api/v1/links \
  -H "Authorization: Bearer ck_your_key" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/a/very/long/address","slug":"offer","tags":"campaign,summer"}'

一覧と単一リンク

GET /api/v1/links はあなたのリンクをすべて返します。GET /api/v1/links/{slug} は1つの詳細です。

curl https://cutty.dev/api/v1/links/offer \
  -H "Authorization: Bearer ck_your_key"

更新と削除

PATCH /api/v1/links/{slug} は渡したフィールドを更新し、DELETE /api/v1/links/{slug} はリンクを削除します。

curl -X PATCH https://cutty.dev/api/v1/links/offer \
  -H "Authorization: Bearer ck_your_key" \
  -H "Content-Type: application/json" \
  -d '{"maxHits":500}'

PATCH では、たとえば次のものを設定できます: targetUrl、expiresAt、maxHits、status、password、tags、folder、そして以下の高度なフィールド。フィールドを null（または空文字列）にすると、その項目はクリアされます。

ターゲティング、A/B、高度なフィールド

リンクエディタで使えるものと同じことが、APIからも行えます:

  • rules — 国やデバイスによるリダイレクトルールの配列。例: [{"kind":"country","match":"PL","url":"https://shop.pl"},{"kind":"device","match":"ios","url":"https://apps.apple.com/..."}]
  • abUrls — A/Bローテーション: 配列 [{"url":"https://a.com","weight":1},{"url":"https://b.com","weight":1}]。どのルールにも当てはまらないときに使われます
  • startsAt — リンクが有効になる日時（ISO 8601）。それ以前はリンクは 425 を返します
  • webhookUrl — クリックのたびに POST 通知を受け取るアドレス（送りっぱなし）
  • serveOg と ogTitle、ogDescription、ogImageUrl — ソーシャルのクローラー向けのカスタムプレビューカード（人間はそのままリダイレクトされます）
curl -X PATCH https://cutty.dev/api/v1/links/offer \
  -H "Authorization: Bearer ck_your_key" \
  -H "Content-Type: application/json" \
  -d '{"rules":[{"kind":"country","match":"DE","url":"https://example.de"}]}'

一括操作

POST /api/v1/bulk は1回のリクエストで多数のリンクを作成します。links 配列（各項目は通常の作成と同じ形式）を、1度に最大500件まで渡せます。レスポンスでは行ごとの結果が返ります。

curl -X POST https://cutty.dev/api/v1/bulk \
  -H "Authorization: Bearer ck_your_key" \
  -H "Content-Type: application/json" \
  -d '{"links":[{"url":"https://a.com"},{"url":"https://b.com","slug":"b"}]}'

リンクの統計

GET /api/v1/links/{slug}/stats はクリックの概要を返します: 合計、デバイス別とブラウザ別の内訳、そして直近24時間の分布です。

curl https://cutty.dev/api/v1/links/offer/stats \
  -H "Authorization: Bearer ck_your_key"

MCPサーバー

AIアシスタントを使っているなら、MCP（Model Context Protocol）で cutty を接続し、会話の中でそのままリンクを短縮・整理してもらえます。サーバーは https://mcp.cutty.dev/mcp で Streamable HTTP として動き、認証は同じAPIキー、つまり Authorization: Bearer ck_... ヘッダーで行います。

ツールの完全な一覧、すぐに使える接続スニペット、サンプルは専用ページにまとめています： cutty MCP サーバー。

うまく動かないときは？

[email protected] までご連絡ください。その日のうちに返信します。