API

The API is REST over HTTPS, at your workspace's address. Requests carry an API key as a bearer token; bodies and responses are JSON. The OpenAPI document is at /api/v1/openapi.json, and a generated reference to read at toolaby.app/api/v1/docs.

https://<workspace>.toolaby.app/api/v1

On Test, the base is your workspace's Test address with /test, like https://quiet-otter-4172.toolaby.app/test/api/v1. Configure → API shows yours on each side.

Authentication

Create a key under Configure → API in the dashboard. It is shown once. Test keys (wk_test_…) act on Test's data; live keys (wk_live_…) on Live's.

curl https://northwind.toolaby.app/api/v1/tools/invoice-grabber/customers/maya@example.com \
  -H "Authorization: Bearer wk_live_…"

const res = await fetch('https://northwind.toolaby.app/api/v1/tools/invoice-grabber/customers/maya@example.com', {
  headers: { Authorization: `Bearer ${process.env.TOOLABY_API_KEY}` },
});
const customer = await res.json();

There is no SDK; the API is nine endpoints, called with fetch. A key acts only on tools in its workspace. A tool in another workspace, or one that does not exist, answers 404.

{tool} in a path is either of the tool's ids: the full one, as Tool id on the tool's page shows it (northwind--invoice-grabber), or the short one (invoice-grabber). Responses name the tool by its full id.

Rate limits

600 requests a minute per key and 1,200 per workspace, all its keys together, in the clock's minute (UTC). Above either, 429 with rate_limit_error.

• List customers: 30 pages a minute per workspace, all its keys together. Each page reads the tool's whole list, and the rows it reads count toward the workspace's 300,000 a day, the dashboard's Customers page with them: ask for 500 a page to read a long list in few. See Limits.
• Retrieve a customer: 20,000 a day per workspace, all its keys together, counted before it reads. List grants is a lookup by address too, counted with it. The day is the 24 hours from the first lookup in it. To know every customer, page through the list; to keep up, use webhooks: see Sync customers.
• Uses: each buyer's asks are counted per minute, and their free uses per day, as an extension's are: see Limits.
• Create a grant: 1,000 a day per tool, counted over the last 24 hours, however the grants were made. Past it, the API and the command line refuse. Each grant is also one of the workspace's 20,000 additions a day, counted before it is written: see Limits. Bring more in with the tool's Import page.

Errors

Every error has the shape:

{ "error": { "type": "invalid_request_error", "message": "days: Too big: expected number to be <=3650", "param": "days" } }

Endpoints

List customers

GET /tools/{tool}/customers

Everyone who holds the tool or has signed in to it, newest first: the newest 2,000 of each kind, as in the dashboard. A customer beyond them answers Retrieve a customer.

Returns a page.

{
  "data": [
    { "email": "maya@example.com", "account": true, "entitled": true, "via": "subscription", "since": "2026-09-18T13:33:55.000Z", "last_active_at": "2026-09-20T08:12:01.000Z", "devices": 2 }
  ],
  "has_more": true,
  "next_cursor": "NTA"
}

let cursor = null;
do {
  const url = new URL('https://northwind.toolaby.app/api/v1/tools/invoice-grabber/customers?limit=500');
  if (cursor) url.searchParams.set('cursor', cursor);
  const page = await (await fetch(url, { headers: { Authorization: `Bearer ${key}` } })).json();
  for (const c of page.data) await upsertCustomer(c);
  cursor = page.next_cursor;
} while (cursor);

Retrieve a customer

GET /tools/{tool}/customers/{email}

Whether the address holds the tool now, and how. An address with no account still answers for a licence bought under it. Each lookup is one of the workspace's 20,000 a day: see Rate limits.

Returns a Customer.

{
  "email": "maya@example.com",
  "account": true,
  "entitled": true,
  "via": "subscription",
  "paid_at": "2026-09-18T09:38:35.000Z",
  "plan": { "id": "yearly", "name": "Yearly", "billing": "subscription", "amountCents": 2900, "currency": "eur", "interval": "year" },
  "subscription": { "status": "active", "periodEnd": "2027-09-18T09:38:35.000Z", "cancelAtPeriodEnd": false, "cancelAt": null },
  "trial": null
}

List grants

GET /tools/{tool}/grants?email={email}

The address's grants and trials for the tool, newest first, up to 100.

Returns { "data": [Grant, …] }.

Create a grant

POST /tools/{tool}/grants

Grants access without payment. An unknown address gets an account; the grant applies when they sign in. The extension unlocks at its next check.

curl -X POST https://northwind.toolaby.app/api/v1/tools/invoice-grabber/grants \
  -H "Authorization: Bearer wk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "email": "maya@example.com", "days": 30, "note": "Beta tester" }'

const grant = await (await fetch('https://northwind.toolaby.app/api/v1/tools/invoice-grabber/grants', {
  method: 'POST',
  headers: { Authorization: `Bearer ${key}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ email: 'maya@example.com', days: 30, note: 'Beta tester' }),
})).json();

Returns the Grant with status 201. On Hobby, a grant made at the same moment as others can pass the 100 passes: it is made and held, with live: false.

Revoke a grant

DELETE /tools/{tool}/grants/{id}

Ends the grant. The extension stops at its next check, within 15 minutes. Revoking twice succeeds.

Returns { "id", "tool", "revoked_at", "live": false }.

Retrieve a buyer's uses

GET /tools/{tool}/uses

What the signed-in buyer a site token names holds of the tool, and how many of its free uses are left, counting nothing: for your page to say before the first use. Your server sends its key, and the buyer's site token: Toolaby.token({ tool }) on your page, or toolaby.siteToken({ audience }) in your extension (Your server).

Returns a Usage.

Count a buyer's uses

POST /tools/{tool}/uses

Counts count of the buyer's uses, for an action your server does for them. It is allowed and counted, or refused whole, with why (reason) and what remains: a refusal is an answer, 200 with allowed: false, not an error. A buyer who holds the tool, or a tool open to everyone, counts nothing.

curl https://northwind.toolaby.app/api/v1/tools/invoice-grabber/uses \
  -H "Authorization: Bearer wk_live_…" \
  -H "Toolaby-Site-Token: $SITE_TOKEN" \
  -H "Idempotency-Key: $ACTION_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "count": 3 }'

Returns a Usage.

{ "object": "usage", "allowed": true, "entitled": false, "used": 3, "remaining": 7, "limit": 10, "per": "ever" }

Analytics summary

GET /tools/{tool}/analytics?range={range}

The figures of the tool's Analytics Overview for the period: devices active today, in 7 days and in 30 days, new devices; the funnel from a new device to a purchase, which leaves out the devices that have the tool another way and counts them in has_access_elsewhere; what was paid and refunded in each currency, with monthly recurring revenue; and uninstalls. Analytics in the API is on Pro (Analytics).

Returns an AnalyticsSummary. A part the plan does not hold is null; parts says what each part is to your workspace.

{
  "tool": "northwind--invoice-grabber",
  "range": { "id": "30d", "from": "2026-09-17", "to": "2026-10-16", "days": 30, "clamped": false },
  "counting": true,
  "parts": { "overview": "open", "revenue": "open", "devices": "open", "funnel": "open", "features": "open", "uninstalls": "open", "versions": "open", "experiments": "off", "export": "open", "history": "open" },
  "devices": { "active": 1163, "active_7_days": 2775, "active_30_days": 5202, "new": 3401 },
  "funnel": { "new_devices": 3363, "met_paywall": 742, "opened_checkout": 210, "paid": 99, "median_days_to_paid": 2, "has_access_elsewhere": 38 },
  "revenue": [{ "currency": "eur", "purchased": 412300, "renewed": 25100, "refunded": 0, "net": 437400, "mrr": 26400, "subscriptions": 88 }],
  "uninstalls": { "removed": 234, "paying": 3, "answered": 141, "median_days_kept": 9 }
}

Analytics table

GET /tools/{tool}/analytics/{table}?range={range}

One table of the tool's Analytics as rows, the CSV file's own: each row an object keyed by its columns. A table is open where its part is.

Returns { "part", "range", "channel", "data": [ … ] }.

{
  "part": "features",
  "range": { "id": "30d", "from": "2026-09-17", "to": "2026-10-16", "days": 30, "clamped": false },
  "data": [
    { "opened_by": "_limit", "paywall_opens": 6512, "checkouts": 98, "purchases": 72, "currency": "eur", "revenue": 216000 },
    { "opened_by": "export", "paywall_opens": 1349, "checkouts": 21, "purchases": 15, "currency": "eur", "revenue": 45000 }
  ]
}

Money is in minor units of currency. Days are UTC dates.

Objects

CustomerListItem

Customer

Grant

Usage

Dates are ISO 8601 strings.