CTAurl APIでできるようになること
CTAurl APIはまだ使えません。公開後は、自社のシステムから短縮URLとQRコードを作成できます。HTTPS上でJSONをやり取りするシンプルなREST APIで、エンドポイントはhttps://app.ctaurl.com/api/v1です。すべてのリクエストはワークスペースのBearerトークンで認証し、受け付けるリクエストは次のとおりです。
| リクエスト | 内容 |
|---|---|
POST /links | CTAドメインまたはctaurl.meでリンクを作成。末尾の文字列、タイトル、タグ、有効期限（expiresAt）は任意で指定可能 |
GET /links/{id} | リンクを1件取得 |
PATCH /links/{id} | リンクを無効化（{"disabled": true}） |
POST /qr-codes | 既存のリンクのQRコードを作成。または新しいリンクとそのQRコードを1回で作成 |
GET /qr-codes/{id} | QRコードを取得 |
PATCH /qr-codes/{id} | QRコードの色とスタイルを変更 |
GET /qr-codes/{id}/svg、/png | QRコードをSVGまたはPNGでダウンロード |
APIトークンと権限
CTAurlのAPIトークンは、ワークスペースのオーナーがアプリのSettings → API keys（設定 → APIキー）で作成します。トークンはRead only（読み取り専用）かManage（読み取りと作成）のどちらかです。トークンが表示されるのは作成時の1回だけで、いつでも無効にできます。1つのワークスペースで有効なトークンは20個までです。トークンはAuthorizationヘッダーで送ります。
Authorization: Bearer cta_live_…APIで短縮URLを作成する方法
APIの公開後、短縮URLを作成するには、POST /linksにBearerトークン、Idempotency-Key、JSONの本文を付けて送ります。作成リクエストには必ずIdempotency-Keyを付けます。値は、Unixミリ秒の時刻、ドット、UUID v4をつなげたものです。リクエストがタイムアウトしたときは、24時間以内に同じキーで送り直せば、2本目のリンクは作られず、最初の結果が返ります。
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で作ったリンクも、アプリで作ったリンクと同じ毎月の作成枠に数えられます。
レート制限とエラー
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では、リンクの一覧取得、リンク先の変更（アプリで行ってください）、クリック数やスキャン数の取得はできません。WebhookとSDKはなく、独自ドメインも使えません。どれかが使えるようになったら、このページでお知らせします。
APIについてよくある質問
CTAurlにAPIはありますか？
まだありません。CTAurl APIは開発済みですが、まだ公開していません。公開後は、短縮URLとQRコードの作成と取得、リンクの無効化、QRコードのSVG・PNGでのダウンロードができます。トークンはワークスペースのオーナーがSettingsのAPI keysで作成します。リンクの一覧取得、リンク先の変更、クリック数の取得、Webhookの送信には対応していません。
CTAurl APIにレート制限はありますか？
あります。公開後のCTAurl APIの上限は、ワークスペースごとに毎分60リクエストです。上限を超えたリクエストには、Retry-Afterヘッダー付きの429が返ります。APIで作ったリンクも、アプリで作ったリンクと同じく、プランの毎月のリンクの作成枠に数えられます。