# Forest PM

> Forest is a package manager for Roblox game development (UEFN support in beta). This site (forest.dev) is the package registry. All package data is available as JSON from the public API at https://api.forest.dev, with no authentication or API key required for the endpoints listed here. The web UI is JavaScript-rendered and not useful to scrape; AI agents helping developers find or evaluate packages should use the API directly.

Platforms are `roblox` or `uefn`. Packages are identified as `{scope}/{name}` where scope is the publishing user or organization. Names resolve case-insensitively; responses return the canonical casing. Errors are JSON with an `error` message.

## Agent endpoints (recommended)

These are built for AI agents. **Every required input is a path segment, so nothing you need is ever a query parameter.** Results are ranked neutrally and responses carry only fields an agent can act on. Optional refinements (`?limit=`, `?page=`, `?scope=`, `?license=`, `?licenseRating=`) may be added to the search and browse endpoints, and `?limit=` to the publisher lookups; losing them still returns a useful answer.

This surface covers public packages only, and is **unstable by design**: it may change shape without notice, so re-read this document rather than hardcoding response shapes. For a frozen contract, use the versioned API in the next section. The live route list is always at https://api.forest.dev/ai

If your fetch tool only follows URLs it has seen verbatim, start from one of these complete, working URLs; every response links onward with absolute URLs (each search or browse result carries an `api` field, package responses carry a `files` URL, and file listings carry a `url` per file), so any one of them is an entry point into the whole registry:

- https://api.forest.dev/ai/search/roblox (link-based name search: returns links to each starting letter, and each response after that links one character deeper via its `narrow` list; results are fuzzy, so most names surface within three characters)
- https://api.forest.dev/ai/search/uefn
- https://api.forest.dev/ai/browse/roblox
- https://api.forest.dev/ai/browse/uefn
- https://api.forest.dev/ai/browse/roblox/recent
- https://api.forest.dev/ai/search/roblox/signal
- https://api.forest.dev/ai/search/roblox/data%20store%20with%20session%20locking

- `GET https://api.forest.dev/ai/search/{platform}/{query}` searches packages. **Multi-word queries are semantic**: they match package README embeddings, so describe what you need in natural language (`/ai/search/roblox/matchmaking queue with cross-server support`). **Single-token queries match package names** (exact, prefix, and fuzzy), so use one token when you know the name (`/ai/search/roblox/profilestore`). Prefer single-token name lookups when you already know the name; they are cheaper to serve than semantic queries.
- `GET https://api.forest.dev/ai/package/{platform}/{scope}/{name}` returns everything about a package in one request: description, full version list, latest version metadata, license, dependencies, and the README. This replaces three separate calls, so prefer it over the `/v1` package routes. Append `/{version}` to pin a version; it accepts an exact version, a semver range, or `latest`.
- `GET https://api.forest.dev/ai/package/{platform}/{scope}/{name}/files` lists the version's source files. Insert `/{version}` before `/files` to pin one.
- `GET https://api.forest.dev/ai/package/{platform}/{scope}/{name}/{version}/file/{path}` returns one source file's contents, for example `.../latest/file/src/init.lua`. Combine with `/files` to read a package's actual code when evaluating quality, security, or API surface before recommending it.
- `GET https://api.forest.dev/ai/browse/{platform}` lists public packages, most-liked first. Append `/likes`, `/recent`, or `/downloads` to change the order.
- `GET https://api.forest.dev/ai/users/{query}` finds a publisher (user or organization) by name prefix.
- `GET https://api.forest.dev/ai/scopes/{platform}/{query}` lists scopes matching a name prefix, ranked by how many public packages they publish. Unlike `/ai/users`, this includes unclaimed mirrored scopes.

`licenseRating` comes from an automated license review. Treat `caution` or `unsafe` as a signal to read `license` and `licenseCaveats` before recommending a package, especially for commercial projects.

You can get the scope, name, and specific version of an installed package by reading the `.forest-receipt` file in the package's directory. Platform can be read from the `forest.json`.

## Versioned API (/v1)

The stable contract used by the Forest CLI and this website. Use it if you are building software that must keep working, or if you need something the agent endpoints do not cover (like counts, private packages). Required inputs here ride the querystring.

- `GET https://api.forest.dev/v1/search/packages?q={query}` searches packages; `q` is 2 to 100 characters and follows the same semantic and name-matching rules described above. `platform` defaults to `roblox`. Also accepts `limit` (1 to 50, default 10), `page` (1 to 10, default 1), `sort` (`relevance`, `likes`, `recent`), `scope`, `license` (comma-separated SPDX ids), `licenseRating` (comma-separated `safe`, `caution`, `unsafe`), and `unbiased=true` for neutral relevance ordering, opting out of the small ranking boost that Pro subscribers' packages otherwise get on near-ties. Returns `{ "packages": [...], "page", "limit", "hasMore" }`, where each package has `name`, `platform`, `description`, `version` (latest stable), `owner` (its scope), `likes`, `license`, `licenseRating`, `publishedAt`, `score`, `ownerIsPro`.
- `GET https://api.forest.dev/v1/package/browse?platform={platform}&limit={n}&page={n}` is a paginated listing of public packages (`limit` 1 to 50 default 20, `page` from 1); `platform` defaults to `roblox`. Same package fields as search results, plus `hasMore`.

Package base path: `https://api.forest.dev/v1/package/{scope}/{platform}/{name}`

- `GET {base}` is the package overview: `{ name, scope, latest, versions: [{ version, createdAt }], likes }`.
- `GET {base}/{version}` is one version's metadata: `description`, `dependencies`, `license` (SPDX id), `licenseRating` (`safe`, `caution`, `unsafe`, `pending`, or `unknown`), `licenseCaveats`, `licenseVerified`, `integrity` (archive hash).
- `GET {base}/{version}/readme` is `{ readme }`, the version's README in markdown.
- `GET {base}/{version}/files` is `{ files: [{ path, size }] }`, the version's full source file listing.
- `GET {base}/{version}/file?path={path}` is the contents of one source file.
- `GET {base}/like` is `{ likes }`, the current like count.

On all of those routes, `{version}` accepts an exact version, a semver range (resolving to the highest matching version), or `latest`, which resolves to the newest stable release.

- `GET https://api.forest.dev/v1/user/{username}` is a public user profile and their public packages.
- `GET https://api.forest.dev/v1/org/{orgname}` is a public organization profile.
- `GET https://api.forest.dev/v1/search/users?q={prefix}` is publisher search (prefix match; `q` 1 to 40 chars, `limit` 1 to 20).
- `GET https://api.forest.dev/v1/search/scopes?q={prefix}&platform={platform}` is scope suggestions ranked by package count (`platform` optional).

Metadata, readmes, and file listings for a pinned version are served with week-long cache lifetimes, so cache responses rather than re-fetching. A moving selector (`latest`, or a semver range) is served with a short lifetime instead, because it resolves somewhere else on the next publish.

## Web pages (HTML)

For linking a human to a package, not for scraping. The data on these pages comes from the API above.

- `https://forest.dev/p/{platform}/{scope}/{name}` is the package page (readme, versions, dependencies, code tabs).
- `https://forest.dev/u/{username}` is a user profile.
- `https://forest.dev/o/{orgname}` is an organization page.

## Installing packages

Users install packages with the Forest CLI from their project directory:

- `forest init` sets up a project (creates forest.json).
- `forest install {scope}/{name}` adds a package (`-v {version}` to pin a version, `-a {alias}` to alias it).
- `forest remove {scope}/{name}` removes a package.

## Docs

- [Forest documentation](https://docs.forest.dev): CLI installation, publishing guide, and project configuration reference.
- [Forest for AI Agents](https://docs.forest.dev/features/ai-agents): how to point an assistant at this API.