Triremes API

Search the problems and the website visibility gaps, and buy leads, idea reports and websites from your own code. The API shows what their pages show, plus each one's price and whether you own it; what you buy comes back in the answer, exactly as its page shows it.

Access and prices

$250 a month for API access, billed by card through Stripe until you cancel. Subscribe on your account's API page, where you also make your keys.
Purchases are paid from prepaid credits, bought on the same page in packs of $100, $250 and $500. A purchase costs what it costs on the site: a lead $19 for each business found, at least $19; an idea report its tier's price; a website's visibility gaps $99. Each problem's price (price_cents) and its businesses are in the API's answers. Credits never expire and are not refunded in cash.
At most 60 requests a minute per key, and at most $500 of purchases per account in a day (UTC).
From one address, at most 120 requests a minute with or without a key, and 10 a minute with a key that is not valid; past either, that address waits out the minute.

Keys

Send your key with every request, in the Authorization header. A key is shown once, when you make it; keep it secret, and revoke it on your account's API page if it leaks. Keys work only while your subscription is active.

Authorization: Bearer trm_live_...

Endpoints

All under https://triremes.com/api/v1, all JSON. The full description is openapi.json (OpenAPI 3.1).

Search problems

GET /problems, 25 at a time (limit, up to 100). Filters: q (words in the title or the summary), tier (A, B or C), has_businesses (true: leads; false: idea reports), since (first seen on or after a date). The next page is cursor= the answer's next_cursor, null on the last page.

curl -s "https://triremes.com/api/v1/problems?tier=A&has_businesses=true&limit=10" \
  -H "Authorization: Bearer $TRIREMES_KEY"

Each problem has its slug, name, tier, kind (what it sells: lead or idea), businesses, reports, summary, price_cents and already_owned.

One problem

GET /problems/{slug}: as its page shows it, with a lead's reports and related problems.

curl -s "https://triremes.com/api/v1/problems/inventory-sync-drops-orders-0a1b2c3d4e" \
  -H "Authorization: Bearer $TRIREMES_KEY"

Website visibility gaps

GET /website-gaps: the websites on sale, 25 at a time (limit, up to 50), each as its page shows it before it is bought: its id, title, category (what the business does), region, city, country, its gaps by name, measured_at, price_cents and already_owned; never which business it is. Filters: category (a business category, a NAICS title or a NAICS code), region, city, country and since (measured on or after a date); the next page is cursor= the answer's next_cursor. GET /website-gaps/{id} is one website.

curl -s "https://triremes.com/api/v1/website-gaps?category=dentists&region=TX" \
  -H "Authorization: Bearer $TRIREMES_KEY"

Buy

POST /purchases with the problem's slug and what it sells, or a website's id and website_gaps. Credit is spent and the purchase made in one step; send an Idempotency-Key so a retried request never buys twice. Buying what you already own, through the API or on the site, returns it at no charge.

curl -s -X POST "https://triremes.com/api/v1/purchases" \
  -H "Authorization: Bearer $TRIREMES_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"item": "inventory-sync-drops-orders-0a1b2c3d4e", "kind": "lead"}'

curl -s -X POST "https://triremes.com/api/v1/purchases" \
  -H "Authorization: Bearer $TRIREMES_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"item": "site-17", "kind": "website_gaps"}'

The answer is 201 when credit was spent, 200 when it was not, and holds the purchase's content: a lead's businesses (business, email, the page it was published on), the idea report, or a website's sites (the business, its website, its contact page, and each finding as measured on its date).

Your purchases and balance

GET /purchases lists everything bought with your account's address, through the API or on the site; GET /purchases/{id} fetches one again with its content; GET /balance is your credit, today's spending and your subscription.

curl -s "https://triremes.com/api/v1/balance" -H "Authorization: Bearer $TRIREMES_KEY"

Errors

Every error is {"error": {"code": "...", "message": "..."}}.

Status	Code	Means
400	`invalid_parameter`, `invalid_json`	The request is not as described: a parameter that is not one, a value of the wrong form, or a body other than exactly `{"item", "kind"}`.
415	`unsupported_media_type`	A purchase's body is not sent as `Content-Type: application/json`.
401	`invalid_key`	No key, or one not valid or revoked.
402	`insufficient_credit`	Not enough credit: buy more on your account's API page.
403	`subscription_inactive`	The subscription is not active.
404	`not_found`	No such problem, website, purchase or endpoint.
409	`kind_unavailable`, `idempotency_key_reused`	The problem sells the other kind now; or the key was used for another purchase.
410	`gone`	The problem is no longer listed.
429	`rate_limited`, `daily_spend_cap`	Wait the seconds in `Retry-After`.

API terms

The terms for buyers apply to everything bought through the API.
Contacts and reports you buy are for your own use. You may not resell, republish, share or sublicense them, or the API's answers, in whole or in part.
Use the contacts lawfully, and only as the terms for buyers allow.
Keep your keys secret. You are responsible for every request made with them; revoke a key you think has leaked.
Stay within the rate limit and the daily spend cap, and do not try to get around them.
The subscription is billed monthly until you cancel; cancelling ends it when the month paid for ends. All purchases are final. Credits never expire and are not refunded in cash, except where we decide to.
We may suspend a key or an account that breaks these terms, and may change prices or these terms with notice on this page.