API reference
Version 1 of the API reads your organisation's records. This page is made from the list of routes that a test holds to the running API, so a route, filter or field that changes makes the test fail until this page changes too.
Base address
https://track.tooli.dev/api/v1Keys
Every request carries a key in the Authorization header. Owners and admins make keys in Organisation → API; a key is shown once.
Authorization: Bearer tk_live_…A key is tk_live_ and 32 hexadecimal characters. On Tooli Suite's test sites keys start tk_test_. A read-only key is refused on any request that isn't a GET.
Limits
Each key may make 120 requests a minute. Past that, the answer is 429 with Retry-After: 60.
A route answers only while its part of Tooli Suite is switched on for everyone; otherwise it answers 403 with feature_off.
Pages
A list that comes in pages answers with next. Pass it back as cursor, with the same filters, for the page after; on the last page next is null.
Your organisation
GET /api/v1/organization
The key's own organisation: its name, its plan, and what it has used this month against the plan's limits.
Filters
None.
What it answers
| Name | Type | About |
|---|---|---|
name | text | The organisation's name. |
plan | object | Its plan. |
plan.name | text | The plan's name. |
month | text | The month the monthly counts are for, as YYYY-MM, in UTC. |
usage | list | Each limit of the plan, with what is used. |
usage[].key | text | Which limit. One of: emails_month members websites domains documents |
usage[].used | number | How much is used: this month for tracked emails, now for the rest. |
usage[].limit | number or null | The plan's limit; null when there is none. |
Example
curl -H "Authorization: Bearer $TOOLI_API_KEY" \
"https://track.tooli.dev/api/v1/organization"Documents
GET /api/v1/documents
Your hosted documents, newest first, with the figures the Documents page shows. Nobody who viewed one is named.
Needs documents switched on as well.
Filters
| Name | Values | About |
|---|---|---|
q | Any words | Part of a document's name. |
viewed | yes no | yes: viewed at least once. no: never viewed. |
state | archived | archived: archived documents only. Without it, documents that aren't archived. |
limit | 1 to 200; 50 unless said | How many in a page. |
cursor | The next of the page before | Where the next page starts. |
What it answers
| Name | Type | About |
|---|---|---|
rows | list | The documents in this page. |
rows[].code | text | What follows /d/ in its address; the same value a document.viewed webhook carries. |
rows[].url | text | The whole address a reader opens. |
rows[].name | text | Its name. |
rows[].pages | number or null | How many pages; null when they couldn't be counted. |
rows[].size | number | Its size in bytes. |
rows[].version | number | Which file readers get: 1 for the first, one more each time the file is replaced. |
rows[].shared | true or false | Shared with the organisation. |
rows[].downloadsAllowed | true or false | Readers may download it. |
rows[].addedBy | text or null | The name of whoever added it. |
rows[].createdAt | text | When it was added (ISO 8601, UTC). |
rows[].archivedAt | text or null | When it was archived; null if it isn't. |
rows[].views | number | Every time it was opened, a machine's included; your own previews left out. |
rows[].automatedViews | number | The views a machine most likely made. They are in views too. |
rows[].people | number | Different visitors among the views a person most likely made, told apart by device and network. |
rows[].timedViews | number | The views whose time was reported. |
rows[].averageReadSeconds | number or null | What a timed view took on average, in seconds; null while none was timed. |
rows[].furthestPage | number or null | The furthest page anyone had on screen for a second or more. |
rows[].readThrough | number or null | That page as a share of the pages, 0 to 100. |
rows[].downloads | number | How many times it was downloaded. |
rows[].lastViewedAt | text or null | The last view; null if there is none. |
rows[].viewsByDay | list of number | Views on each of the last seven days (UTC), oldest first. |
next | text or null | The cursor for the next page; null on the last. |
total | number | How many documents match, across every page. |
views | number | Their views, together. |
Example
curl -H "Authorization: Bearer $TOOLI_API_KEY" \
"https://track.tooli.dev/api/v1/documents?limit=10"Websites
GET /api/v1/websites
Your websites, busiest in the last 24 hours first. A handful each, so it doesn't come in pages.
Needs websites switched on as well.
Filters
| Name | Values | About |
|---|---|---|
q | Any words | Part of a website's name or address. |
state | receiving none paused | receiving: page views are arriving. none: none yet. paused: page views are refused. |
What it answers
| Name | Type | About |
|---|---|---|
rows | list | The websites. |
rows[].key | text | Its site key, as the snippet carries it. |
rows[].name | text | Its name. |
rows[].origins | list of text | The addresses its page views are taken from. |
rows[].state | text | Whether page views are arriving. One of: receiving none paused |
rows[].pageViews | number | Every page view so far. |
rows[].pageViews24h | number | Page views in the last 24 hours. |
rows[].visitors24h | number | Different visitors in the last 24 hours. |
rows[].lastPageViewAt | text or null | The last page view; null if there is none. |
rows[].addedBy | text or null | The name of whoever added it. |
rows[].createdAt | text | When it was added. |
total | number | How many websites match. |
Example
curl -H "Authorization: Bearer $TOOLI_API_KEY" \
"https://track.tooli.dev/api/v1/websites"Visitors
GET /api/v1/visitors
The people and machines that clicked your links, read your documents or visited your websites, newest seen first. A visitor is named only as the app names one.
Filters
| Name | Values | About |
|---|---|---|
q | Any words | Part of a visitor's name, town, region, network, browser or address. |
named | yes no | yes: named visitors only. no: visitors with no name. |
activity | clicks pages documents | Visitors who clicked a link, viewed a page of a website, or read a document. |
site | A website's site key | Visitors of one website only. |
seen | today 7d 30d | Last seen today, in the last 7 days or in the last 30. |
who | people automated | people: those most likely a person. automated: machines. |
limit | 1 to 100; 50 unless said | How many in a page. |
cursor | The next of the page before | Where the next page starts. |
What it answers
| Name | Type | About |
|---|---|---|
rows | list | The visitors in this page. |
rows[].name | text or null | The visitor's name where the app names them; null otherwise. |
rows[].how | text or null | How sure the name is; null when there is no name. One of: certain probable |
rows[].firstSeenAt | text | When the visitor was first seen. |
rows[].lastSeenAt | text | When the visitor was last seen. |
rows[].clicks | number | Clicks on your links. |
rows[].documentViews | number | Views of your documents. |
rows[].pageViews | number | Page views on your websites. |
rows[].automated | true or false | Most likely a machine. |
rows[].place | object | Where the network they last came from is registered. |
rows[].place.country | text or null | The country, as a two-letter code. |
rows[].place.region | text or null | The region. |
rows[].place.city | text or null | The town or city. |
rows[].place.estimated | true or false | Always true: a place comes from the network, not from the device. |
rows[].network | text or null | The name of the network they last came from. |
rows[].browser | text or null | Their browser, with its version. |
rows[].system | text or null | Their device's system. |
rows[].website | object or null | The website they were last seen on; null if none. |
rows[].website.key | text | Its site key. |
rows[].website.name | text | Its name. |
next | text or null | The cursor for the next page; null on the last. |
total | number | How many visitors match, across every page. |
Example
curl -H "Authorization: Bearer $TOOLI_API_KEY" \
"https://track.tooli.dev/api/v1/visitors?limit=10"Event log
GET /api/v1/events
Every view, click, document view and page view, newest first: those still in the database, then those kept only in the event archive, each marked.
Filters
| Name | Values | About |
|---|---|---|
type | open click doc_view web_hit | open: email views. click: link clicks. doc_view: document views. web_hit: page views. |
limit | 1 to 200; 50 unless said | How many in a page. |
cursor | The next of the page before | Where the next page starts. |
What it answers
| Name | Type | About |
|---|---|---|
rows | list | The events in this page. |
rows[].at | text | When it happened (ISO 8601, UTC). |
rows[].type | text | What kind of event. One of: email_view link_click document_view page_view |
rows[].about | text | What it happened to, by its own name: the email's subject, the short link, the document's name, the website's name. |
rows[].detail | text or null | For a page view, the page's path; for a click, where the link sent it; otherwise null. |
rows[].class | text | What most likely made the request. One of: direct gmail_proxy apple_privacy datacenter vpn bot scanner prefetch sender_preview |
rows[].confidence | number | How sure the class is, 0 to 100. |
rows[].place | object | Where the network it came from is registered. |
rows[].place.country | text or null | The country, as a two-letter code; null where a mail service's proxy asked. |
rows[].place.region | text or null | The region; null where it isn't known. |
rows[].place.city | text or null | The town or city; null where it isn't known. |
rows[].network | text or null | The network's name. |
rows[].ipFamily | number or null | Whether it came over IPv4 or IPv6. One of: 4 6 |
rows[].client | text or null | The user agent the request carried. |
rows[].archived | true or false | Kept only in the event archive now: it left the database after it was copied. |
next | text or null | The cursor for the next page; null on the last. |
Example
curl -H "Authorization: Bearer $TOOLI_API_KEY" \
"https://track.tooli.dev/api/v1/events?limit=10"Errors
A refusal is JSON: {"error": {"code": …, "message": …, "details": …, "requestId": …}}. The code says what kind of refusal it is; the message says why, in words a program can match.
| Code | About |
|---|---|
unauthenticated | No key, or a key that isn't known or no longer works. 401. |
forbidden | The key may not do this: a read-only key writing, or an organisation that is suspended or deleted. 403. |
not_found | No such route or record. 404. |
invalid_request | A filter's value isn't one it takes; message names which (unknown_limit, unknown_state …). 400. |
conflict | The change clashes with what is there now. 409. |
limit_reached | The plan's limit is reached; details says which and how much is used. 403. |
rate_limited | Too many requests this minute: wait as Retry-After says. 429. |
feature_off | That part of Tooli Suite is switched off for now; details.feature names it. 403. |
unavailable | Tooli Suite can't answer just now: try again shortly. 503. |
internal | Something went wrong on Tooli Suite's side; requestId helps us find it. 500. |
Messages the API gives
| Message | About |
|---|---|
api_key_required | There is no key in the Authorization header. |
api_key_invalid | The key isn't known, was revoked, or has been rolled for more than 24 hours. |
read_only_key | A read-only key sent something other than a GET. |
rate_limited | The key made too many requests this minute. |
organisation_suspended | Tooli Suite has suspended the organisation. |
organisation_deleted | The organisation's owner has deleted it. |
Webhook events
A webhook sends each event to your https address as a POST of JSON, signed by the Standard Webhooks convention (webhook-id, webhook-timestamp, webhook-signature).
| Event | About |
|---|---|
email.viewed | A tracked email is viewed. |
link.clicked | A short link is clicked. |
document.viewed | A document is viewed. |
website.visited | A visit to a website begins. |
Your server has 10 seconds to answer with a 2xx. A delivery is tried up to 8 times, waiting 1 min, 5 min, 30 min, 2 h, 5 h, 8 h, 8 h 24 min between tries.