انتقل إلى المحتوى
cutty.dev
للمطوّرين

واجهة API وخادم MCP

أنشئ روابطك المختصرة وأدِرها من داخل كودك — عبر واجهة REST API أو من خلال خادم MCP في مساعدك الذكي.

يمتلك cutty واجهة API عامة وخادم MCP. الأولى تتيح لك إنشاء الروابط وتغييرها من الشيفرة؛ والثاني يعمل مباشرة من مساعد ذكاء اصطناعي يتحدث بروتوكول MCP. وكلاهما يستخدم مفتاح API نفسه.

مفتاح API

وثِّق كل طلب بترويسة:

Authorization: Bearer ck_your_key

من أين تحصل على مفتاح: سجّل الدخول، وافتح لوحة التحكم ← مفاتيح API ← إنشاء مفتاح. يظهر المفتاح الكامل (يبدأ بـ ck_) مرة واحدة فقط عند الإنشاء — احفظه في مكان آمن فورًا. الحد الأقصى 120 طلبًا في الدقيقة لكل مفتاح.

العنوان الأساسي

جميع مسارات 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} — تفاصيل رابط واحد.

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 عند كل نقرة (fire-and-forget)
  • 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 (كل عنصر مثل عملية إنشاء عادية)، حتى 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

إن كنت تعمل مع مساعد ذكاء اصطناعي، فيمكنك ربط cutty عبر MCP (Model Context Protocol) وأن تطلب منه اختصار الروابط وتنظيمها داخل المحادثة مباشرة. يعمل الخادم على https://mcp.cutty.dev/mcp عبر Streamable HTTP، وتوثّق الاتصال بمفتاح API نفسه — ترويسة Authorization: Bearer ck_....

القائمة الكاملة للأدوات، ومقتطفات الاتصال الجاهزة، والأمثلة موجودة في صفحة مخصّصة: خادم MCP الخاص بـ cutty.

هناك خلل ما؟

راسلني على [email protected] — أردّ في اليوم نفسه.