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