ALLINONETOOLS
नेपाली

Developer API

Calculators, converters, text utilities and AI over plain HTTPS and JSON. Create a key, send a request, read the answer. Everything on this page is generated from the code that serves the API.

Quick start

  1. Sign in, open Developers and create a key. Copy it; it is shown once.
  2. Keep it on your server, for example in an environment variable.
  3. Call an endpoint:
curl -X POST https://tools.bajhangi.bid/api/v1/calc/vat \
  -H "Authorization: Bearer $AIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount":1000,"rate_pct":13}'

The answer is JSON: { "data": { … }, "meta": { "request_id": "req_…", "credits_charged": 0 } }.

Authentication

Send the key in the Authorization header as Bearer <key>. Keys are never accepted in the URL.

  • A key looks like aio_live_…. We store only its SHA-256 fingerprint and the first characters for display, so a lost key cannot be recovered. Create a new one and revoke the old one.
  • Each key has scopes (permissions). A call outside them returns 403 with the scope it needed. A new key does not get the credit-spending AI scope unless you tick it.
  • This is a server-to-server API: there are no CORS headers on purpose. Never put a key in a web page or a mobile app; anyone could copy it.
  • Revoking a key works immediately. Keys made by someone who leaves an organization are revoked with them. A suspended account cannot use its keys.
  • Repeated wrong keys from one address are slowed down (429) for a few minutes.
Scopes
ScopeAllows
tools:readSee which endpoints exist and what they cost.
usage:readRead this key's usage, rate limit and the credit balance.
rates:readRead the bundled Nepal Rastra Bank rate snapshot.
calc:runLoan EMI, VAT and SIP calculators.
convert:runBS/AD dates and unit conversion.
text:runText statistics and case conversion.
ai:runSummarize, translate, rewrite and more. Spends credits.
embed:tokenOrganization keys only: read the widget settings and mint short-lived embed tokens.

Responses and errors

Success is 200 with data and meta. Every response, success or error, carries an X-Request-Id header. Errors share one shape:

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit of 60 requests per minute exceeded for this key.",
    "request_id": "req_AbCdEf123456",
    "details": {
      "limit": 60,
      "retryAfterSeconds": 12
    }
  }
}
Error codes
HTTPcodeMeaning
400invalid_requestThe request body or a header is not valid (details.issues lists the fields).
401unauthorizedThe key is missing, wrong, revoked or expired.
402insufficient_creditsThe owner has too few credits for this call. Nothing ran and nothing was charged.
403forbiddenThe key lacks the scope (details.required_scope), or the account is suspended.
404not_foundNo such endpoint.
409conflictThis Idempotency-Key was already used.
413payload_too_largeThe body is over the size limit.
415unsupported_media_typeSend Content-Type: application/json.
422unprocessableValid JSON that cannot be processed, for example a date that does not exist.
429rate_limitedToo many requests for this key (or for the plan). See Retry-After.
500internal_errorOur fault. Quote the request_id if you contact us.
503provider_not_configuredThe AI provider is not set up on this server. Nothing was charged.
503unavailableThe upstream service could not finish. Credits are refunded; try again later.

Wrong method on a real path returns 405 with an Allow header. Request bodies are JSON, at most 250 KB, and unknown fields are rejected so typos do not pass silently.

Rate limits

Each key has its own limit in requests per minute, sliding (not reset on the minute): 60 by default, up to 600, chosen when the key is created. Authenticated responses carry:

  • X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (unix seconds when a slot frees up)
  • On 429: Retry-After in seconds. Rejected requests are not counted against you.

Credits and billing

  • Endpoints that cost nothing are free: they never touch your credits. Right now these cost credits: ai.run. Every other endpoint is free.
  • A priced call first reserves its cost, runs, then charges exactly the price. If anything fails, the reservation is released and you pay nothing. A call you cannot afford returns 402 before anything runs.
  • Keys belong to a person or an organization and spend that owner's credits. Priced calls also count toward the owner's plan allowance (daily and monthly), which can answer 429.
  • Send Idempotency-Key (8–64 characters) on priced calls. Repeating the same key answers 409 and is not charged again; use a new key for a new request.
  • cost_credits in GET /api/v1/tools shows each price. These prices are launch defaults chosen by the site owner and are not final; they can change, and the endpoint list always shows the current ones. Buying credits needs the owner's payment accounts, which are not connected yet.

Endpoints

Base URL https://tools.bajhangi.bid/api/v1. Only deterministic calculators, converters and text utilities run here, plus text AI through the site's existing AI gateway. There are no file, PDF or OCR endpoints.

GET

/api/v1/tools

List the endpoints of this API with the scope each one needs and what it costs.

Needs scope tools:read · Cost: Free

Example request

curl https://tools.bajhangi.bid/api/v1/tools \
  -H "Authorization: Bearer $AIO_API_KEY"

Example response (shortened)

{
  "data": {
    "endpoints": [
      {
        "id": "calc.vat",
        "method": "POST",
        "path": "/api/v1/calc/vat",
        "scope": "calc:run",
        "cost_credits": 0,
        "allowed": true,
        "summary": "VAT on an amount: add it to a net price or take it out of a gross price."
      }
    ]
  },
  "meta": {
    "request_id": "req_AbCdEf123456",
    "credits_charged": 0
  }
}
GET

/api/v1/usage

This key's rate limit and 30-day usage, plus the owner's plan and credit balance.

Needs scope usage:read · Cost: Free

Example request

curl https://tools.bajhangi.bid/api/v1/usage \
  -H "Authorization: Bearer $AIO_API_KEY"

Example response (shortened)

{
  "data": {
    "key": {
      "name": "my-server",
      "prefix": "aio_live_AbCdEfGh",
      "scopes": [
        "calc:run"
      ],
      "rate_limit_per_min": 60
    },
    "owner": {
      "type": "user",
      "plan": "free",
      "credits": 0
    },
    "last_30_days": {
      "requests": 12,
      "errors": 0,
      "rate_limited": 0,
      "credits_charged": 0,
      "avg_latency_ms": 4,
      "p95_latency_ms": 9
    }
  },
  "meta": {
    "request_id": "req_AbCdEf123456",
    "credits_charged": 0
  }
}
GET

/api/v1/rates/currency

Nepal Rastra Bank exchange rates from the snapshot bundled with this deployment (NPR per 1 unit).

Needs scope rates:read · Cost: Free

  • This is a DATED SNAPSHOT, not live data: check `as_of`. The website's currency converter fetches newer rates on demand.

Example request

curl https://tools.bajhangi.bid/api/v1/rates/currency \
  -H "Authorization: Bearer $AIO_API_KEY"

Example response (shortened)

{
  "data": {
    "source": "nrb",
    "base": "NPR",
    "live": false,
    "as_of": "2026-11-15",
    "npr_per_unit": {
      "NPR": 1,
      "USD": 133.5
    },
    "note": "Truncated example."
  },
  "meta": {
    "request_id": "req_AbCdEf123456",
    "credits_charged": 0
  }
}
POST

/api/v1/calendar/bs-to-ad

Convert a Bikram Sambat (BS) date to the Gregorian (AD) date.

Needs scope convert:run · Cost: Free

  • BS years 1970-2090 (the verified table range). `date` is YYYY-MM-DD; Devanagari digits are accepted.

Example request

curl -X POST https://tools.bajhangi.bid/api/v1/calendar/bs-to-ad \
  -H "Authorization: Bearer $AIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date":"2081-01-01"}'

Example response

{
  "data": {
    "input": {
      "calendar": "BS",
      "date": "2081-01-01"
    },
    "output": {
      "calendar": "AD",
      "date": "2024-04-13",
      "year": 2024,
      "month": 4,
      "day": 13
    },
    "weekday": "Saturday"
  },
  "meta": {
    "request_id": "req_AbCdEf123456",
    "credits_charged": 0
  }
}
POST

/api/v1/calendar/ad-to-bs

Convert a Gregorian (AD) date to the Bikram Sambat (BS) date.

Needs scope convert:run · Cost: Free

  • AD years 1913-2034 (the range covered by the BS table). `date` is YYYY-MM-DD.

Example request

curl -X POST https://tools.bajhangi.bid/api/v1/calendar/ad-to-bs \
  -H "Authorization: Bearer $AIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date":"2024-04-13"}'

Example response

{
  "data": {
    "input": {
      "calendar": "AD",
      "date": "2024-04-13"
    },
    "output": {
      "calendar": "BS",
      "date": "2081-01-01",
      "year": 2081,
      "month": 1,
      "day": 1
    },
    "weekday": "Saturday"
  },
  "meta": {
    "request_id": "req_AbCdEf123456",
    "credits_charged": 0
  }
}
POST

/api/v1/calc/emi

Loan EMI with total interest and an optional yearly amortization schedule.

Needs scope calc:run · Cost: Free

  • Reducing-balance monthly EMI, rounded to 2 decimals. No bank fees, taxes or insurance.

Example request

curl -X POST https://tools.bajhangi.bid/api/v1/calc/emi \
  -H "Authorization: Bearer $AIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"principal":100000,"annual_rate_pct":12,"months":12}'

Example response

{
  "data": {
    "emi": 8884.88,
    "months": 12,
    "total_interest": 6618.55,
    "total_payment": 106618.55
  },
  "meta": {
    "request_id": "req_AbCdEf123456",
    "credits_charged": 0
  }
}
POST

/api/v1/calc/vat

VAT on an amount: add it to a net price or take it out of a gross price.

Needs scope calc:run · Cost: Free

  • You supply the rate; this API does not decide what rate applies to what.

Example request

curl -X POST https://tools.bajhangi.bid/api/v1/calc/vat \
  -H "Authorization: Bearer $AIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount":1000,"rate_pct":13}'

Example response

{
  "data": {
    "net": 1000,
    "vat": 130,
    "gross": 1130
  },
  "meta": {
    "request_id": "req_AbCdEf123456",
    "credits_charged": 0
  }
}
POST

/api/v1/calc/sip

Future value of a monthly SIP (investment at month start, monthly compounding).

Needs scope calc:run · Cost: Free

  • A constant-rate projection, not a forecast or advice.

Example request

curl -X POST https://tools.bajhangi.bid/api/v1/calc/sip \
  -H "Authorization: Bearer $AIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"monthly_amount":5000,"annual_rate_pct":12,"months":12}'

Example response

{
  "data": {
    "invested": 60000,
    "value": 64046.64,
    "gain": 4046.64
  },
  "meta": {
    "request_id": "req_AbCdEf123456",
    "credits_charged": 0
  }
}
POST

/api/v1/convert/units

Convert a value between units (length, mass, area incl. Nepal land units, volume, temperature, pressure, speed, energy, power, data).

Needs scope convert:run · Cost: Free

  • `from`/`to` are unit ids such as m, ft, kg, lb, ropani, c, f, kib. See the unit list below.

Example request

curl -X POST https://tools.bajhangi.bid/api/v1/convert/units \
  -H "Authorization: Bearer $AIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category":"length","value":1,"from":"mi","to":"km"}'

Example response

{
  "data": {
    "category": "length",
    "value": 1,
    "from": "mi",
    "to": "km",
    "result": 1.609344
  },
  "meta": {
    "request_id": "req_AbCdEf123456",
    "credits_charged": 0
  }
}

Categories and unit ids

length
mm, cm, m, km, in, ft, yd, mi, nmi
mass
mg, g, kg, t, oz, lb, tola
area
m2, cm2, km2, ha, ft2, in2, acre, ropani, aana, paisa, daam, bigha, kattha, dhur
volume
ml, l, m3, in3, ft3, galus, galimp, ptus, cup, flozus
temperature
c, f, k
pressure
pa, kpa, bar, mbar, atm, psi, torr, inhg
speed
ms, kmh, mph, fts, kn
energy
j, kj, cal, kcal, wh, kwh, mj, btu
power
w, kw, mw, hp, hpuk, btuh
data
bit, b, kb, mb, gb, tb, kib, mib, gib, tib
POST

/api/v1/text/stats

Words, characters, sentences, paragraphs and reading time for a text.

Needs scope text:run · Cost: Free

  • Up to 100,000 characters per request. Nepali and other scripts are counted by grapheme.

Example request

curl -X POST https://tools.bajhangi.bid/api/v1/text/stats \
  -H "Authorization: Bearer $AIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello world. This is a test."}'

Example response

{
  "data": {
    "words": 6,
    "characters": 28,
    "characters_no_spaces": 23,
    "bytes": 28,
    "sentences": 2,
    "paragraphs": 1,
    "lines": 1,
    "reading_minutes": 0.0252,
    "speaking_minutes": 0.04
  },
  "meta": {
    "request_id": "req_AbCdEf123456",
    "credits_charged": 0
  }
}
POST

/api/v1/text/case

Change the letter case of a text: upper, lower, title (AP, Chicago or simple) or sentence case.

Needs scope text:run · Cost: Free

Example request

curl -X POST https://tools.bajhangi.bid/api/v1/text/case \
  -H "Authorization: Bearer $AIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"the quick brown fox","mode":"title"}'

Example response

{
  "data": {
    "result": "The Quick Brown Fox"
  },
  "meta": {
    "request_id": "req_AbCdEf123456",
    "credits_charged": 0
  }
}
GET

/api/v1/embed/config

The organization's white-label widget settings: whether embedding is on, the allowed websites, the enabled tools and the brand.

Needs scope embed:token · Cost: Free

  • Organization keys only: a personal key gets 422. Settings are changed by an owner or admin in the dashboard, not through the API.

Example request

curl https://tools.bajhangi.bid/api/v1/embed/config \
  -H "Authorization: Bearer $AIO_API_KEY"

Example response (shortened)

{
  "data": {
    "organization": {
      "handle": "acme-traders"
    },
    "embedding": {
      "enabled": true,
      "allowed_origins": [
        "https://www.acme.example"
      ],
      "tools": [
        {
          "id": "FIN-001",
          "name": "EMI Calculator"
        }
      ],
      "base_url": "https://tools.example/embed/acme-traders"
    },
    "brand": {
      "name": "Acme Traders",
      "color": "#1a56db",
      "logo_url": null
    }
  },
  "meta": {
    "request_id": "req_AbCdEf123456",
    "credits_charged": 0
  }
}
POST

/api/v1/embed/token

Mint a short-lived signed embed token for the organization, so your own server can render widgets without exposing a long-lived one.

Needs scope embed:token · Cost: Free

  • Organization keys only. The token lives 1 hour by default (60 seconds to 24 hours) and stops working at once if the organization rotates its embed key.
  • Use it as the t query parameter of the widget URL: url_template shows the exact form. Embedding must be switched on in the dashboard, and the page that shows the widget must be on the allowed-websites list.
  • A token is not a secret from your visitors (it appears in the page); it only proves the organization enabled the widget and can expire or be revoked.

Example request

curl -X POST https://tools.bajhangi.bid/api/v1/embed/token \
  -H "Authorization: Bearer $AIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ttl_seconds":3600}'

Example response (shortened)

{
  "data": {
    "token": "aioe1.…",
    "expires_at": "2026-01-01T01:00:00.000Z",
    "ttl_seconds": 3600,
    "url_template": "https://tools.example/embed/acme-traders/{tool}?t=aioe1.…"
  },
  "meta": {
    "request_id": "req_AbCdEf123456",
    "credits_charged": 0
  }
}
POST

/api/v1/ai/run

Run a text AI task (summarize, translate, rewrite, grammar, ...) through the site's AI gateway. Spends credits.

Needs scope ai:run · Cost: Per task, in cost units (1 unit: chat, summarize, rewrite, translate, humanize, paraphrase, grammar, extract, email; 2 units: research, report; 3 units: article) × credits per unit (set by the owner, default 1)

  • Tasks: chat, summarize, rewrite, article, translate, humanize, paraphrase, grammar, extract, research, report, email.
  • Cost = the gateway's cost units for the task x credits per unit (default 1; the owner sets it). A failed call is refunded in full.
  • `503 provider_not_configured` until the owner has configured an AI provider. Output may be wrong: review it before use.
  • Send an `Idempotency-Key` header to make retries safe (a repeated key is rejected with 409 and charged once).

Example request

curl -X POST https://tools.bajhangi.bid/api/v1/ai/run \
  -H "Authorization: Bearer $AIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task":"summarize","input":"A long text ...","options":{"length":"short"}}'

Example response (shortened)

{
  "data": {
    "text": "A short summary.",
    "provider": "groq",
    "model": "model-id"
  },
  "meta": {
    "request_id": "req_AbCdEf123456",
    "credits_charged": 0
  }
}

Webhooks

Add an address under Developers and we POST signed JSON events to it. The address must be a public https:// URL (private networks are refused, redirects are not followed). The signing secret whsec_… is shown once and stored encrypted.

Webhook events
EventWhen
webhook.testSent when you press Send test event.
credits.lowYour credit balance dropped below the low-credit threshold after an API request.
api_key.createdA new API key was created.
api_key.revokedAn API key was revoked.
subscription.updatedA verified payment started or extended a subscription.
{
  "id": "evt_AbCdEf123456",
  "type": "credits.low",
  "created": 1763251200,
  "data": {
    "balance": 9,
    "threshold": 10,
    "owner_type": "user"
  }
}

Events carry metadata only: no emails, names or keys. Each request has these headers:

  • X-AIO-Signature: t=<unix seconds>,v1=<hex>: HMAC-SHA256 of <t>.<raw body> with your secret
  • X-AIO-Event (type), X-AIO-Event-Id (same on every retry), X-AIO-Delivery, X-AIO-Attempt (1–8)

Verify before you trust a request: recompute the signature over the raw body, compare in constant time, reject timestamps more than 5 minutes off, and ignore event ids you have already processed.

import { createHmac, timingSafeEqual } from "node:crypto";

const seen = new Set(); // in production: a store with expiry (Redis, a DB table)

export function verify(rawBody, headers, secret) {
  const header = headers["x-aio-signature"] ?? "";
  const t = Number(/t=(\d+)/.exec(header)?.[1]);
  const sig = /v1=([0-9a-f]{64})/.exec(header)?.[1];
  if (!t || !sig) return false;
  if (Math.abs(Date.now() / 1000 - t) > 300) return false; // too old (replay) or from the future
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  if (!timingSafeEqual(Buffer.from(sig, "hex"), Buffer.from(expected, "hex"))) return false;
  const id = headers["x-aio-event-id"]; // identical on every retry and replay
  if (seen.has(id)) return false;       // already processed
  seen.add(id);
  return true;
}
  • Answer with any 2xx within 8 seconds. Anything else counts as a failure.
  • A failed delivery is retried up to 8 times in total, starting 30 seconds after the first failure, doubling each time up to 6 hours, with random jitter. Each retry is signed again with a fresh timestamp.
  • After 5 deliveries in a row run out of retries, the webhook is paused until you switch it on again. Every delivery is listed in the delivery log, where you can replay one.
  • Retries run when the site has traffic or when the owner's scheduled maintenance call runs, so a retry can be a little later than the schedule.

Status of this API

Implemented and unit-tested. No live traffic has been verified yet.

  • The AI endpoint needs the owner's AI provider keys; until they are set it answers 503 and costs nothing.
  • Buying credits and plans needs the owner's payment accounts; until then only credits you already have can be spent.
  • Webhook delivery to real servers has been exercised against a local receiver only.
  • Currency rates are a dated snapshot, not a live feed. Check as_of.