npm-api.mdx - docs -

npm-api.mdx (2297B)
      1 ---
      2 title: "NPM API"
      3 ---
      4 
      5 import Copyright from "/snippets/copyright.mdx";
      6 
      7 **Base URL:** `https://notamitgamer-osma-npm-api.hf.space`
      8 
      9 ## GET /ping
     10 
     11 Uptime check — always returns 200. Lightweight endpoint for UptimeRobot or health monitors; doesn't query the database.
     12 
     13 ```bash
     14 curl https://notamitgamer-osma-npm-api.hf.space/ping
     15 ```
     16 
     17 ```json
     18 { "ping": "pong" }
     19 ```
     20 
     21 ## GET /health
     22 
     23 Server status + total package count. Returns `200` with the package count once the database is ready; returns `503` if it's still initializing after a cold start.
     24 
     25 ```bash
     26 curl https://notamitgamer-osma-npm-api.hf.space/health
     27 ```
     28 
     29 ```json
     30 {
     31   "status": "ok",
     32   "total_packages": 3881465
     33 }
     34 ```
     35 
     36 ## GET /stats
     37 
     38 Dataset metadata and package count, intended for dashboard stats bars.
     39 
     40 ```bash
     41 curl https://notamitgamer-osma-npm-api.hf.space/stats
     42 ```
     43 
     44 ```json
     45 {
     46   "total_npm_packages": 3881465,
     47   "source": "npmjs.com",
     48   "note": "Snapshot dataset — updated periodically."
     49 }
     50 ```
     51 
     52 ## GET /browse
     53 
     54 Paginated package list, ordered by `package_no`.
     55 
     56 | Parameter | Type | Default | Max | Required | Description |
     57 |---|---|---|---|---|---|
     58 | `page` | integer | 1 | — | optional | Page number, 1-indexed |
     59 | `limit` | integer | 200 | 500 | optional | Rows per page |
     60 
     61 ```bash
     62 curl "https://notamitgamer-osma-npm-api.hf.space/browse?page=1&limit=5"
     63 ```
     64 
     65 ```json
     66 {
     67   "page": 1,
     68   "limit": 5,
     69   "results": [
     70     { "no": 1, "name": "--123hoodmane-pyodide", "version": "latest", "url": "https://www.npmjs.com/package/..." }
     71   ]
     72 }
     73 ```
     74 
     75 ## GET /search
     76 
     77 Ranked search across all packages. Results are ranked by match quality — exact match (`0`) first, starts-with (`1`) second, contains (`2`) last — then sorted alphabetically within each rank.
     78 
     79 | Parameter | Type | Default | Max | Required | Description |
     80 |---|---|---|---|---|---|
     81 | `q` | string | — | 100 chars | required | Search query, min 2 characters |
     82 | `limit` | integer | 250 | 500 | optional | Max results to return |
     83 
     84 ```bash
     85 curl "https://notamitgamer-osma-npm-api.hf.space/search?q=react&limit=5"
     86 ```
     87 
     88 ```json
     89 {
     90   "query": "react",
     91   "count": 250,
     92   "results": [
     93     { "no": 42, "name": "react", "version": "18.3.1", "url": "...", "rank": 0 },
     94     { "no": 88, "name": "react-dom", "version": "18.3.1", "url": "...", "rank": 1 }
     95   ]
     96 }
     97 ```
     98 
     99 <Copyright />