Rate API — documentation

Basics

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

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

GET /health bina passkey ke uptime check deta hai.

Authentication

Har endpoint ko passkey chahiye. Teen jagah se bhej sakte ho — jo suit kare. GET ke saath bhi JSON body chalti hai, to passkey / id / month sab ek hi payload me bhej sakte ho:

copy# 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,"effective_from":"2026-04"}'

# 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

# GET + body -- sab kuch ek payload me
curl -X GET http://localhost:3000/api/rates \
     -H 'content-type: application/json' \
     -d '{"passkey":"client_xxx","id":"profile_1001","month":"2026-02"}'

Key ka scope — kis key ko kitne rates dikhte hain

Har passkey ka ek scope hota hai. Ye tay karta hai ki wo key kaunse rates dekh / badal sakti hai. GET /api/me se apna scope check kar sakte ho.

Profile ids

• 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:

copyGET  /api/rates/profile_1001?month=2026-03
GET  /api/rates?id=profile_1001&month=2026-03
PUT  /api/rates            {"id":"profile_1001","month":"2026-03","rate":5999.99}

Ek profile ke kai rate rows hote hain — har period ka apna. Isliye har period ka apna rate_id hota hai jo server banata hai aur create ke response me wapas aata hai. Usse kisi ek period ko exactly target karte ho — rate badalna ho ya month range, dono ke liye wahi id.

Error codes

Apni key khud banao signup secret

User ko admin ke paas jaane ki zarurat nahi — do call me apni key mil jaati hai. user_id hi uska profile id hai, aur aise bani key ka scope own hota hai — wo sirf apne profile ka rate aur history padh sakta hai.

Step 1 · GET /api/keys/lookup?user_id=:user_id

Pehle ye check karo ki us user ki key pehle se hai ya nahi. Passkey ki value yahan kabhi wapas nahi aati — sirf "hai ya nahi" pata chalta hai.

copycurl "http://localhost:3000/api/keys/lookup?user_id=acme"      -H "x-signup-secret: $SIGNUP_SECRET"

# key nahi hai, par profile bhi nahi hai -> register nahi hoga
{ "ok": true, "data": { "user_id": "acme", "exists": false,
                        "profile_exists": false, "can_register": false } }

# key nahi hai aur profile maujood hai -> Step 2 par jao
{ "ok": true, "data": { "user_id": "acme", "exists": false,
                        "profile_exists": true, "can_register": true } }

# key pehle se hai -> naya register mat karo
{ "ok": true, "data": {
    "user_id": "acme", "exists": true, "profile_exists": true, "can_register": false,
    "active": true, "label": "Acme Ltd", "scope": "own", "is_admin": false,
    "created_at": "2026-09-09 11:45:53" } }

Step 2 · POST /api/keys/register

Sirf tab jab Step 1 me can_register: true aaya ho.

copycurl -X POST http://localhost:3000/api/keys/register      -H "x-signup-secret: $SIGNUP_SECRET"      -H 'content-type: application/json'      -d '{"user_id":"acme","label":"Acme Ltd"}'

{ "ok": true,
  "data": { "user_id": "acme",
            "passkey": "pk_eaad439def25eccc9cfdcfe120d958e9",
            "label": "Acme Ltd",
            "scope": "own" },
  "note": "Ye passkey ab dobara nahi dikhega -- abhi save kar lo." }

Apni pasand ki passkey bhejni ho

Server ki generated key yaad rakhne ka jhanjhat na ho to new_passkey me apni value bhej do — wahi store hoti hai aur wahi response me echo hoti hai:

copycurl -X POST http://localhost:3000/api/keys/register      -H "x-signup-secret: $SIGNUP_SECRET"      -H 'content-type: application/json'      -d '{"user_id":"acme","new_passkey":"AcmeSecret2026!x"}'

{ "ok": true,
  "data": { "user_id":"acme", "passkey":"AcmeSecret2026!x", "label":"acme", "scope":"own" },
  "note": "Ye wahi passkey hai jo tumne bheji thi." }

Step 3 · us key se apna rate padho

Normal rate API wahi hai — bas x-passkey me apni key lagao. List me sirf tumhare profile ke rows aayenge, aur likhne wale endpoints band rahenge.

copyKEY=pk_eaad439def25eccc9cfdcfe120d958e9

# apne profile ke saare rates
curl http://localhost:3000/api/rates -H "x-passkey: $KEY"

# is month ka rate
curl "http://localhost:3000/api/rates/profile_1001?month=2026-06" -H "x-passkey: $KEY"

# poori history -- saare periods
curl http://localhost:3000/api/rates/profile_1001/history -H "x-passkey: $KEY"

# doosre profile par -> 404
curl http://localhost:3000/api/rates/profile_2002 -H "x-passkey: $KEY"
{ "ok": false, "error": "profile_2002 ka koi rate nahi hai" }

# kuch bhi badalne ki koshish -> 403
curl -X PATCH http://localhost:3000/api/rates/profile_1001 -H "x-passkey: $KEY" -d '{"rate":1}'
{ "ok": false, "error": "Ye key sirf padh sakti hai -- rate banane/badalne ke liye panel wali key chahiye" }

# apna scope check karo
curl http://localhost:3000/api/me -H "x-passkey: $KEY"
{ "ok": true, "data": { "id": "profile_1001", "label": "Acme Ltd", "is_admin": false,
                        "scope": "own", "sees_all_rates": false, "can_edit_rates": false } }

Rates koi bhi valid passkey · scope ke hisaab se

Ek profile ki history kaise banti hai

copy# January me: Jan se March tak ka rate
curl -X POST http://localhost:3000/api/rates \
     -H 'content-type: application/json' \
     -d '{"passkey":"client_xxx","id":"profile_1001","name":"gold_22k","rate":5500,
          "effective_from":"2026-01","effective_to":"2026-03"}'

# April me: April se December tak ka naya rate (purana waise ka waisa rehta hai)
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-04","effective_to":"2026-12"}'

Ab profile_1001 ke do period hain, aur har ek ka apna rate_id:

rate_id 1    2026-01 → 2026-03    rate 5500
rate_id 2    2026-04 → 2026-12    rate 5820.5

GET /api/rates/:id?month=YYYY-MM — us month ka rate

Yahi main lookup hai: month bhejo, us month me jo rate lagu tha wo milega. month na do to is month ka rate.

copycurl "http://localhost:3000/api/rates/profile_1001?passkey=client_xxx&month=2026-03"
# -> rate 5500   (2026-01 → 2026-03 wala period)

curl "http://localhost:3000/api/rates/profile_1001?passkey=client_xxx&month=2026-06"
# -> rate 5820.5 (2026-04 → 2026-12 wala period)

{
  "ok": true,
  "data": { "rate_id": 1, "id": "profile_1001", "name": "gold_22k", "rate": 5500,
            "effective_from": "2026-01", "effective_to": "2026-03",
            "asked_month": "2026-03" }
}

month payload me bhi bhej sakte ho. Us month me koi period na mile to 404 … me koi rate lagu nahi hai.

GET /api/rates/:id/history — saare periods

copycurl -H "x-passkey: client_xxx" http://localhost:3000/api/rates/profile_1001/history

GET /api/rates — sab profiles

copy# saare periods, saare profiles
curl "http://localhost:3000/api/rates?passkey=client_xxx"

# sirf wo rates jo March me lagu the -- har profile ka ek row
curl "http://localhost:3000/api/rates?passkey=client_xxx&month=2026-03"

POST /api/rates — naya period

Response me naye period ka rate_id aata hai — usi se aage edit/delete karoge:

{
  "ok": true,
  "data": { "rate_id": 3, "id": "profile_1001", "name": "gold_22k", "rate": 6100,
            "effective_from": "2027-01", "effective_to": "2027-06",
            "created_at": "…", "updated_at": "…" }
}

PUT PATCH /api/rates/:id — period edit

Kaunsa period edit karna hai wo selector se chunta hai. Selector query me bhi chalega aur payload me bhi — jo suit kare:

Dono selector query me bhi chalte hain aur payload me bhi — ?rate_id=2 ya {"rate_id":2}, jo suit kare.

copy# 1. rate_id se rate badlo -- sab payload me
curl -X PUT http://localhost:3000/api/rates \
     -H 'content-type: application/json' \
     -d '{"passkey":"client_xxx","id":"profile_1001","rate_id":1,"rate":5555}'

# 2. rate_id se month range badlo (overlap hua to 409)
curl -X PUT http://localhost:3000/api/rates \
     -H 'content-type: application/json' \
     -d '{"passkey":"client_xxx","id":"profile_1001","rate_id":1,
          "effective_from":"2025-11","effective_to":"2026-02"}'

# 3. rate_id nahi pata? month se dhundo -- Feb jis period me hai uska rate badlega
curl -X PUT http://localhost:3000/api/rates \
     -H 'content-type: application/json' \
     -d '{"passkey":"client_xxx","id":"profile_1001","month":"2026-02","rate":5999}'

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

Jo field bhejoge sirf wahi badlega — baaki waise ke waise rehte hain, aur updated_at apne aap set hota hai.

effective_to ko null kar sakte ho, par effective_from ko khaali nahi — rate hamesha kisi month se lagu hota hai.

DELETE /api/rates/:id — ek period hatao

Wahi selectors chalte hain (query ya payload). Sirf wo period delete hota hai, baaki history bachi rehti hai. rate_id doosre profile ka ho to 404 — ek profile doosre ka period nahi chhed sakta.

copycurl -X DELETE "http://localhost:3000/api/rates/profile_1001?passkey=client_xxx&rate_id=1"

{ "ok": true, "deleted": { "id": "profile_1001", "rate_id": 1 } }

GET /api/me

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

Passkeys admin only

GET /api/keys

Saari keys — id, passkey, label, is_admin, scope, active, created_at. Kisi user ka kho gaya passkey yahin se dobara mil sakta hai.

POST /api/keys — nayi key issue karo

Body: id (required, profile id) · label · new_passkey (optional — na do to secret auto-generate; diya to 6–200 chars, bina space) · is_admin · scope.

copycurl -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, "scope": "all", "active": 1, "created_at": "…" } }

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

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

Body: active · label · scope ("all" ya "own") — yani kisi user ki key ko baad me full access de sakte ho ya wapas apne rates tak seemit kar sakte ho.

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.

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

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

Dynamic sections — kaise kaam karta hai

Upar wala /api/rates ek fixed table hai — uske columns code me likhe hain. Sections uska ulta hai: tum runtime par table banate ho, uske fields aur unke types tay karte ho, aur batate ho kaun si passkeys usko kaise use kar sakti hain.

Ek section banane par teen cheezein ek hi transaction me hoti hain:

1. dyn_sections me section ka row
2. dyn_fields me har field ka row — yahi schema ka record hai
3. asli sec_<slug> table, jiska DDL unhi field rows se banta hai

Yaani field definitions sirf documentation nahi hain — Postgres ke asli columns, NOT NULL, UNIQUE, DEFAULT aur CHECK unse hi bante hain. Isliye validation do jagah lagti hai: pehle JS me (saaf error message ke liye), phir DB me (aakhri guarantee).

Ek section, do keys

Access (section, passkey) ka joda hai, aur har jode ke apne teen flags — can_read, can_write, can_delete. Ek section ko jitni chaaho keys se jod sakte ho, aur har key ko alag permission de sakte ho:

invoices  ←  profile_1001   read ✓  write ✓  delete ✗
invoices  ←  profile_1002   read ✓  write ✗  delete ✗
branches  ←  profile_1001   read ✓  write ✓  delete ✓

admin passkey  →  har section par sab kuch, hamesha

Field types

Live list GET /api/types se milti hai (dashboard ka dropdown aur ye table wahi se bante hain).

Har field ke saath ye flags de sakte ho:

Section builder admin only

POST /api/sections — naya section

Fields aur access grants ek hi call me de sakte ho:

curl -X POST http://localhost:3000/api/sections \
  -H "x-passkey: $ADMIN" -H "content-type: application/json" -d '{
  "slug": "invoices",
  "label": "Client invoices",
  "description": "Har invoice ek row",
  "fields": [
    { "name": "invoice_no",  "type": "text",   "required": true, "unique": true },
    { "name": "client_name", "type": "text",   "indexed": true },
    { "name": "amount",      "type": "number", "required": true },
    { "name": "status",      "type": "enum",   "options": { "choices": ["draft","sent","paid"] },
                                               "default": "draft" },
    { "name": "due_date",    "type": "date" },
    { "name": "paid",        "type": "bool",   "default": "false" },
    { "name": "line_items",  "type": "json" }
  ],
  "access": [
    { "passkey_id": "profile_1001", "can_read": true, "can_write": true },
    { "passkey_id": "profile_1002", "can_read": true }
  ]
}'

Peeche Postgres me ye chalta hai:

CREATE TABLE sec_invoices (
  record_id    BIGSERIAL PRIMARY KEY,
  invoice_no   TEXT   NOT NULL,
  client_name  TEXT,
  amount       DOUBLE PRECISION NOT NULL,
  status       TEXT   DEFAULT 'draft' CONSTRAINT ck_sec_invoices_p3
                        CHECK (status IN ('draft','sent','paid')),
  due_date     DATE,
  paid         BOOLEAN DEFAULT FALSE,
  line_items   JSONB,
  created_by   TEXT,
  created_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
  updated_at   TIMESTAMPTZ NOT NULL DEFAULT now()
);
ALTER TABLE sec_invoices ADD CONSTRAINT uq_sec_invoices_p0 UNIQUE (invoice_no);
CREATE INDEX ix_sec_invoices_p1 ON sec_invoices (client_name);

GET /api/sections — sab sections

Har section ke saath uske fields, access grants aur record count.

GET /api/sections/:slug

PATCH /api/sections/:slug — label / description

DELETE /api/sections/:slug?confirm=:slug

POST /api/sections/:slug/fields — naya field

curl -X POST .../api/sections/invoices/fields \
  -H "x-passkey: $ADMIN" -H "content-type: application/json" \
  -d '{ "name": "notes", "type": "text", "label": "Internal notes" }'

ALTER TABLE … ADD COLUMN chalta hai, aur field turant usable ho jaata hai.

PATCH /api/sections/:slug/fields/:name

label, required, unique, indexed, default aur options (enum ke choices) badal sakte ho. Type badalna support nahi hai — uske liye field delete karke naye type se banao.

DELETE /api/sections/:slug/fields/:name

DROP COLUMN — us column ka data chala jaata hai. Aakhri field delete nahi ho sakta.

Access grants admin only

GET /api/sections/:slug/access

PUT /api/sections/:slug/access — grant set / update

Upsert hai — key pehle se ho to uske flags badal jaate hain, warna naya grant ban jaata hai.

curl -X PUT .../api/sections/invoices/access \
  -H "x-passkey: $ADMIN" -H "content-type: application/json" -d '{
  "access": [
    { "passkey_id": "profile_1001", "can_read": true, "can_write": true, "can_delete": true },
    { "passkey_id": "profile_1003", "can_read": true }
  ]
}'

Koi flag na do to sirf can_read — default hamesha sabse kam permission.

DELETE /api/sections/:slug/access/:passkey_id

GET /api/sections/status

Postgres zinda hai ya nahi, kaun sa database, kitne sections/fields/grants.

Section ka data jis key ko access ho

Ye endpoints admin-only nahi hain. Koi bhi valid passkey chalti hai — bas us section par uska grant hona chahiye. Grant na ho to 403, permission na ho to bhi 403.

GET /api/data/:slug/schema — pehle yahi dekho

Client ko bataata hai ki is section me kaun se fields hain, kis type ke, kya required hai, aur meri key kya kar sakti hai. Isse client bina docs padhe form bana sakta hai.

curl -H "x-passkey: $CLIENT" .../api/data/invoices/schema

GET /api/data/:slug — list

Response top level par hai (data me lipta hua nahi):

{ "ok": true, "section": "invoices", "total": 42, "limit": 50, "offset": 0,
  "rows": [ { "record_id": 1, "invoice_no": "INV-001", ... } ] }

Filters query string me — field ka naam + optional operator suffix:

Anjaan field par filter lagane par 404 milta hai — chup-chaap ignore nahi hota.

POST /api/data/:slug — naya record

curl -X POST .../api/data/invoices \
  -H "x-passkey: $CLIENT" -H "content-type: application/json" -d '{
  "invoice_no": "INV-2026-001",
  "client_name": "Acme Corp",
  "amount": 48500.75,
  "status": "sent",
  "due_date": "2026-09-15",
  "line_items": [ { "desc": "design", "qty": 2 } ]
}'

created_by me calling passkey ki id apne aap chali jaati hai. Fields ko {"data": { … }} me lapet ke bhi bhej sakte ho — dono chalega.

GET /api/data/:slug/:record_id

PATCH /api/data/:slug/:record_id — partial update

Jo fields bhejo wahi badalte hain, baaki waise hi rehte hain. Optional field ko null bhej ke khaali kar sakte ho; required field null par 400.

DELETE /api/data/:slug/:record_id

can_delete chahiye.

GET /api/my-sections

Meri key kaun se sections use kar sakti hai, kis permission ke saath. Admin ko sab dikhte hain.

GET /api/types

Saare field types ki live list.

Analytics actions

Har event ka action in me se ek hota hai:

Dynamic sections ke actions

Tables

rates                              -- ek profile ke kai rows (rate history)
  rate_id         INTEGER PRIMARY KEY  -- har period ka apna id, server banata hai
  id              TEXT              -- profile id, caller deta hai (repeat hota hai)
  owner_id        TEXT  -> passkeys.id  -- AUDIT: kis key ne banaya (visibility isse tay nahi hoti)
  name            TEXT
  rate            REAL
  effective_from  TEXT              -- YYYY-MM, is month se lagu
  effective_to    TEXT              -- YYYY-MM, is month tak (NULL = open-ended)
  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
  scope       TEXT                 -- 'all' = saare rates + write | 'own' = sirf apni id ke rates, read-only
  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

Postgres — dynamic sections (alag database)

dyn_sections                       -- ek row = ek section
  section_id   BIGSERIAL PRIMARY KEY
  slug         TEXT UNIQUE       -- api me yahi dikhta hai
  table_name   TEXT UNIQUE       -- sec_<slug>
  label        TEXT
  description  TEXT
  created_by   TEXT              -- kis passkey ne banaya
  created_at   TIMESTAMPTZ
  updated_at   TIMESTAMPTZ

dyn_fields                         -- section ka schema; DDL isi se banta hai
  field_id      BIGSERIAL PRIMARY KEY
  section_id    BIGINT -> dyn_sections.section_id  (ON DELETE CASCADE)
  name          TEXT              -- asli column ka naam
  label         TEXT
  type          TEXT              -- text | number | int | bool | date |
                                  -- datetime | json | uuid | enum
  required      BOOLEAN           -- NOT NULL
  is_unique     BOOLEAN           -- UNIQUE constraint
  indexed       BOOLEAN           -- index
  default_value TEXT              -- DEFAULT (type se validate hota hai)
  options       JSONB             -- enum choices, text max_length
  position      INTEGER           -- constraint naam isi se bante hain, reuse nahi hote
  UNIQUE (section_id, name)

dyn_access                         -- kaun si key, kaunsa section, kya kar sakti hai
  section_id  BIGINT -> dyn_sections.section_id  (ON DELETE CASCADE)
  passkey_id  TEXT              -- SQLite ki passkeys.id -- doosra db, isliye FK nahi
  can_read    BOOLEAN
  can_write   BOOLEAN
  can_delete  BOOLEAN
  granted_by  TEXT
  PRIMARY KEY (section_id, passkey_id)   -- ek section, kitni bhi keys

sec_<slug>                          -- har section ki apni table
  record_id   BIGSERIAL PRIMARY KEY
  <tumhare fields>                 -- dyn_fields se generate
  created_by  TEXT              -- kis passkey ne banaya
  created_at  TIMESTAMPTZ
  updated_at  TIMESTAMPTZ