رفتن به محتوا
cutty.dev
برای توسعه‌دهندگان

API و سرور MCP

لینک‌های کوتاه را از کد خودتان بسازید و مدیریت کنید — از طریق REST API یا با سرور MCP در دستیار هوش مصنوعی‌تان.

cutty یک API عمومی و یک سرور MCP دارد. اولی به شما اجازه می‌دهد لینک‌ها را از کد بسازید و تغییر دهید؛ دومی مستقیم از یک دستیار هوش مصنوعی که به پروتکل MCP صحبت می‌کند کار می‌کند. هر دو از یک کلید API استفاده می‌کنند.

کلید API

هر فراخوان را با یک هدر احراز هویت کنید:

Authorization: Bearer ck_your_key

کلید را از کجا بگیرید: وارد شوید، داشبورد خود را باز کنید ← API keys ← Create key. کلید کامل (که با ck_ شروع می‌شود) فقط یک‌بار، هنگام ساخت، نمایش داده می‌شود — همان موقع جایی امن ذخیره‌اش کنید. محدودیت ۱۲۰ درخواست در دقیقه برای هر کلید است.

نشانی پایه

همهٔ اندپوینت‌های REST زیر https://cutty.dev/api/v1 قرار دارند. درخواست‌ها و پاسخ‌ها JSON هستند.

ساختن یک لینک

POST /api/v1/links — بدنهٔ JSON دست‌کم به یک url نیاز دارد. باقی اختیاری است:

  • url — نشانی مقصد (الزامی)
  • slug — پایانهٔ سفارشی، ۳ تا ۴۰ نویسه؛ برای یک مقدار تصادفی آن را خالی بگذارید
  • expiresAt — تاریخ انقضا در قالب ISO 8601
  • maxHits — محدودیت کلیک (۱ تا ۱٬۰۰۰٬۰۰۰)
  • 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} — جزئیات یک لینک.

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 در یک درخواست چند لینک می‌سازد. یک آرایهٔ links بفرستید (هر آیتم مثل یک ساخت عادی)، تا ۵۰۰ تا در هر بار. پاسخ برای هر ردیف یک نتیجه برمی‌گرداند.

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 یک خلاصهٔ کلیک برمی‌گرداند: مجموع، تفکیک بر اساس دستگاه و مرورگر، و توزیع در ۲۴ ساعت گذشته.

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

سرور MCP

اگر با یک دستیار هوش مصنوعی کار می‌کنید، می‌توانید cutty را از طریق MCP (Model Context Protocol) وصل کنید و درست در همان گفتگو از آن بخواهید لینک‌ها را کوتاه و سامان‌دهی کند. سرور روی https://mcp.cutty.dev/mcp با Streamable HTTP اجرا می‌شود، و با همان کلید API احراز هویت می‌کنید — هدر Authorization: Bearer ck_....

فهرست کامل ابزارها، قطعه‌کدهای آمادهٔ اتصال و نمونه‌ها در یک صفحهٔ جداگانه هستند: سرور MCP cutty.

چیزی کار نمی‌کند؟

به [email protected] بنویسید — همان روز پاسخ می‌دهم.