面向开发者

API 与 MCP 服务器

用你自己的代码创建和管理短链接——通过 REST API,或在 AI 助手中借助 MCP 服务器完成。

cutty 提供一套公开 API 和一台 MCP 服务器。前者让你从代码里创建和修改链接；后者直接在会说 MCP 协议的 AI 助手里工作。两者用的是同一个 API 密钥。

API 密钥

每次调用都用一个请求头来鉴权：

Authorization: Bearer ck_your_key

在哪里拿密钥：登录后打开你的控制台 → API keys → Create key。完整密钥（以 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 服务器

如果你用 AI 助手工作，可以通过 MCP（Model Context Protocol）接入 cutty，直接在对话里让它缩短和整理链接。服务器运行在 https://mcp.cutty.dev/mcp，走 Streamable HTTP，用同一个 API 密钥鉴权——即 Authorization: Bearer ck_... 请求头。

完整的工具列表、现成的连接配置片段和示例都在单独的页面上： cutty MCP 服务器。

有什么不顺手？

写信到 [email protected] —— 我当天就回。