Tooli Suite登录

草稿,等待所有者审核。尚未发布,也不会被搜索引擎收录。

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任意文字文档名称的一部分。
viewedyes noyes:至少被查看过一次。no:从未被查看。
statearchivedarchived:只看已归档的文档。不指定时,返回未归档的文档。
limit1 到 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[].sharedtrue 或 false是否已与组织共享。
rows[].downloadsAllowedtrue 或 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任意文字网站名称或地址的一部分。
statereceiving none pausedreceiving:正在接收页面浏览。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任意文字访客的名称、城市、地区、网络、浏览器或地址的一部分。
namedyes noyes:只看已点名的访客。no:没有名称的访客。
activityclicks pages documents点击过链接、浏览过网站页面或阅读过文档的访客。
site网站的站点密钥只看某一个网站的访客。
seentoday 7d 30d最近一次出现在今天、最近 7 天内或最近 30 天内。
whopeople automatedpeople:最可能是真人。automated:机器。
limit1 到 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[].automatedtrue 或 false最可能是机器。
rows[].place对象访客最近一次所来自网络的登记位置。
rows[].place.country文本 或 null国家,两个字母的代码。
rows[].place.region文本 或 null地区。
rows[].place.city文本 或 null城市或城镇。
rows[].place.estimatedtrue 或 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

每一次查看、点击、文档查看和页面浏览,按从新到旧排列:先是仍在数据库中的事件,然后是只保存在事件归档中的事件,并分别标出。

筛选条件

名称取值说明
typeopen click doc_view web_hitopen:邮件查看。click:链接点击。doc_view:文档查看。web_hit:页面浏览。
limit1 到 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[].archivedtrue 或 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_offTooli Suite 的这一部分暂时关闭;details.feature 会指出是哪一部分。403。
unavailableTooli Suite 暂时无法应答:请稍后再试。503。
internalTooli Suite 这边出了问题;requestId 能帮助我们查找原因。500。

API 给出的消息

消息说明
api_key_requiredAuthorization 请求头中没有密钥。
api_key_invalid密钥未知、已被撤销,或者轮换已超过 24 小时。
read_only_key只读密钥发出了 GET 以外的请求。
rate_limited该密钥本分钟发出的请求太多。
organisation_suspendedTooli 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 分钟。