UtilNest API for developers

The UtilNest API gives Pro accounts the engines behind the site over HTTPS: every calculator, unit converter and reference table, document and ebook conversions, cloud transcription, HD background removal and upscaling, and the AI text and image tools. Calls cost exactly what the same action costs on the site, and use the same plan limits and credits.

Keys

Create a key on your account page (Pro plan). It looks like un_live_…, is shown once, and is stored by us only as a hash; revoke it there at any time. A key works while the account is on Pro and stops when it isn't. Send it as a bearer token:

curl https://api.utilnest.io/v1/me -H "Authorization: Bearer $UTILNEST_KEY"

Keep keys on your server; don't put them in web pages or apps you ship.

Calculators, converters and tables

GET /v1/utilities lists the utilities you can run, with their fields and defaults. POST /v1/run/{utility} runs one with a JSON body; fields you leave out take their default. These calls use no credits.

curl https://api.utilnest.io/v1/run/units.length.miles-to-km \
  -H "Authorization: Bearer $UTILNEST_KEY" -H "Content-Type: application/json" \
  -d '{"value": 26.2}'
# {"utility":"units.length.miles-to-km","result":42.1648128}

curl https://api.utilnest.io/v1/run/calculators.finance.compound-interest \
  -H "Authorization: Bearer $UTILNEST_KEY" -H "Content-Type: application/json" \
  -d '{"principal": 10000, "rate": 5, "years": 10, "monthly": 0}'

Each utility's input schema is in the OpenAPI 3.1 document, generated from the same registry as the site.

Document and ebook jobs

The flow the site uses: create an upload, send the bytes to the link you get, start a job, then download the result. Pro limits apply (file size, upload windows, jobs a day, how long results are kept).

# 1. Upload (small files get one PUT link; large ones are multipart)
curl https://api.utilnest.io/v1/uploads -H "Authorization: Bearer $UTILNEST_KEY" \
  -H "Content-Type: application/json" -d '{"name": "contract.pdf", "size": 182044}'
# {"fileId":"…","method":"put","url":"https://…","headers":{"content-type":"application/pdf"}}
curl -X PUT "$URL" -H "Content-Type: application/pdf" --data-binary @contract.pdf
curl -X POST https://api.utilnest.io/v1/uploads/$FILE/complete -H "Authorization: Bearer $UTILNEST_KEY"

# 2. Convert: handlers office.pdf, pdf.docx, pdf.xlsx, ebook.pdf, ebook.epub
curl https://api.utilnest.io/v1/jobs -H "Authorization: Bearer $UTILNEST_KEY" \
  -H "Content-Type: application/json" -d '{"fileId": "'$FILE'", "handler": "pdf.docx", "options": {"to": "docx"}}'

# 3. Poll GET /v1/jobs/{id} until it is done, then get a download link for its output file
curl https://api.utilnest.io/v1/files/$OUTPUT/download -H "Authorization: Bearer $UTILNEST_KEY"

Cloud AI

These run on https://utilnest.io/api/ai/… with the same key and charge credits at their real model cost, as on the site:

Your balance and what is left this month are in GET https://api.utilnest.io/v1/usage.

Limits, errors and retries

• Rate: 120 requests a minute per key (429 with Retry-After past that), on top of the plan limits.
• Idempotency: send Idempotency-Key: <your id> on a POST to the API host; repeating it within 24 hours returns the first response (marked Idempotent-Replayed: true) instead of running again. The same key with a different body gets 422.
• Errors are JSON: {"error": "code", "message": "…"}. Common codes: invalid-key (401), pro-required (403), rate (429), credits (402, with your balance), unknown-utility (404), invalid-input (400).
• Logs: we log each call's time, path, status and key id, never what you send or get back.

The terms apply to API use; automated access is allowed through the API only.