Timbrica API

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

# 2. What will it cost?
curl -X POST https://tembrica.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://tembrica.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://tembrica.com/v1/uploads \
  -H "Authorization: Bearer $TIMBRICA_KEY" \
  -F "file=@song.mp3"

# ...or hand us a URL
curl -X POST https://tembrica.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://tembrica.com/mcp",
      "headers": { "Authorization": "Bearer $TIMBRICA_KEY" }
    }
  }
}

Connecting from ChatGPT or Claude

Those two do not take a pasted key: they add a remote MCP server through OAuth. Give them the URL and nothing else — they discover the rest, and send you here to sign in and approve:

https://tembrica.com/mcp

You approve once, on a page that names the app asking and the balance it may spend. Every call it makes afterwards is charged to that balance, the connection is listed in your profile under Settings → API, and ending it there stops the app immediately. A connector token works only against /mcp — it cannot be used on the REST surface, which is why approving one is narrower than handing over a key.

A key in a header remains the way for everything else: your own scripts, an editor, an agent you host. Same catalogue, same wallet, same limits.

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://tembrica.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