notes.md - docs -

notes.md (3992B)
      1 ---
      2 label: Notes & FAQ
      3 icon: question
      4 order: 500
      5 ---
      6 
      7 # Notes & Reference
      8 
      9 ## Limits & notes
     10 
     11 **Rate limits** — APIs are strictly rate-limited to 10 requests/minute and 100 requests/hour per IP to protect the free-tier infrastructure. Send the `X-Bypass-Token` header to override this.
     12 
     13 **Data freshness** — both datasets are snapshots. NPM was frozen `2026-04-29 09:42 IST`, PyPI `2026-04-29 08:45 IST`. Packages published after these dates aren't indexed.
     14 
     15 **CORS** — both APIs have `Access-Control-Allow-Origin: *`, so you can call them directly from any browser-based frontend with no proxy needed.
     16 
     17 **Cold starts** — on first boot after a deployment, each server downloads its dataset and builds a SQLite index (~1 min). `/health` returns `503` during this window. UptimeRobot prevents this in normal operation.
     18 
     19 ## Response schema
     20 
     21 `results` arrays from `/browse` or `/search` contain objects with:
     22 
     23 | Field | Type | Description |
     24 |---|---|---|
     25 | `no` | integer | Stable, sequential ID/rank of the package within the snapshot database |
     26 | `name` | string | The exact, registered name of the package |
     27 | `version` | string | Version string available at the time the snapshot was taken |
     28 | `url` | string | Absolute link to the package on the official registry website |
     29 | `rank` | integer | *(`/search` only)* Match quality: `0` exact, `1` starts-with, `2` contains |
     30 
     31 ## Common errors
     32 
     33 **`404` Not Found** — the API URL path is incorrect or misspelled (e.g. `/searc` instead of `/search`).
     34 
     35 **`422` Unprocessable Entity** — `/search` was called without the required `q` parameter, or the query was under 2 characters.
     36 
     37 **`429` Too Many Requests** — you exceeded the 10/min or 100/hour rate limit. The response includes a `Retry-After` header.
     38 
     39 **`503` Service Unavailable** — the server was asleep (cold start) and is downloading the dataset / building its SQLite index. Normal on free-tier hosting; usually resolves within a minute.
     40 
     41 !!!warning Still having trouble?
     42 If you're seeing continuous `500` errors or found a bug, [open an issue on GitHub](https://github.com/notamitgamer/osma/issues) or email [mail@amit.is-a.dev](mailto:mail@amit.is-a.dev).
     43 !!!
     44 
     45 ## FAQ
     46 
     47 **What exactly is OSMA?**
     48 A heavily optimized, static API serving historical snapshots of the NPM and PyPI registries — search packages and view base version data instantly without live registry rate limits or CAPTCHAs.
     49 
     50 **Why can't I find a recently published package?**
     51 The datasets are frozen snapshots from April 29, 2026. Anything published, renamed, or deleted after that date won't appear.
     52 
     53 **Is there rate limiting?**
     54 Yes — 10 requests/minute and 100/hour per IP via SlowAPI. Open a GitHub issue to request an `X-Bypass-Token` if you need it disabled.
     55 
     56 **Do I need an API key?**
     57 No — the APIs are fully open and require no authentication for standard usage within the rate limits.
     58 
     59 **Can I use this in a frontend app directly?**
     60 Yes — both APIs have open CORS (`Access-Control-Allow-Origin: *`), so browser apps can fetch directly with no proxy.
     61 
     62 **What does the `rank` field mean?**
     63 `0` = exact match, `1` = starts with the query, `2` = contains the query somewhere in the name.
     64 
     65 **Why does `/health` sometimes return 503?**
     66 The server went to sleep from inactivity. On waking (a "cold start") it needs 1–2 minutes to download the CSV snapshot and rebuild its index — it returns `503` while loading.
     67 
     68 **How many packages are indexed?**
     69 Roughly 3.88 million NPM packages and 793,000 PyPI packages as of the current snapshots. Check `/stats` for exact live numbers.
     70 
     71 **Are other registries (RubyGems, Cargo) planned?**
     72 The current focus is strictly NPM and PyPI; other ecosystems may be considered with enough demand.
     73 
     74 **How do I report a bug or vulnerability?**
     75 General bugs/UI issues → [open a GitHub issue](https://github.com/notamitgamer/osma/issues). Security vulnerabilities → email [mail@amit.is-a.dev](mailto:mail@amit.is-a.dev) directly instead of filing a public issue.
	docs
	Log \| Files \| Refs \| Activity