REST API
基于你的链接，构建更多。

身份、工作区、套餐以及该套餐包含的所有权益。这是验证令牌、在尝试操作前了解账户权限的最简便方式。

curl -H "X-API-KEY: YOUR_TOKEN" \
  https://letl.ink/api/v1/me

{
  "data": {
    "user": { "id": 1, "email": "[email protected]", "name": "You" },
    "workspace": { "id": 12, "name": "My Workspace", "block_bots": true },
    "plan": {
      "id": "growth",
      "name": "Growth",
      "limits": {
        "links": 200,
        "monthly_clicks": 100000,
        "custom_domains": 3,
        "qr_codes": 30,
        "retention_days": 365
      },
      "features": {
        "api": true,
        "webhooks": true,
        "integrations": true,
        "ai_access": false,
        "geo_analytics": false,
        "smart_link_types": true
      }
    },
    "base_domain": "letl.ink"
  }
}

本计费月内每项额度的使用量。可用于在客户达到追踪点击上限前发出提醒——超出后跳转仍然有效，但点击将不再被记录。

{
  "data": {
    "links": { "used": 42, "limit": 200, "remaining": 158, "percent_used": 21.0 },
    "clicks_this_month": { "used": 8140, "limit": 100000, "remaining": 91860, "percent_used": 8.1 },
    "custom_domains": { "used": 1, "limit": 3, "remaining": 2, "percent_used": 33.3 },
    "qr_codes": { "used": 4, "limit": 30, "remaining": 26, "percent_used": 13.3 }
  },
  "meta": { "plan": "growth", "period": "2026-09" }
}

工作区中的自定义域名，以及每个域名是否已完成 DNS 验证。只有已验证的域名才能在创建链接时用作 domain 字段。

产品提供的所有集成、你的套餐是否包含、此工作区是否已连接，以及投递情况——最近状态、最近错误和连续失败次数。适合用于监控多个工作区。

工作区中的链接，点击总数分为 all、ios、android 和 desktop。包含零点击的链接。

查询参数

• domain string

  限定为单个主机名。省略则列出工作区中的所有主机名。

  可选
• search string

  匹配短码、标题和目标网址。

  可选
• type string

  direct、utm、appstore、instagram、mobile 或 device。

  可选
• archived boolean

  默认为 false。传入 true 则列出归档链接。

  可选
• favorite boolean

  仅限已收藏的链接。

  可选
• sort string

  created_at（默认）、clicks、short_code、title 或 updated_at。

  可选
• direction string

  asc 或 desc。默认为 desc。

  可选
• limit integer

  1–200。默认为 50。

  可选
• offset integer

  默认为 0。

  可选
• start_date date

  YYYY-MM-DD。用于限定点击总数的时间范围，而不是筛选返回哪些链接。

  可选
• end_date date

  YYYY-MM-DD，包含当天。

  可选

curl -H "X-API-KEY: YOUR_TOKEN" \
  "https://letl.ink/api/v1/links?sort=clicks&limit=20"

{
  "data": [
    {
      "id": 49,
      "short_code": "spring",
      "domain": "letl.ink",
      "url": "https://letl.ink/spring",
      "destination": "https://shop.example.com/spring",
      "title": "Spring sale",
      "type": "utm",
      "archived": false,
      "favorite": true,
      "created_at": "2026-08-01T09:14:00+00:00",
      "updated_at": "2026-09-02T11:00:00+00:00",
      "clicks": { "all": 650, "ios": 180, "android": 210, "desktop": 260 },
      "total_clicks": 650,
      "device_limit": null,
      "utm": { "source": "twitter", "medium": "social", "campaign": "spring" },
      "split_test": {
        "variations": [
          { "name": "control", "url": "https://example.com/a", "weight": 2 },
          { "name": "variant-b", "url": "https://example.com/b", "weight": 1 }
        ]
      }
    }
  ],
  "meta": {
    "total": 42, "limit": 20, "offset": 0,
    "has_more": true, "next_offset": 20,
    "sort": "clicks", "direction": "desc",
    "date_range": { "start_date": null, "end_date": null },
    "domain": "all"
  }
}

按 ID 获取单个链接，结构与列表端点返回的相同。

创建短链接。省略 short_code 将随机生成。如果目标网址没有 title，我们会在后台抓取页面标题。

JSON 请求体

• destination

  要跳转到的 URL。direct 和 utm 链接必填。也接受 original_url 作为别名。

  必填*
• short_code

  最多 20 个字符：字母、数字、连字符和下划线，不能以分隔符开头或结尾。每个主机名下必须唯一。

  可选
• title

  控制台中显示的名称。

  可选
• domain

  已验证的自定义域名或基础域名。默认为基础域名。

  可选
• type

  direct（默认）、utm、appstore、instagram、mobile 或 device。除 direct 和 utm 外，其他类型都需要 Solo、Growth 或 Ultimate 套餐。

  可选
• utm_source, utm_medium, utm_campaign

  用于 utm 链接；当 type 为 utm 时，utm_source 为必填项。

  可选
• ios_url, android_url

  appstore 和 mobile 链接的各平台目标网址。

  可选
• desktop_url, mobile_url

  device 链接必须同时填写。

  可选
• instagram_username

  用于 instagram 链接。

  可选
• split_variations

  由 {name, url, weight} 对象组成的数组——至少两个——用于在 direct 或 utm 链接上运行加权分流测试。

  可选
• limit_visits_per_device

  设为 true 并提供 visit_limit_per_device，即可限制每台设备每小时的访问次数。

  可选

curl -X POST https://letl.ink/api/v1/links \
  -H "X-API-KEY: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "destination": "https://shop.example.com/spring",
        "short_code": "spring",
        "title": "Spring sale",
        "type": "utm",
        "utm_source": "twitter",
        "utm_campaign": "spring"
      }'

The created link, in the shape shown above.

在一个请求中创建多个链接。每一行都独立处理：有效的行会被创建，失败的行会按索引报告，因此一个错误的 URL 不会导致整批作废。只要有内容被创建就返回 201，全部失败则返回 422。

curl -X POST https://letl.ink/api/v1/links/bulk \
  -H "X-API-KEY: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"links":[
        {"destination":"https://example.com/1","short_code":"one"},
        {"destination":"https://example.com/2"}
      ]}'

{
  "data": [ { "id": 51, "short_code": "one", … } ],
  "meta": {
    "requested": 2,
    "created": 1,
    "failed": 1,
    "errors": [
      { "index": 1,
        "code": "invalid_request",
        "message": "This shortcode is already taken.",
        "short_code": "two" }
    ]
  }
}

PATCH 为合并：只修改你发送的字段，其他字段保持当前值。PUT 为替换：你省略的字段都会被清空。接受的字段与创建时相同。

curl -X PATCH https://letl.ink/api/v1/links/49 \
  -H "X-API-KEY: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Spring sale — extended"}'

归档链接：链接将停止解析，并释放一个额度名额，但其点击历史会保留。API 有意不提供永久删除——销毁链接及其历史只能在控制台中经过明确确认后操作。

让已归档的链接重新启用。如果工作区的活跃链接额度已满，则返回 403 plan_required。

单个链接的各次访问，按时间倒序排列。支持 limit 和 offset。所有套餐均包含国家。

整个工作区的核心数据：累计点击和时间范围内的点击、独立访客、二维码扫描、高峰日，以及时段和星期分布。支持 days（默认 30，受数据保留期限制）。

{
  "data": {
    "window_days": 30,
    "clicks": {
      "total": 24592, "window": 8140, "last_7_days": 2103,
      "daily_average": 271,
      "peak_day": { "date": "Sep 02", "clicks": 612 }
    },
    "visitors": { "unique_total": 18204, "unique_window": 6021 },
    "qr": { "scans_total": 940, "scans_window": 310 },
    "timing": {
      "by_hour": [12, 4, 2, …],
      "by_weekday": [1420, 1610, 1585, 1490, 1310, 480, 245],
      "peak_hour": { "peakHour": 14, "peakValue": 812, "label": "14:00–14:59" },
      "peak_weekday": { "peakDay": 1, "peakValue": 1610, "label": "Tuesday" }
    },
    "links": { "active": 42, "limit": 200 }
  },
  "meta": { "plan": "growth", "geo_included": true, "retention_days": 365 }
}

每日点击数，可直接用于绘制图表。传入 link_id 可限定到单个链接，传入 days 可设置时间范围。没有流量的日期会返回 0 而不会被省略，因此序列始终是连续的。

{
  "data": [
    { "date": "Sep 04", "clicks": 22 },
    { "date": "Sep 05", "clicks": 11 }
  ],
  "meta": { "window_days": 7, "total": 33, "link_id": null }
}

按单一维度分组的点击，以及每一行占总数的比例。

查询参数

• dimension string

  channel、referrer、device、browser、os、brand、variation 或 country。browser、os、brand 和 variation 需要提供 link_id。

  必填
• link_id integer

  限定为单个链接。省略则为整个工作区。

  可选
• limit integer

  1–100。默认为 10。

  可选

{
  "data": [
    { "label": "Search", "value": 215, "share": 33.1 },
    { "label": "Social", "value": 201, "share": 30.9 },
    { "label": "Direct / none", "value": 142, "share": 21.8 }
  ],
  "meta": { "dimension": "channel", "link_id": 49, "total": 650 }
}

一次调用即可获取控制台为单个链接显示的全部内容：链接本身、点击总数、独立访客和回访访客、每日序列、小时和星期分布、所有细分数据，以及链接正在运行分流测试时的结果。

"split_test": {
  "active": true,
  "conclusive": true,
  "minClicks": 100,
  "leader": "control",
  "totalClicks": 650,
  "totalVisitors": 172,
  "arms": [
    { "name": "control", "isControl": true, "weight": 2,
      "clicks": 357, "visitors": 60,
      "expectedShare": 50.0, "actualShare": 54.9, "drift": 4.9 },
    { "name": "variant-b", "isControl": false, "weight": 1,
      "clicks": 146, "visitors": 57,
      "expectedShare": 25.0, "actualShare": 22.5, "drift": -2.5 }
  ]
}

工作区中所有链接的原始访问数据流，按时间倒序排列。这是 GET /visits 的现代替代方案：数据相同，采用标准结构，并支持 limit 和 offset。

{
  "data": [
    {
      "id": 2691,
      "link_id": 49,
      "short_code": "spring",
      "occurred_at": "2026-09-10T22:45:33+00:00",
      "ip_address": "203.0.113.7",
      "referrer": "https://twitter.com/",
      "browser": "Chrome",
      "os": "iOS",
      "device_type": "mobile",
      "device_brand": "Apple",
      "country": "US",
      "variation": "control"
    }
  ],
  "meta": { "limit": 50, "returned": 50, "geo_included": true }
}

此账户上注册的 Webhook 端点。

注册一个 HTTPS 端点，在每次记录点击时接收 JSON 数据。每个账户最多 25 个。投递失败会自动重试。

JSON 请求体

• target_url

  必须以 https:// 开头。

  必填
• event

  默认为 link_visited，这是目前唯一的事件。

  可选

curl -X POST https://letl.ink/api/v1/hooks \
  -H "X-API-KEY: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"target_url": "https://example.com/hooks/clicks"}'

移除 Webhook 端点。POST /hooks/subscribe 和 DELETE /hooks/unsubscribe/{id} 仍可用于 Zapier 的 REST Hook 流程。

最初的连接测试：以扁平对象返回你的用户 ID、邮箱以及工作区 ID/名称。GET /me 返回相同的身份信息以及你的套餐限额和功能开关，更适合新代码使用。

curl -H "X-API-KEY: YOUR_TOKEN" \
  https://letl.ink/api/v1/auth/me

{
  "id": 1,
  "email": "[email protected]",
  "workspace_id": 12,
  "workspace_name": "My Workspace"
}

单个链接的点击总数，通过 domain 和 slug 而非 id 定位。两个参数均为必填。如果你知道 id，GET /links/{id} 和 GET /analytics/links/{id} 可提供同样的数据。

查询参数

• domain string

  基础域名或你已验证的某个自定义域名。

  必填
• slug string

  短码，不带前导斜杠。

  必填
• start_date date

  YYYY-MM-DD，受套餐数据保留期限制。

  可选
• end_date date

  YYYY-MM-DD，包含当天。

  可选

整个工作区最近 50 次访问，以纯 JSON 数组形式返回——不带外层结构——使用 visit_id、visit_time、link_shortcode 和 visitor_* 字段名。这是 Zapier REST Hook 的“perform list”步骤读取的内容，因此其结构已冻结。新开发请使用 GET /events。

单个链接最近 50 次访问，以纯数组形式返回，包含 created_at、ip_address、country、 device_type、browser、os 和 referrer。与 /visits 一同冻结；新开发请使用 GET /links/{id}/events。

REST Hook 订阅。接收 target_url 和可选的 event（默认为 link_visited），直接返回创建的订阅，不带外层结构。POST /hooks 是采用标准结构的相同操作。

REST Hook 取消订阅，返回 {"success": true}。DELETE /hooks/{id} 是采用标准结构的等效操作。