API docs

Quick start

1. Get a key. New purchases are not available right now; existing keys keep working. Buy a credit pack on the pricing page. After payment the confirmation page shows your API key once (it starts with tt_live_); copy it somewhere safe.
2. Send it with every request as Authorization: Bearer tt_live_XXXX to https://tools.yukai.uk/api/v1/<route>. Every route accepts a JSON body (POST) or the same fields as a query string (GET).
3. Read the cost from the response headers x-credits-charged and x-credits-balance.

Your first call

Turn a web page into Markdown (18 credits):

curl

curl -i -X POST "https://tools.yukai.uk/api/v1/markdown" \
  -H "Authorization: Bearer tt_live_XXXX" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'

JavaScript (fetch)

const res = await fetch("https://tools.yukai.uk/api/v1/markdown", {
  method: "POST",
  headers: { "Authorization": "Bearer tt_live_XXXX", "Content-Type": "application/json" },
  body: JSON.stringify({"url":"https://example.com"}),
});
console.log(res.status, res.headers.get("x-credits-charged"), res.headers.get("x-credits-balance"));
console.log(await res.json());

Python (requests)

import requests

r = requests.post(
    "https://tools.yukai.uk/api/v1/markdown",
    headers={"Authorization": "Bearer tt_live_XXXX"},
    json={"url": "https://example.com"},
    timeout=120,
)
print(r.status_code, r.headers.get("x-credits-charged"), r.headers.get("x-credits-balance"))
print(r.json())

Credits on every response

• x-credits-charged: credits this call used (0 for a failed call).
• x-credits-balance: your balance after this call.
• 1 credit = $0.0001. Each route's cost is in the table below and on the pricing page.

Failed calls are free

Before a call runs, its cost is reserved from your balance. If the call fails (any non-2xx answer: invalid input, a blocked or unreachable page, a timeout, an error on our side) nothing is charged and the reserved credits go back at once. Routes that return a list (jobs, reviews, places, batch lookups) reserve a few items and are settled on the number of items actually returned, so the last call of a nearly empty balance can take it slightly below zero; the next purchase covers the difference.

Check your balance

curl -H "Authorization: Bearer tt_live_XXXX" "https://tools.yukai.uk/v1/billing/balance"

Answers {"success": true, "keyPrefix", "mode", "status", "balance", "balanceUsd", "recent": [...]}: the balance in credits and your last 20 calls and purchases. Balance checks are free.

Top up the same key

curl -X POST "https://tools.yukai.uk/v1/billing/checkout" \
  -H "Authorization: Bearer tt_live_XXXX" \
  -H "Content-Type: application/json" \
  -d '{"pack":"pro"}'

Answers a checkoutUrl; after payment the credits are added to the same key. Packs: starter, pro, scale (see pricing).

Errors

Errors share one shape: {"success": false, "error": {"code", "message", "retryable"}}.

• 401 unauthorized: missing, unknown or revoked key.
• 402 insufficient_credits: the balance does not cover the reserve of this call; error.details has balance, required and buyUrl.
• 403 account_suspended: write to tidytools@yukai.uk.
• 404 not_found: the route is not available with a TidyTools key (only the routes below are).
• 400 for invalid input, 5xx with retryable: true for temporary failures. None of them cost credits.

The OpenAPI specs linked below describe each route's fields and responses. Their servers entry is the marketplace gateway; with a TidyTools key, call https://tools.yukai.uk as shown here.

All 41 routes

Questions or a route you need: tidytools@yukai.uk.