Tooli SuiteSign in

Draft for the owner's approval. Not published, and kept out of search engines.

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/v1

Keys

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

NameTypeAbout
nametextThe organisation's name.
planobjectIts plan.
plan.nametextThe plan's name.
monthtextThe month the monthly counts are for, as YYYY-MM, in UTC.
usagelistEach limit of the plan, with what is used.
usage[].keytextWhich limit. One of: emails_month members websites domains documents
usage[].usednumberHow much is used: this month for tracked emails, now for the rest.
usage[].limitnumber or nullThe 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

NameValuesAbout
qAny wordsPart of a document's name.
viewedyes noyes: viewed at least once. no: never viewed.
statearchivedarchived: archived documents only. Without it, documents that aren't archived.
limit1 to 200; 50 unless saidHow many in a page.
cursorThe next of the page beforeWhere the next page starts.

What it answers

NameTypeAbout
rowslistThe documents in this page.
rows[].codetextWhat follows /d/ in its address; the same value a document.viewed webhook carries.
rows[].urltextThe whole address a reader opens.
rows[].nametextIts name.
rows[].pagesnumber or nullHow many pages; null when they couldn't be counted.
rows[].sizenumberIts size in bytes.
rows[].versionnumberWhich file readers get: 1 for the first, one more each time the file is replaced.
rows[].sharedtrue or falseShared with the organisation.
rows[].downloadsAllowedtrue or falseReaders may download it.
rows[].addedBytext or nullThe name of whoever added it.
rows[].createdAttextWhen it was added (ISO 8601, UTC).
rows[].archivedAttext or nullWhen it was archived; null if it isn't.
rows[].viewsnumberEvery time it was opened, a machine's included; your own previews left out.
rows[].automatedViewsnumberThe views a machine most likely made. They are in views too.
rows[].peoplenumberDifferent visitors among the views a person most likely made, told apart by device and network.
rows[].timedViewsnumberThe views whose time was reported.
rows[].averageReadSecondsnumber or nullWhat a timed view took on average, in seconds; null while none was timed.
rows[].furthestPagenumber or nullThe furthest page anyone had on screen for a second or more.
rows[].readThroughnumber or nullThat page as a share of the pages, 0 to 100.
rows[].downloadsnumberHow many times it was downloaded.
rows[].lastViewedAttext or nullThe last view; null if there is none.
rows[].viewsByDaylist of numberViews on each of the last seven days (UTC), oldest first.
nexttext or nullThe cursor for the next page; null on the last.
totalnumberHow many documents match, across every page.
viewsnumberTheir 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

NameValuesAbout
qAny wordsPart of a website's name or address.
statereceiving none pausedreceiving: page views are arriving. none: none yet. paused: page views are refused.

What it answers

NameTypeAbout
rowslistThe websites.
rows[].keytextIts site key, as the snippet carries it.
rows[].nametextIts name.
rows[].originslist of textThe addresses its page views are taken from.
rows[].statetextWhether page views are arriving. One of: receiving none paused
rows[].pageViewsnumberEvery page view so far.
rows[].pageViews24hnumberPage views in the last 24 hours.
rows[].visitors24hnumberDifferent visitors in the last 24 hours.
rows[].lastPageViewAttext or nullThe last page view; null if there is none.
rows[].addedBytext or nullThe name of whoever added it.
rows[].createdAttextWhen it was added.
totalnumberHow 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

NameValuesAbout
qAny wordsPart of a visitor's name, town, region, network, browser or address.
namedyes noyes: named visitors only. no: visitors with no name.
activityclicks pages documentsVisitors who clicked a link, viewed a page of a website, or read a document.
siteA website's site keyVisitors of one website only.
seentoday 7d 30dLast seen today, in the last 7 days or in the last 30.
whopeople automatedpeople: those most likely a person. automated: machines.
limit1 to 100; 50 unless saidHow many in a page.
cursorThe next of the page beforeWhere the next page starts.

What it answers

NameTypeAbout
rowslistThe visitors in this page.
rows[].nametext or nullThe visitor's name where the app names them; null otherwise.
rows[].howtext or nullHow sure the name is; null when there is no name. One of: certain probable
rows[].firstSeenAttextWhen the visitor was first seen.
rows[].lastSeenAttextWhen the visitor was last seen.
rows[].clicksnumberClicks on your links.
rows[].documentViewsnumberViews of your documents.
rows[].pageViewsnumberPage views on your websites.
rows[].automatedtrue or falseMost likely a machine.
rows[].placeobjectWhere the network they last came from is registered.
rows[].place.countrytext or nullThe country, as a two-letter code.
rows[].place.regiontext or nullThe region.
rows[].place.citytext or nullThe town or city.
rows[].place.estimatedtrue or falseAlways true: a place comes from the network, not from the device.
rows[].networktext or nullThe name of the network they last came from.
rows[].browsertext or nullTheir browser, with its version.
rows[].systemtext or nullTheir device's system.
rows[].websiteobject or nullThe website they were last seen on; null if none.
rows[].website.keytextIts site key.
rows[].website.nametextIts name.
nexttext or nullThe cursor for the next page; null on the last.
totalnumberHow 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

NameValuesAbout
typeopen click doc_view web_hitopen: email views. click: link clicks. doc_view: document views. web_hit: page views.
limit1 to 200; 50 unless saidHow many in a page.
cursorThe next of the page beforeWhere the next page starts.

What it answers

NameTypeAbout
rowslistThe events in this page.
rows[].attextWhen it happened (ISO 8601, UTC).
rows[].typetextWhat kind of event. One of: email_view link_click document_view page_view
rows[].abouttextWhat it happened to, by its own name: the email's subject, the short link, the document's name, the website's name.
rows[].detailtext or nullFor a page view, the page's path; for a click, where the link sent it; otherwise null.
rows[].classtextWhat most likely made the request. One of: direct gmail_proxy apple_privacy datacenter vpn bot scanner prefetch sender_preview
rows[].confidencenumberHow sure the class is, 0 to 100.
rows[].placeobjectWhere the network it came from is registered.
rows[].place.countrytext or nullThe country, as a two-letter code; null where a mail service's proxy asked.
rows[].place.regiontext or nullThe region; null where it isn't known.
rows[].place.citytext or nullThe town or city; null where it isn't known.
rows[].networktext or nullThe network's name.
rows[].ipFamilynumber or nullWhether it came over IPv4 or IPv6. One of: 4 6
rows[].clienttext or nullThe user agent the request carried.
rows[].archivedtrue or falseKept only in the event archive now: it left the database after it was copied.
nexttext or nullThe 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.

CodeAbout
unauthenticatedNo key, or a key that isn't known or no longer works. 401.
forbiddenThe key may not do this: a read-only key writing, or an organisation that is suspended or deleted. 403.
not_foundNo such route or record. 404.
invalid_requestA filter's value isn't one it takes; message names which (unknown_limit, unknown_state …). 400.
conflictThe change clashes with what is there now. 409.
limit_reachedThe plan's limit is reached; details says which and how much is used. 403.
rate_limitedToo many requests this minute: wait as Retry-After says. 429.
feature_offThat part of Tooli Suite is switched off for now; details.feature names it. 403.
unavailableTooli Suite can't answer just now: try again shortly. 503.
internalSomething went wrong on Tooli Suite's side; requestId helps us find it. 500.

Messages the API gives

MessageAbout
api_key_requiredThere is no key in the Authorization header.
api_key_invalidThe key isn't known, was revoked, or has been rolled for more than 24 hours.
read_only_keyA read-only key sent something other than a GET.
rate_limitedThe key made too many requests this minute.
organisation_suspendedTooli Suite has suspended the organisation.
organisation_deletedThe 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).

EventAbout
email.viewedA tracked email is viewed.
link.clickedA short link is clicked.
document.viewedA document is viewed.
website.visitedA 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.