API 参考
第 1 版 API 用于读取您组织的记录。本页根据路由列表生成,而这份列表由一项测试与正在运行的 API 逐一核对:只要路由、筛选条件或字段发生变化,测试就会失败,直到本页随之更新。
基础地址
https://track.tooli.dev/api/v1密钥
每次请求都在 Authorization 请求头中带上密钥。所有者和管理员在“组织 → API”中创建密钥;密钥只显示一次。
Authorization: Bearer tk_live_…密钥由 tk_live_ 加 32 个十六进制字符组成。在 Tooli Suite 的测试站点上,密钥以 tk_test_ 开头。只读密钥发出的非 GET 请求都会被拒绝。
限制
每个密钥每分钟可以发出 120 个请求。超出后,应答为 429,并带有 Retry-After: 60。
只有当 Tooli Suite 的相应部分对所有人开启时,路由才会应答;否则应答为 403,代码为 feature_off。
分页
分页返回的列表会带有 next。把它作为 cursor 传回,并使用相同的筛选条件,即可获取下一页;最后一页的 next 为 null。
您的组织
GET /api/v1/organization
密钥所属的组织:名称、套餐,以及本月相对于套餐限制的用量。
筛选条件
无。
应答内容
| 名称 | 类型 | 说明 |
|---|---|---|
name | 文本 | 组织的名称。 |
plan | 对象 | 组织的套餐。 |
plan.name | 文本 | 套餐的名称。 |
month | 文本 | 月度计数所属的月份,格式为 YYYY-MM,按 UTC 计算。 |
usage | 列表 | 套餐的每项限制及其用量。 |
usage[].key | 文本 | 哪一项限制。 可取值: emails_month members websites domains documents |
usage[].used | 数字 | 已用量:已跟踪的邮件按本月计算,其余按当前数量计算。 |
usage[].limit | 数字 或 null | 套餐的限制;没有限制时为 null。 |
示例
curl -H "Authorization: Bearer $TOOLI_API_KEY" \
"https://track.tooli.dev/api/v1/organization"文档
GET /api/v1/documents
您托管的文档,按从新到旧排列,附带文档页面显示的数字。不会点名任何查看者。
还需要开启 documents。
筛选条件
| 名称 | 取值 | 说明 |
|---|---|---|
q | 任意文字 | 文档名称的一部分。 |
viewed | yes no | yes:至少被查看过一次。no:从未被查看。 |
state | archived | archived:只看已归档的文档。不指定时,返回未归档的文档。 |
limit | 1 到 200; 未指定时为 50 | 每页的数量。 |
cursor | 上一页的 next | 下一页从哪里开始。 |
应答内容
| 名称 | 类型 | 说明 |
|---|---|---|
rows | 列表 | 本页中的文档。 |
rows[].code | 文本 | 地址中 /d/ 之后的部分;与 document.viewed Webhook 中的值相同。 |
rows[].url | 文本 | 读者打开的完整地址。 |
rows[].name | 文本 | 文档名称。 |
rows[].pages | 数字 或 null | 页数;无法统计时为 null。 |
rows[].size | 数字 | 大小,以字节为单位。 |
rows[].version | 数字 | 读者看到的是哪个文件:第一个为 1,每替换一次文件加 1。 |
rows[].shared | true 或 false | 是否已与组织共享。 |
rows[].downloadsAllowed | true 或 false | 读者是否可以下载。 |
rows[].addedBy | 文本 或 null | 添加者的名称。 |
rows[].createdAt | 文本 | 添加时间(ISO 8601,UTC)。 |
rows[].archivedAt | 文本 或 null | 归档时间;未归档时为 null。 |
rows[].views | 数字 | 被打开的每一次,包括机器的查看;不包括您自己的预览。 |
rows[].automatedViews | 数字 | 最可能由机器产生的查看。它们也包含在 views 中。 |
rows[].people | 数字 | 最可能由真人产生的查看中的不同访客,按设备和网络区分。 |
rows[].timedViews | 数字 | 报告了时长的查看次数。 |
rows[].averageReadSeconds | 数字 或 null | 计时查看的平均时长,以秒为单位;还没有计时查看时为 null。 |
rows[].furthestPage | 数字 或 null | 有人在屏幕上停留至少一秒的最后一页。 |
rows[].readThrough | 数字 或 null | 这一页占总页数的比例,0 到 100。 |
rows[].downloads | 数字 | 被下载的次数。 |
rows[].lastViewedAt | 文本 或 null | 最近一次查看;没有查看时为 null。 |
rows[].viewsByDay | 数字列表 | 最近七天(UTC)每天的查看次数,从早到晚排列。 |
next | 文本 或 null | 下一页的游标;最后一页为 null。 |
total | 数字 | 所有页面中符合条件的文档数量。 |
views | 数字 | 这些文档的查看次数之和。 |
示例
curl -H "Authorization: Bearer $TOOLI_API_KEY" \
"https://track.tooli.dev/api/v1/documents?limit=10"网站
GET /api/v1/websites
您的网站,按最近 24 小时的访问量从高到低排列。每个组织只有几个,因此不分页。
还需要开启 websites。
筛选条件
| 名称 | 取值 | 说明 |
|---|---|---|
q | 任意文字 | 网站名称或地址的一部分。 |
state | receiving none paused | receiving:正在接收页面浏览。none:尚无数据。paused:页面浏览被拒绝。 |
应答内容
| 名称 | 类型 | 说明 |
|---|---|---|
rows | 列表 | 网站列表。 |
rows[].key | 文本 | 站点密钥,与代码片段中的相同。 |
rows[].name | 文本 | 网站名称。 |
rows[].origins | 文本列表 | 记录页面浏览的地址。 |
rows[].state | 文本 | 是否正在接收页面浏览。 可取值: receiving none paused |
rows[].pageViews | 数字 | 到目前为止的所有页面浏览。 |
rows[].pageViews24h | 数字 | 最近 24 小时的页面浏览。 |
rows[].visitors24h | 数字 | 最近 24 小时的不同访客。 |
rows[].lastPageViewAt | 文本 或 null | 最近一次页面浏览;没有时为 null。 |
rows[].addedBy | 文本 或 null | 添加者的名称。 |
rows[].createdAt | 文本 | 添加时间。 |
total | 数字 | 符合条件的网站数量。 |
示例
curl -H "Authorization: Bearer $TOOLI_API_KEY" \
"https://track.tooli.dev/api/v1/websites"访客
GET /api/v1/visitors
点击过您的链接、阅读过您的文档或访问过您网站的真人和机器,按最近出现的时间排列。访客只会像在应用中那样被点名。
筛选条件
| 名称 | 取值 | 说明 |
|---|---|---|
q | 任意文字 | 访客的名称、城市、地区、网络、浏览器或地址的一部分。 |
named | yes no | yes:只看已点名的访客。no:没有名称的访客。 |
activity | clicks pages documents | 点击过链接、浏览过网站页面或阅读过文档的访客。 |
site | 网站的站点密钥 | 只看某一个网站的访客。 |
seen | today 7d 30d | 最近一次出现在今天、最近 7 天内或最近 30 天内。 |
who | people automated | people:最可能是真人。automated:机器。 |
limit | 1 到 100; 未指定时为 50 | 每页的数量。 |
cursor | 上一页的 next | 下一页从哪里开始。 |
应答内容
| 名称 | 类型 | 说明 |
|---|---|---|
rows | 列表 | 本页中的访客。 |
rows[].name | 文本 或 null | 应用为访客显示的名称;否则为 null。 |
rows[].how | 文本 或 null | 名称的确定程度;没有名称时为 null。 可取值: certain probable |
rows[].firstSeenAt | 文本 | 第一次出现的时间。 |
rows[].lastSeenAt | 文本 | 最近一次出现的时间。 |
rows[].clicks | 数字 | 对您链接的点击。 |
rows[].documentViews | 数字 | 对您文档的查看。 |
rows[].pageViews | 数字 | 在您网站上的页面浏览。 |
rows[].automated | true 或 false | 最可能是机器。 |
rows[].place | 对象 | 访客最近一次所来自网络的登记位置。 |
rows[].place.country | 文本 或 null | 国家,两个字母的代码。 |
rows[].place.region | 文本 或 null | 地区。 |
rows[].place.city | 文本 或 null | 城市或城镇。 |
rows[].place.estimated | true 或 false | 始终为 true:位置来自网络,而不是设备。 |
rows[].network | 文本 或 null | 访客最近一次所来自网络的名称。 |
rows[].browser | 文本 或 null | 浏览器及其版本。 |
rows[].system | 文本 或 null | 设备的系统。 |
rows[].website | 对象 或 null | 访客最近一次出现的网站;没有时为 null。 |
rows[].website.key | 文本 | 站点密钥。 |
rows[].website.name | 文本 | 网站名称。 |
next | 文本 或 null | 下一页的游标;最后一页为 null。 |
total | 数字 | 所有页面中符合条件的访客数量。 |
示例
curl -H "Authorization: Bearer $TOOLI_API_KEY" \
"https://track.tooli.dev/api/v1/visitors?limit=10"事件记录
GET /api/v1/events
每一次查看、点击、文档查看和页面浏览,按从新到旧排列:先是仍在数据库中的事件,然后是只保存在事件归档中的事件,并分别标出。
筛选条件
| 名称 | 取值 | 说明 |
|---|---|---|
type | open click doc_view web_hit | open:邮件查看。click:链接点击。doc_view:文档查看。web_hit:页面浏览。 |
limit | 1 到 200; 未指定时为 50 | 每页的数量。 |
cursor | 上一页的 next | 下一页从哪里开始。 |
应答内容
| 名称 | 类型 | 说明 |
|---|---|---|
rows | 列表 | 本页中的事件。 |
rows[].at | 文本 | 发生时间(ISO 8601,UTC)。 |
rows[].type | 文本 | 事件的种类。 可取值: email_view link_click document_view page_view |
rows[].about | 文本 | 事件针对的对象,使用它自己的名称:邮件主题、短链接、文档名称或网站名称。 |
rows[].detail | 文本 或 null | 页面浏览时为页面路径;点击时为链接指向的地址;其他情况为 null。 |
rows[].class | 文本 | 最可能是什么发出了请求。 可取值: direct gmail_proxy apple_privacy datacenter vpn bot scanner prefetch sender_preview |
rows[].confidence | 数字 | 类别的把握程度,0 到 100。 |
rows[].place | 对象 | 请求所来自网络的登记位置。 |
rows[].place.country | 文本 或 null | 国家,两个字母的代码;由邮件服务代理请求时为 null。 |
rows[].place.region | 文本 或 null | 地区;未知时为 null。 |
rows[].place.city | 文本 或 null | 城市或城镇;未知时为 null。 |
rows[].network | 文本 或 null | 网络的名称。 |
rows[].ipFamily | 数字 或 null | 通过 IPv4 还是 IPv6 到达。 可取值: 4 6 |
rows[].client | 文本 或 null | 请求携带的用户代理。 |
rows[].archived | true 或 false | 现在只保存在事件归档中:复制后已从数据库移出。 |
next | 文本 或 null | 下一页的游标;最后一页为 null。 |
示例
curl -H "Authorization: Bearer $TOOLI_API_KEY" \
"https://track.tooli.dev/api/v1/events?limit=10"错误
拒绝时返回 JSON:{"error": {"code": …, "message": …, "details": …, "requestId": …}}。代码说明是哪一类拒绝;消息用程序可以匹配的文字说明原因。
| 代码 | 说明 |
|---|---|
unauthenticated | 没有密钥,或者密钥未知、已失效。401。 |
forbidden | 密钥不能执行此操作:只读密钥尝试写入,或者组织已被暂停或删除。403。 |
not_found | 没有这个路由或记录。404。 |
invalid_request | 筛选条件的值不被接受;message 会指出是哪一个(unknown_limit、unknown_state …)。400。 |
conflict | 更改与当前内容冲突。409。 |
limit_reached | 已达到套餐的限制;details 说明是哪一项以及已用多少。403。 |
rate_limited | 本分钟的请求太多:按 Retry-After 的说明等待。429。 |
feature_off | Tooli Suite 的这一部分暂时关闭;details.feature 会指出是哪一部分。403。 |
unavailable | Tooli Suite 暂时无法应答:请稍后再试。503。 |
internal | Tooli Suite 这边出了问题;requestId 能帮助我们查找原因。500。 |
API 给出的消息
| 消息 | 说明 |
|---|---|
api_key_required | Authorization 请求头中没有密钥。 |
api_key_invalid | 密钥未知、已被撤销,或者轮换已超过 24 小时。 |
read_only_key | 只读密钥发出了 GET 以外的请求。 |
rate_limited | 该密钥本分钟发出的请求太多。 |
organisation_suspended | Tooli Suite 已暂停该组织。 |
organisation_deleted | 该组织的所有者已将其删除。 |
Webhook 事件
Webhook 以 JSON 的 POST 请求把每个事件发送到您的 https 地址,并按 Standard Webhooks 规范签名(webhook-id、webhook-timestamp、webhook-signature)。
| 事件 | 说明 |
|---|---|
email.viewed | 已跟踪的邮件被查看。 |
link.clicked | 短链接被点击。 |
document.viewed | 文档被查看。 |
website.visited | 网站的一次访问开始。 |
您的服务器需要在 10 秒内返回 2xx。每次投递最多尝试 8 次,两次尝试之间依次等待 1 分钟、5 分钟、30 分钟、2 小时、5 小时、8 小时、8 小时 24 分钟。