Reurl API

基础地址：https://api.reurl.to/v1。账号 API Token 在后台 https://app.reurl.to 创建。

未带版本号的路径仍作为兼容别名保留；新集成请统一使用 /v1。

认证

业务 API 通过标准 Authorization Header 接收 API Token。

Authorization: Bearer reurl_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

控制台请求也可以使用邮箱验证码或 GitHub 登录后产生的 session cookie。账号 Token 管理接口必须使用这个浏览器 session。API Token 不能管理其他 API Token。

接口组织

/v1/links 只管理短网址资源，/v1/qr 只负责二维码生成与下载，/v1/geoip 只负责 IP/域名查询。每组资源只承担一类职责，并使用相同 JSON 信封；短链跳转仍使用 https://reurl.to/:code，不展示广告或等待页。

响应格式

所有 JSON 工具 API 使用同一信封，资源数据保持简单并放在 data 下：

操作	响应结构
查看链接列表	`{ "code": 200, "msg": "ok", "data": { "links": [...] } }`
创建短链接	`{ "code": 201, "msg": "created", "data": { "link": {...}, "short_url": "https://reurl.to/code" } }`
读取或更新短链接	`{ "code": 200, "msg": "ok", "data": { "link": {...} } }`
删除短链接	`{ "code": 200, "msg": "ok", "data": { "deleted": true } }`
短链接 QR 资产	`{ "code": 201, "msg": "created", "data": { "qr_code": {...} } }`
独立 QR 生成	`{ "code": 200, "msg": "ok", "data": { "qr_code": {...} } }`
IP/域名归属地服务	`{ "code": 200, "msg": "ok", "data": { "country": {...}, "asn": {...}, "city": {...} } }`
查看 Token	`{ "code": 200, "msg": "ok", "data": { "tokens": [...], "limit": 5 } }`
创建 Token	`{ "code": 201, "msg": "created", "data": { "token": "reurl_..." } }`
删除 Token	`{ "code": 200, "msg": "ok", "data": { "deleted": true } }`

错误响应使用同一信封：

{
  "code": 401,
  "msg": "Authentication is required.",
  "data": null,
}

直接文件输出是例外：短链二维码 SVG 和 QR 下载 URL 成功时返回图片字节，错误仍使用 JSON 信封。

访问策略

短链接、二维码、GeoIP、统计和其他业务 API 都不设置服务端调用限速或业务配额。API Token 只用于鉴权并标识账号和资源所有者。每个账号最多保留 5 个有效 API Token。

Token 管理本身必须使用浏览器 session。邮箱验证码仍保留防刷，这是认证安全控制，不是业务额度。

Account tokens

Token 管理必须使用邮箱验证码或 GitHub 登录后的浏览器会话。删除 Token 会彻底移除记录，不能恢复，也不能再用于调用 API。

GET /v1/tokens
POST /v1/tokens
DELETE /v1/tokens/:id

短链接

查看链接：

curl https://api.reurl.to/v1/links \
  -H "Authorization: Bearer reurl_xxx"

用 JSON 创建链接：

curl -X POST https://api.reurl.to/v1/links \
  -H "Authorization: Bearer reurl_xxx" \
  -H "Content-Type: application/json" \
  -d '{"target_url":"https://example.com","code":"launch"}'

更新状态或元数据：

curl -X PATCH https://api.reurl.to/v1/links/LINK_ID \
  -H "Authorization: Bearer reurl_xxx" \
  -H "Content-Type: application/json" \
  -d '{"is_active":false}'

删除链接：

curl -X DELETE https://api.reurl.to/v1/links/LINK_ID \
  -H "Authorization: Bearer reurl_xxx"

短链接 QR 适配接口

短链接 QR 接口属于短链接 API。它把短链接 URL 作为输入调用 QR 生成能力。

curl https://api.reurl.to/v1/links/LINK_ID/qr \
  -H "Authorization: Bearer reurl_xxx"

响应是图片字节。如果输入是任意文本而不是短链接，请使用下面的独立 QR 接口。

保存短链接 QR 资产：

curl -X POST https://api.reurl.to/v1/links/LINK_ID/qr \
  -H "Authorization: Bearer reurl_xxx" \
  -H "Content-Type: application/json" \
  -d '{"persist":true,"format":"svg"}'

响应：

{
  "code": 201,
  "msg": "created",
  "data": {
    "qr_code": {
      "key": "qr/launch.svg",
      "format": "svg",
      "short_url": "https://reurl.to/launch"
    }
  }
}

独立 QR 生成

把任意文本生成二维码。默认返回 JSON，内联 SVG 位于 data.qr_code.svg。

curl -X POST https://api.reurl.to/v1/qr/text \
  -H "Authorization: Bearer reurl_xxx" \
  -H "Content-Type: application/json" \
  -d '{"text":"https://example.com","format":"svg"}'

请求 7 分钟有效的下载文件：

curl -X POST https://api.reurl.to/v1/qr/text \
  -H "Authorization: Bearer reurl_xxx" \
  -H "Content-Type: application/json" \
  -d '{"text":"launch code","format":"svg","download":true}'

响应：

{
  "code": 201,
  "msg": "created",
  "data": {
    "qr_code": {
      "format": "svg",
      "content_type": "image/svg+xml; charset=utf-8",
      "download_url": "https://api.reurl.to/v1/qr/download/abc123",
      "expires_at": "2026-07-26T12:07:00.000Z",
      "expires_in_seconds": 420
    }
  }
}

下载地址创建后 7 分钟失效。过期访问会直接清理对象，定时任务也会继续批量清理。

独立 QR 生成支持 svg 和 png。SVG 响应包含内联 SVG 文本；PNG 响应包含 base64 图片字节，download:true 会返回 7 分钟有效的下载 URL。

IP 和域名归属地

直接 API 查询需要 Token。官网首页查询表单不需要粘贴 Token，并同时返回文本摘要和 JSON。业务调用不设置服务端额度或调用限速。

组合查询：

curl "https://api.reurl.to/v1/geoip/lookup?ip=8.8.8.8&lang=en" \
  -H "Authorization: Bearer reurl_xxx"

按类型查询：

curl "https://api.reurl.to/v1/geoip/country?ip=1.1.1.1&lang=en" \
  -H "Authorization: Bearer reurl_xxx" \
curl "https://api.reurl.to/v1/geoip/asn?ip=1.1.1.1&lang=en" \
  -H "Authorization: Bearer reurl_xxx" \
curl "https://api.reurl.to/v1/geoip/city?ip=1.1.1.1&lang=en" \
  -H "Authorization: Bearer reurl_xxx"

域名查询：

curl -X POST https://api.reurl.to/v1/geoip/lookup \
  -H "Authorization: Bearer reurl_xxx" \
  -H "Content-Type: application/json" \
  -d '{"input":"example.com"}'

典型响应：

{
  "code": 200,
  "msg": "ok",
  "data": {
    "ip": "1.1.1.1",
    "lang": "en",
    "country": { "countryCode": "AU", "countryName": "Australia" },
    "asn": { "autonomousSystemNumber": 13335, "autonomousSystemOrganization": "Example Network" },
    "city": { "countryCode": "AU", "city": "Sydney", "timezone": "Australia/Sydney" }
  }
}

活动数据集会在校验通过后按版本切换。刷新失败时继续使用上一个活动版本。

归属地是基于数据集的 best-effort 结果，不是街道地址，也不能当成精确用户身份信号。

Token 管理

Token 管理必须使用控制台登录 session。这些接口不接受 API Token。

查看 Token：

curl https://api.reurl.to/v1/tokens \
  -H "Cookie: reurl_session=..."

创建 Token：

curl -X POST https://api.reurl.to/v1/tokens \
  -H "Cookie: reurl_session=..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Production"}'

删除 Token：

curl -X DELETE https://api.reurl.to/v1/tokens/TOKEN_ID \
  -H "Cookie: reurl_session=..."

登录防刷

配置后端 TURNSTILE_SECRET 后，邮箱验证码登录会启用浏览器挑战。后端会在发送邮件前校验 token。