Chuyển đến nội dung chính
cutty.dev
Dành cho nhà phát triển

API và máy chủ MCP

Tạo và quản lý liên kết rút gọn ngay từ mã của bạn — qua REST API hoặc qua máy chủ MCP trong trợ lý AI của bạn.

cutty có một API công khai và một máy chủ MCP. Cái đầu cho phép bạn tạo và thay đổi liên kết từ mã; cái sau hoạt động ngay từ một trợ lý AI biết giao thức MCP. Cả hai dùng chung một khóa API.

Khóa API

Hãy xác thực mọi lệnh gọi bằng một header:

Authorization: Bearer ck_your_key

Lấy khóa ở đâu: đăng nhập, mở bảng điều khiển → API keys → Create key. Khóa đầy đủ (bắt đầu bằng ck_) chỉ hiện đúng một lần, lúc tạo — hãy lưu vào nơi an toàn ngay. Giới hạn là 120 yêu cầu mỗi phút cho mỗi khóa.

Base URL

Tất cả endpoint REST nằm dưới https://cutty.dev/api/v1. Yêu cầu và phản hồi đều ở dạng JSON.

Tạo một liên kết

POST /api/v1/links — phần thân JSON cần tối thiểu một trường url. Phần còn lại là tùy chọn:

  • url — địa chỉ đích (bắt buộc)
  • slug — phần đuôi tùy chỉnh, 3–40 ký tự; bỏ trống để tạo ngẫu nhiên
  • expiresAt — ngày hết hạn theo định dạng ISO 8601
  • maxHits — giới hạn lượt nhấp (1–1.000.000)
  • password — mật khẩu bảo vệ liên kết
  • tags — các nhãn cách nhau bằng dấu phẩy để sắp xếp trong bảng điều khiển
  • folder — tên thư mục chứa liên kết
  • utmSource, utmMedium, utmCampaign — các tham số UTM được gắn thêm khi chuyển hướng

Phản hồi trả về cho bạn slug, shortUrl và 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"}'

Liệt kê và xem một liên kết

GET /api/v1/links trả về tất cả liên kết của bạn. GET /api/v1/links/{slug} — chi tiết của một liên kết.

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

Cập nhật và xóa

PATCH /api/v1/links/{slug} cập nhật các trường bạn truyền vào, DELETE /api/v1/links/{slug} xóa liên kết.

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

Qua PATCH bạn có thể đặt, trong số những trường khác: targetUrl, expiresAt, maxHits, status, password, tags, folder, cùng các trường nâng cao bên dưới. Một trường được đặt thành null (hoặc chuỗi rỗng) sẽ xóa thuộc tính đó.

Định tuyến, A/B và các trường nâng cao

Những thứ bạn có trong trình chỉnh sửa liên kết đều dùng được qua API:

  • rules — một mảng quy tắc chuyển hướng theo quốc gia hoặc thiết bị, ví dụ [{"kind":"country","match":"PL","url":"https://shop.pl"},{"kind":"device","match":"ios","url":"https://apps.apple.com/..."}]
  • abUrls — luân phiên A/B: một mảng [{"url":"https://a.com","weight":1},{"url":"https://b.com","weight":1}]; được dùng khi không có quy tắc nào khớp
  • startsAt — ngày (ISO 8601) liên kết bắt đầu hoạt động; trước thời điểm đó, liên kết trả về 425
  • webhookUrl — địa chỉ nhận thông báo POST ở mỗi lượt nhấp (gửi đi rồi không chờ phản hồi)
  • serveOg kèm ogTitle, ogDescription, ogImageUrl — thẻ xem trước tùy chỉnh cho trình thu thập của mạng xã hội (người dùng vẫn được chuyển hướng như thường)
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"}]}'

Thao tác hàng loạt

POST /api/v1/bulk tạo nhiều liên kết trong một yêu cầu. Hãy truyền một mảng links (mỗi phần tử giống như khi tạo thường), tối đa 500 mỗi lần. Phản hồi trả về kết quả cho từng dòng.

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"}]}'

Thống kê liên kết

GET /api/v1/links/{slug}/stats trả về bản tóm tắt lượt nhấp: tổng số, phân tích theo thiết bị và trình duyệt, cùng phân bố trong 24 giờ qua.

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

Máy chủ MCP

Nếu bạn làm việc với một trợ lý AI, bạn có thể kết nối cutty qua MCP (Model Context Protocol) và nhờ nó rút gọn cùng sắp xếp liên kết ngay trong cuộc trò chuyện. Máy chủ chạy tại https://mcp.cutty.dev/mcp qua Streamable HTTP, và bạn xác thực bằng chính khóa API đó — header Authorization: Bearer ck_....

Danh sách đầy đủ các công cụ, đoạn mã kết nối sẵn dùng và ví dụ nằm ở một trang riêng: máy chủ MCP của cutty.

Có gì đó không hoạt động?

Hãy viết cho [email protected] — tôi trả lời ngay trong ngày.