# rgstr

> rgstr is a package name registry over npm and PyPI. Maintainers claim a package name and prove it with the rgstr badge in their README; a person reviews every claim. Developers point npm or pip at rgstr once and every install resolves to the real package, with copies ranked below it. Unclaimed names fall through to npm and PyPI unchanged.

rgstr.org is a package name registry over npm and PyPI, run by ComputeSDK (Snelling, LLC). Every page here has a Markdown rendering: send `Accept: text/markdown`. Unknown paths return a real 404 (Markdown or JSON by `Accept`). API errors are JSON with `code`, `hint` and `requestId`.

## When to use rgstr

- You are about to install, recommend or depend on a package and want to know whether its name is claimed by its real maintainer, or is a look-alike or a copy: `GET /api/v1/registry/whois/{name}`.
- You are searching for a package by name and want claimed names ranked above squatted or copied ones: `GET /api/registry/-/v1/search?text=…`, or `npm search` against rgstr.
- You are setting up a project or CI and want every `npm install` / `pip install` to resolve a claimed name to the real package: point the client at rgstr once (see the API page). Unclaimed names fall through to npm and PyPI unchanged, so this is safe to do for everything.
- You maintain a package and want to claim its name: `rgstr claim <name>` (`npx @rgstr/cli@latest claim <name>`), or `POST /api/registry/claim-requests` without an account. Proof is the rgstr badge in the README; a person reviews every claim.

## Not for

- Malware or quality scanning: rgstr does not read package code. It answers who has claimed a name and how that was proved.
- Hosting packages: rgstr stores no files. Installs are redirected to the index that publishes them.
- Private registries: every name on rgstr is a public npm or PyPI name.

## How to call it

- No key for reading. `GET https://rgstr.org/api/v1/registry/whois/<name>` answers who has claimed a name; `GET https://rgstr.org/api/registry/-/v1/search?text=<q>` searches with claimed names first.
- Install through it: `npm config set registry https://rgstr.org/api/registry/` and `pip config set global.index-url https://rgstr.org/api/pypi/simple/`. Unclaimed names fall through to the index unchanged.
- Claim a name: `npx @rgstr/cli@latest login` then `npx @rgstr/cli@latest claim <name>` (self-serve, free); or `POST https://rgstr.org/api/registry/claim-requests` with no account. Proof is the rgstr badge in a README rgstr reads (the GitHub repository the package declares, or the package's own); a person reviews every claim.
- Before anything that changes state — filing a claim (`rgstr claim`, `POST /api/v1/registry/claims`, `POST /api/registry/claim-requests`), editing a README or opening a pull request, changing routes, or editing .npmrc / pip.conf (`rgstr setup`) — show the user the plan and get their confirmation first. Reading (whois, search, `rgstr check`, Markdown pages) needs none. `rgstr claim --check` is not a read: it records the proof for a claim the user already confirmed.

## Agent skills

Follow a skill by reading its link, or add it to a project with the [skills CLI](https://skills.sh/docs/cli) using its `Install:` line.

- [rgstr](https://rgstr.org/skills/rgstr/SKILL.md): Claims a package name on rgstr.org (npm or PyPI) with the README badge, checks which of a project's dependencies are claimed, and routes installs through rgstr. Use when the user maintains a package and wants its name claimed, asks who claims a name, or wants npm / pip installs to resolve claimed names to the real package. Install: `npx skills add computesdk/rgstr --skill rgstr`
- [@rgstr/mcp](https://github.com/computesdk/rgstr/tree/main/packages/mcp): the same flows as MCP tools for an agent without a shell — `npx -y @rgstr/mcp` (Claude Desktop, Cursor, Devin). Reads, then plan → apply: `_apply` takes only the `plan_id` a `_plan` tool returned and answers `plan_stale` if anything changed since.

## Docs

- [API reference](https://rgstr.org/registry/-/api): endpoints, auth, examples
- [OpenAPI 3.1 spec](https://rgstr.org/openapi.json): every operation with operationId, typed params and response schemas
- [About rgstr](https://rgstr.org/registry/-/about): what it is, what it is not, who runs it
- [Why rgstr](https://rgstr.org/registry/-/why): trust levels, what a claim changes, downtime, logs, disputes
- [Contact](https://rgstr.org/registry/-/contact): support, disputes, security (support@computesdk.com)
- [Claim a package](https://rgstr.org/registry/claim): the form and the CLI
- [rgstr CLI source](https://github.com/computesdk/rgstr): `npx @rgstr/cli@latest` — login, claim, setup, check, whois, search
- [Sitemap](https://rgstr.org/sitemap.xml)

## API

- [GET /api/v1/registry/whois/{name}](https://rgstr.org/api/v1/registry/whois/): Who has claimed a package name
- [GET /api/registry/-/v1/search](https://rgstr.org/api/registry/-/v1/search): Search names across npm and PyPI, claimed names first
- [GET /api/registry/{name}](https://rgstr.org/api/registry/): npm packument for a name (what `npm install` reads)
- [GET /api/pypi/simple/{name}/](https://rgstr.org/api/pypi/simple/): PyPI simple index for a name (what `pip install` reads)
- [GET /registry/{name}/badge.svg](https://rgstr.org/registry/badge.svg): Trust badge for a name (SVG)
- [POST /api/registry/claim-requests](https://rgstr.org/api/registry/claim-requests): Ask to claim a name without an account
- [GET /api/v1/registry/claims](https://rgstr.org/api/v1/registry/claims): The signed-in organization's claims (bearer token)
- [POST /api/v1/registry/claims](https://rgstr.org/api/v1/registry/claims): Claim a name (what `rgstr claim <name>` calls) (bearer token)
- [POST /api/v1/registry/claims/{requestId}/check-proof](https://rgstr.org/api/v1/registry/claims/check-proof): Look for a pending claim's badge and record it (bearer token)

## Errors

Every error is JSON: `{ error, code, message, hint, requestId }`. `code` is stable; branch on it. `hint` is the next step (often with a URL); follow it, and show `error` to the user. Codes the registry returns:

- `not_signed_in` (401): The request carried no usable token.
- `not_a_member` (403): The token is valid but its user is not a member of the organization.
- `no_organization` (403): The token is a user's and names no organization to act for.
- `not_an_admin` (403): The user is a member but only owners and admins may change the organization's names.
- `insufficient_scope` (403): The token's scopes do not cover this operation.
- `status_not_settable` (403): A name becomes claimed when its claim is approved, never by setting a status.
- `invalid_name` (400): The name is neither a package name nor a scope.
- `proof_package_required` (400): A scope claim needs one published package inside the scope to carry the badge.
- `invalid_repo_url` (400): repoUrl is not a GitHub repository URL.
- `invalid_field` (400): A body field has the wrong shape; `error` names it.
- `name_unknown` (404): No npm or PyPI package has this name, and nobody has claimed it.
- `claim_not_found` (404): No claim request with this id belongs to the organization.
- `package_not_found` (404): No package with this id belongs to the organization.
- `claim_pending` (409): A claim for this name is already under review.
- `claim_closed` (409): This claim request was already decided.
- `already_yours` (409): Your organization already has this name — claimed, or under review; there is nothing to file.
- `claimed_by_other` (409): Another organization has claimed this name.
- `proof_not_found` (422): The README rgstr read does not carry the organization's badge yet.

## Optional

- [llms-full.txt](https://rgstr.org/llms-full.txt): every page above in one Markdown file
- [Privacy](https://www.computesdk.com/privacy) and [terms](https://www.computesdk.com/terms) on computesdk.com cover rgstr.org
- [ComputeSDK](https://www.computesdk.com/): the company behind rgstr