API

在脚本和应用里创建和管理短链接。API 是免费的。在你的控制台的 API 密钥里创建一个密钥，然后作为 bearer 令牌发送。

身份验证

Authorization: Bearer gz_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

密钥只显示一次。请像对待密码一样对待它：拿到你密钥的人就能在你的账号里创建和编辑链接。密钥泄露了，就在控制台里吊销它。

限制

• 每个密钥每分钟 60 次请求。
• 每个账号每天 500 个新链接。
• 目标地址会对照 Google Safe Browsing 和我们的黑名单检查。其他短链接服务不能作为目标地址。

创建链接

curl -X POST https://gozi.to/api/my/links \
  -H "Authorization: Bearer $GOZI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/launch", "code": "launch"}'

code 是可选的（4–32 个字母、数字、- 或 _）。留空则生成一个随机的 7 位代码。响应 201：

{
  "link": {
    "code": "launch",
    "shortUrl": "https://gozi.to/launch",
    "url": "https://example.com/launch",
    "status": "active",
    "statusReason": null,
    "custom": true,
    "createdAt": 1790000000000,
    "expiresAt": null
  }
}

列出链接

GET /api/my/links?limit=25&cursor=<nextCursor>&q=<search>&clicks=1

按从新到旧排列。把上一页返回的 nextCursor 传进来，就能取到下一页。clicks=1 会加上全部时间的真人点击数。

获取、编辑、删除

GET    /api/my/links/{code}
PATCH  /api/my/links/{code}   {"url": "https://new.example"}  or  {"status": "disabled" | "active"}
DELETE /api/my/links/{code}

分析

GET /api/my/links/{code}/stats

返回最近 90 天和全部时间的真人点击数、每日点击量，以及排在前面的国家和地区、来源、设备、浏览器和操作系统。机器人和链接预览（Slack、WhatsApp 等）单独计入 botClicks。结果会缓存约 5 分钟。

错误

错误使用 HTTP 状态码和一个 JSON 响应体：

{ "error": { "code": "slug_taken", "message": "That custom link is already taken." } }

• 400 输入无效（invalid_url、invalid_slug，…）
• 401 密钥缺失、无效或已吊销
• 409 自定义链接已被占用
• 422 目标地址不被允许（destination_blocked）
• 429 达到速率上限或每日上限

所有端点的机器可读描述见 /openapi.json。