Timbrica API

# 1. What can I call?
curl https://timbrica.com/v1/tools

# 2. What will it cost?
curl -X POST https://timbrica.com/v1/tools/dns-lookup/estimate \
  -H "Authorization: Bearer $TIMBRICA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":{"name":"example.com"}}'

# 3. Run it
curl -X POST https://timbrica.com/v1/tools/dns-lookup/runs \
  -H "Authorization: Bearer $TIMBRICA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"input":{"name":"example.com","type":"A"}}'

Always send Idempotency-Key. A retried call then returns the original run instead of charging twice. Networks fail; agents retry. Reusing a key with a different body is a conflict (409), not a silent second answer.

A paid plan is not an API allowance. It discounts the tokens every call spends, and it widens the server-lane ceiling — that is all. API usage is paid per call in tokens on every plan, which is why the browser lane, where the work is yours, is the cheap one. GET /v1/account reports the exact numbers in force for your key.

Files

Media tools take a staged file. Upload bytes, or hand us a URL and we fetch it — useful when a model has a link but not the file.

# upload bytes...
curl -X POST https://timbrica.com/v1/uploads \
  -H "Authorization: Bearer $TIMBRICA_KEY" \
  -F "file=@song.mp3"

# ...or hand us a URL
curl -X POST https://timbrica.com/v1/uploads \
  -H "Authorization: Bearer $TIMBRICA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/song.mp3"}'

# then reference the returned id
{"input":{"audio":{"file_id":"01J…"}}}

Results come back as a link, not inline — a JSON call should not answer with a hundred megabytes. Both inputs and results expire; collect a result before it does.

MCP

The whole catalogue is available as native tools to any MCP client (Claude, Cursor, and others) with one line of configuration — no SDK, no glue code.

{
  "mcpServers": {
    "timbrica": {
      "url": "https://timbrica.com/mcp",
      "headers": { "Authorization": "Bearer $TIMBRICA_KEY" }
    }
  }
}

Money

Check the balance with GET /v1/balance. Read spendable_by_lane, not available: some tokens (welcome grants) do not fund API traffic, so the raw balance can be a true number about the wrong pool.

An agent cannot top itself up — card authentication needs a human. POST /v1/billing/topup_link returns a link to hand to the account owner.

Telling us something is wrong

POST /v1/feedback is the channel back, and it is free — reporting a defect never costs tokens. Our telemetry already records what happened: every run's status, error, price and timing. What it cannot see is a call that returned 200 with a wrong answer, a schema that disagrees with reality, or a tool you need that we do not have.

curl -X POST https://timbrica.com/v1/feedback \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"bug","tool":"ocr","run_id":"01J…",
       "message":"Recognised text is empty for a clean 300-dpi scan.",
       "expected":"the page text","actual":"empty file"}'

type is one of bug, tool_request, docs, other. Everything except type and message is optional.

Rate limit: 20 per hour per key — the scarce resource behind this endpoint is a person reading it, not CPU. Repeat submissions of the same report collapse into one entry, so a retry loop cannot bury the queue.

Tools