notes.mdx - docs -

notes.mdx (4057B)
      1 ---
      2 title: "Notes & Reference"
      3 sidebarTitle: "Notes & FAQ"
      4 ---
      5 
      6 import Copyright from "/snippets/copyright.mdx";
      7 
      8 ## Limits & notes
      9 
     10 **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.
     11 
     12 **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.
     13 
     14 **CORS** — both APIs have `Access-Control-Allow-Origin: *`, so you can call them directly from any browser-based frontend with no proxy needed.
     15 
     16 **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.
     17 
     18 ## Response schema
     19 
     20 `results` arrays from `/browse` or `/search` contain objects with:
     21 
     22 | Field | Type | Description |
     23 |---|---|---|
     24 | `no` | integer | Stable, sequential ID/rank of the package within the snapshot database |
     25 | `name` | string | The exact, registered name of the package |
     26 | `version` | string | Version string available at the time the snapshot was taken |
     27 | `url` | string | Absolute link to the package on the official registry website |
     28 | `rank` | integer | *(`/search` only)* Match quality: `0` exact, `1` starts-with, `2` contains |
     29 
     30 ## Common errors
     31 
     32 **`404` Not Found** — the API URL path is incorrect or misspelled (e.g. `/searc` instead of `/search`).
     33 
     34 **`422` Unprocessable Entity** — `/search` was called without the required `q` parameter, or the query was under 2 characters.
     35 
     36 **`429` Too Many Requests** — you exceeded the 10/min or 100/hour rate limit. The response includes a `Retry-After` header.
     37 
     38 **`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.
     39 
     40 <Warning>
     41 **Still having trouble?**
     42 
     43 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).
     44 </Warning>
     45 
     46 ## FAQ
     47 
     48 **What exactly is OSMA?**
     49 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.
     50 
     51 **Why can't I find a recently published package?**
     52 The datasets are frozen snapshots from April 29, 2026. Anything published, renamed, or deleted after that date won't appear.
     53 
     54 **Is there rate limiting?**
     55 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.
     56 
     57 **Do I need an API key?**
     58 No — the APIs are fully open and require no authentication for standard usage within the rate limits.
     59 
     60 **Can I use this in a frontend app directly?**
     61 Yes — both APIs have open CORS (`Access-Control-Allow-Origin: *`), so browser apps can fetch directly with no proxy.
     62 
     63 **What does the `rank` field mean?**
     64 `0` = exact match, `1` = starts with the query, `2` = contains the query somewhere in the name.
     65 
     66 **Why does `/health` sometimes return 503?**
     67 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.
     68 
     69 **How many packages are indexed?**
     70 Roughly 3.88 million NPM packages and 793,000 PyPI packages as of the current snapshots. Check `/stats` for exact live numbers.
     71 
     72 **Are other registries (RubyGems, Cargo) planned?**
     73 The current focus is strictly NPM and PyPI; other ecosystems may be considered with enough demand.
     74 
     75 **How do I report a bug or vulnerability?**
     76 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.
     77 
     78 <Copyright />