TEAM API / v1

团队 API 文档

鉴权与权限

请求头使用 Authorization: Bearer YOUR_API_KEY，同时需要本站登录状态。POST/PATCH 还要求同源 Origin；在本站浏览器上下文中由浏览器提供。

团队密钥以 tm_ 开头。当前登录账号必须是该团队已接受邀请的成员。所有者管理成员与密钥，编辑者可写入链接，只读成员不能写入；密钥自身还需具有 write 权限。

成员被移除、降为只读或账号停用后，相应访问权限会在请求时重新核验。团队链接与个人链接隔离，个人密钥不能访问团队资源。

密钥只显示一次，最多 5 个有效密钥。不要放入 URL、公开网页或代码仓库。

接口列表

`GET /api/team/v1/links`	分页链接列表。支持 q、filter、sort、page、size；size 为 20/50/100。page 从 1 开始。
`POST /api/team/v1/links`	创建链接，首次成功 201，幂等重试成功 200。
`GET /api/team/v1/links/{code}`	读取指定链接，密码只返回是否设置，不返回密码。
`PATCH /api/team/v1/links/{code}`	更新字段，成功 200。不能更换 code、owner 或解除平台封禁。
`GET /api/team/v1/links/{code}/stats`	返回 code、累计 total、from 与近 90 天 daily 数组（day、clicks）。累计数可能与明细和不同。

列表 filter：all、active、inactive、archived、favorites；sort：newest、oldest、clicks、name。响应包含 items、total、page、pages、size、tags、stats。

使用 PATCH {"archived":true} 归档链接，保留数据。当前未提供物理删除接口。

创建与编辑参数

字段	类型	说明
`url`	string	必填。HTTP/HTTPS 完整网址，最长 4096 字符。
`title / note`	string	选填。分别最多保留 120 / 1000 字符。
`code`	string	仅创建时可填。4–40 位字母、数字、横线或下划线。
`request_id`	string	仅创建时可填。16–100 位字母、数字、横线或下划线，用于重试去重。
`tags`	string[]	最多 8 个，每个不超过 24 字符。
`starts / expires`	string \| number \| null	含时区的 ISO 时间或毫秒时间戳。到期晚于开始。
`click_limit`	integer \| null	1–10,000,000；null 为不限制。
`password`	string \| null	8–128 字符；null 移除密码。
`active / archived / favorite`	boolean	启用、归档与收藏状态。归档会暂停跳转，不释放额度。
`ios_url / android_url`	string \| null	设备跳转地址，不可与 A/B 分流同时启用。
`ab_enabled / ab_url / ab_weight`	boolean / string / integer	A/B 分流开关、B 地址及 A 目标比例（1–99）。
`qr_color / qr_style / qr_size`	string / string / integer	深色十六进制颜色；square/rounded/dots；300/600/1200。

请求与响应示例

调用此函数会创建真实链接并占用额度。代码不会自动执行；传入对应的密钥后才可调用。

// Run in this site's authenticated, same-origin context.
// Keep payload unchanged when retrying this creation.
const payload = {
  url: 'https://example.com/product',
  title: 'Product launch',
  request_id: crypto.randomUUID()
};
async function createLink(apiKey) {
  const response = await fetch('/api/team/v1/links', {
    method: 'POST',
    credentials: 'same-origin',
    headers: {
      Authorization: 'Bearer ' + apiKey,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(payload)
  });
  const data = await response.json();
  if (!response.ok) throw new Error(data.error || response.status);
  return new URL('/s/' + data.code, location.origin).href;
}

// 201
{"code":"aB12cd34"}
// 200 replay
{"code":"aB12cd34","replayed":true}
// Error
{"error":"…"}

相同 request_id 与相同内容重试返回原链接；同标识更换内容返回 409。网络超时先检查是否已创建，再保留原请求内容重试。

错误码与限制

400	参数错误
401	未登录或密钥无效、撤销、过期
403	权限不足、账号停用或来源无效
404	资源不存在或不在授权范围
409	后缀或请求内容冲突
429	限速或额度上限
503	服务暂时不可用

每个密钥每 60 秒最多通过 30 次授权校验；创建另受资源空间额度和每分钟创建上限限制。失败的业务请求也可能计入密钥调用数。

当前团队试用每队最多保存 100 条短链接，每分钟最多创建 10 条。不是正式 Team 套餐计费额度。

外部服务器调用、自定义品牌域名、团队计费和第三方连接器尚未开放。接口格式为 Tapmio 自有格式，不能直接替换 Cuttly 的地址或密钥。