Rate API · Docs

Basics

Base URL http://localhost:3000. Sab kuch JSON hai. Har response ka shape fix hai:

{ "ok": true,  "data": … }        // success
{ "ok": false, "error": "…" }     // failure

IP allowlist: server sirf allowlisted IP (default 91.108.105.218) aur localhost se requests leta hai. Kahin aur se aayi to 403 Forbidden: IP not allowed — passkey sahi ho tab bhi.

GET /health bina passkey ke uptime check deta hai (IP allowlist phir bhi lagti hai).

Authentication

Har endpoint ko passkey chahiye. Teen jagah se bhej sakte ho — jo suit kare:

# 1. payload (body) me
curl -X POST http://localhost:3000/api/rates \
     -H 'content-type: application/json' \
     -d '{"passkey":"client_xxx","id":"profile_1001","rate":5820.5}'

# 2. query string me
curl "http://localhost:3000/api/rates?passkey=client_xxx"

# 3. header me
curl -H "x-passkey: client_xxx" http://localhost:3000/api/rates
curl -H "Authorization: Bearer client_xxx" http://localhost:3000/api/rates

Sirf stored passkey chalti hai. Jo passkey passkeys table me nahi hai use turant reject kiya jaata hai — koi guest ya default access nahi. Reject bhi analytics me record hota hai.

Situation	Response
Passkey bheji hi nahi	`401 passkey missing`
Passkey table me nahi hai	`401 Invalid passkey`
Passkey hai par `active = 0`	`403 Passkey is disabled`
Admin endpoint, normal key se	`403 Admin passkey required`

Profile ids

id hamesha caller deta hai. Ye bahar ke system ka profile id hai, isliye kahin bhi auto-generate nahi hota — na API se, na dashboard page se. Rate create / get / update aur passkey create, sab me id tum bhejte ho.

Type TEXT — profile_1001 jaisa string bhi, 90210 jaisa number bhi (andar string ban jaata hai)
Max 120 characters, trim ho jaata hai
/ aur control characters allowed nahi → 400 Invalid id
Rate aur passkey dono me wahi profile id use kar sakte ho — dono tables independent hain

id teen jagah se accept hota hai: URL path, ?id= query, ya payload. Teeno ek hi kaam karte hain:

GET  /api/rates/profile_1001
GET  /api/rates?id=profile_1001
PUT  /api/rates            {"id":"profile_1001","rate":5999.99}

Error codes

Code	Kab
400	`id` ya `rate` missing / invalid, kharab JSON
401	Passkey missing ya table me nahi
403	Passkey disabled, admin chahiye, ya IP allowlist me nahi
404	Rate / passkey exist nahi karta, ya route galat
409	Wahi `id` pehle se hai
413	Payload 1 MB se bada

Rates koi bhi valid passkey

Har rate ka ek validity period hota hai. effective_from (kab se — create pe required), effective_to (kab tak — khaali chhodo to open-ended, matlab abhi tak valid), aur month (YYYY-MM — na bhejo to effective_from se apne aap ban jaata hai).

GET `/api/rates` — list

curl "http://localhost:3000/api/rates?passkey=client_xxx"

{
  "ok": true,
  "data": [
    { "id": "profile_1001", "name": "gold_22k", "rate": 5820.5,
      "effective_from": "2026-08-01", "effective_to": "2026-08-31", "month": "2026-08",
      "created_at": "2026-08-21 07:37:47", "updated_at": "2026-08-21 07:37:47" }
  ]
}

List pe do filter hain:

# us month ke rates
curl "http://localhost:3000/api/rates?passkey=client_xxx&month=2026-08"

# jo rates kisi date par lagu the (open-ended bhi aayenge)
curl "http://localhost:3000/api/rates?passkey=client_xxx&active_on=2026-08-20"
curl "http://localhost:3000/api/rates?passkey=client_xxx&active_on=today"

GET `/api/rates/:id` — ek record

# id path me
curl -H "x-passkey: client_xxx" http://localhost:3000/api/rates/profile_1001

# ya id query/payload me
curl "http://localhost:3000/api/rates?passkey=client_xxx&id=profile_1001"

POST `/api/rates` — create

Field	Required	Format
id	haan	profile id (TEXT)
rate	haan	number
effective_from	haan	`YYYY-MM-DD`
effective_to	nahi	`YYYY-MM-DD` — na do to open-ended
month	nahi	`YYYY-MM` — na do to `effective_from` se
name	nahi	label

curl -X POST http://localhost:3000/api/rates \
     -H 'content-type: application/json' \
     -d '{"passkey":"client_xxx",
          "id":"profile_1001",
          "name":"gold_22k",
          "rate":5820.5,
          "effective_from":"2026-08-01",
          "effective_to":"2026-08-31",
          "month":"2026-08"}'

Bina id ke → 400 `id` is required. Bina effective_from ke → 400 `effective_from` is required. Wahi id dobara → 409 already exists. effective_to effective_from se pehle ka ho → 400.

PUT PATCH `/api/rates/:id` — update

Saare fields optional — jo bhejoge wahi badlega, updated_at apne aap set hota hai.

# sirf rate badlo
curl -X PUT http://localhost:3000/api/rates/profile_1001 \
     -H 'content-type: application/json' \
     -d '{"passkey":"client_xxx","rate":5999.99}'

# period badlo -- rate ko August se September tak extend karo
curl -X PUT http://localhost:3000/api/rates/profile_1001 \
     -H 'content-type: application/json' \
     -d '{"passkey":"client_xxx","effective_to":"2026-09-30"}'

# period dobara open-ended karo
curl -X PUT http://localhost:3000/api/rates/profile_1001 \
     -H 'content-type: application/json' \
     -d '{"passkey":"client_xxx","effective_to":null}'

effective_to ko null bhejna allowed hai (period khul jaata hai), par effective_from ko khaali nahi kar sakte — rate hamesha kisi date se lagu hota hai (400 effective_from cannot be cleared).

DELETE `/api/rates/:id`

curl -X DELETE "http://localhost:3000/api/rates/profile_1001?passkey=client_xxx"

{ "ok": true, "deleted": "profile_1001" }

GET `/api/me`

Ye passkey kiski hai — { id, label, is_admin }.

Passkeys admin only

GET `/api/keys`

Saari keys — id, passkey, label, is_admin, active, created_at.

POST `/api/keys` — nayi key issue karo

Body: id (required, profile id) · label · new_passkey (optional — na do to secret auto-generate) · is_admin.

curl -X POST http://localhost:3000/api/keys \
     -H 'content-type: application/json' -H 'x-passkey: admin_xxx' \
     -d '{"id":"profile_7788","label":"partner-api"}'

{ "ok": true, "data": { "id": "profile_7788", "passkey": "pk_bf97…", "label": "partner-api",
                        "is_admin": 0, "active": 1, "created_at": "…" } }

PATCH `/api/keys/:id` — enable / disable / rename

curl -X PATCH http://localhost:3000/api/keys/profile_7788 \
     -H 'content-type: application/json' -H 'x-passkey: admin_xxx' \
     -d '{"active":false}'

Disable ki hui key ki har call 403 hoti hai, par analytics me auth.disabled ke roop me record hoti rehti hai.

DELETE `/api/keys/:id`

Apni hi key delete nahi kar sakte. Key delete karne par uske purane analytics events bane rehte hain (passkey_id null ho jaata hai).

Analytics admin only

GET `/api/analytics/summary?days=7`

Dashboard jo dikhata hai wahi data:

totals — total / ok / failed requests, active keys, avg latency, today
byAction — kis action ke kitne hits
byKey — per passkey: get / create / update / delete / failed counts + last seen
daily — din-wise hits aur failures (days se range)
hourly — pichle 24 ghante ghanta-wise
topRates — sabse zyada request hone wale rate records

GET `/api/analytics/events`

Raw event log. Query: limit (max 500) · offset · passkey_id · action · failed=1.

curl -H "x-passkey: admin_xxx" \
  "http://localhost:3000/api/analytics/events?passkey_id=profile_1001&limit=50"

{ "ok": true, "data": { "total": 665, "rows": [ … ] } }

Log me passkey hamesha masked hoti hai (clie...0fa1), aur payload me se passkey / token jaise fields mask karke store hote hain.

Analytics actions

Har event ka action in me se ek hota hai:

Action	Matlab
rate.list	Poori list maangi
rate.get	Ek rate padha
rate.create	Naya rate bana
rate.update	Rate badla
rate.delete	Rate delete hua
auth.missing	Passkey bheji hi nahi
auth.invalid	Passkey table me nahi hai
auth.disabled	Key disabled hai
auth.forbidden	Admin endpoint, normal key se
ip.blocked	IP allowlist me nahi
route.missing	Aisa koi endpoint nahi
key.create / key.update / key.delete	Admin ne keys chhedin

Tables

rates
  id              TEXT PRIMARY KEY -- profile id, caller deta hai
  name            TEXT
  rate            REAL
  effective_from  TEXT             -- YYYY-MM-DD, kab se lagu
  effective_to    TEXT             -- YYYY-MM-DD, kab tak (NULL = open-ended)
  month           TEXT             -- YYYY-MM
  created_at      TEXT
  updated_at      TEXT

passkeys
  id          TEXT PRIMARY KEY     -- profile id, caller deta hai
  passkey     TEXT UNIQUE          -- secret
  label       TEXT
  is_admin    INTEGER
  active      INTEGER
  created_at  TEXT

analytics
  id          INTEGER PRIMARY KEY  -- log row counter
  passkey_id  TEXT  -> passkeys.id
  passkey     TEXT                 -- masked
  label       TEXT
  action      TEXT
  method      TEXT
  path        TEXT
  target_id   TEXT                 -- kis rate pe
  status      INTEGER
  ok          INTEGER
  duration_ms INTEGER
  ip          TEXT
  user_agent  TEXT
  payload     TEXT                 -- secrets masked
  error       TEXT
  created_at  TEXT

Basics

Authentication

Profile ids

Error codes

Rates koi bhi valid passkey

GET /api/rates — list

GET /api/rates/:id — ek record

POST /api/rates — create

PUT PATCH /api/rates/:id — update

DELETE /api/rates/:id

GET /api/me