rgstr API
Everything the site shows is available over HTTP, and most of it needs no account. Machine-readable versions: OpenAPI 3.1, llms.txt. Every error is JSON with error, code, hint and requestId.
Base URL and conventions
Base URL https://rgstr.org. Responses are JSON unless the endpoint says otherwise. Scoped npm names go in the path as @scope/name with the slash encoded (%2F) or as two segments. Public endpoints are cacheable for 30–60 s. There is no API key for reading.
Errors look like this, with a stable code to branch on and a hint that is the next step — follow it. The codes are listed in llms.txt and on the Error schema in /openapi.json:
{
"error": "Invalid package name",
"code": "invalid_name",
"message": "Invalid package name",
"hint": "Use a package name (`left-pad`, `@scope/pkg`) or a scope (`@scope` or `@scope/*`)",
"requestId": "req_3f9c…"
}Authentication
Reading (whois, search, install, badges) is public. Claiming names for an organization needs a bearer token: Authorization: Bearer <token>. The token comes from rgstr login (device flow: the CLI prints a code, you approve it at /device in a browser, signed in with GitHub, Google or email; sign-up is self-serve and free). The no-account path is POST /api/registry/claim-requests, which needs no token.
npx @rgstr/cli@latest login
npx @rgstr/cli@latest claim left-pad
npx @rgstr/cli@latest whois left-padFor coding agents
Start at llms.txt; every page here is Markdown with Accept: text/markdown. The rgstr agent skill is the CLI's three flows (claim a name, check a project's dependencies, read without an account) written for an agent, with the rule that matters: show the user the plan and get their confirmation before filing a claim, writing a README, opening a pull request, changing routes or editing .npmrc / pip.conf; reading needs none (rgstr claim --check is not a read: it records the proof for a claim the user already confirmed). Add it to a project with the skills CLI:
npx skills add computesdk/rgstr --skill rgstrAn agent without a shell gets the same flows as MCP tools from `@rgstr/mcp`: reads (rgstr_whois, rgstr_search, rgstr_check), then plan → apply pairs for claim, setup and routes. A _plan tool changes nothing and returns a plan_id; the matching _apply tool takes only that plan_id, and answers plan_stale if anything changed since. Claude Desktop, Cursor, Devin and any other MCP client take this configuration:
{
"mcpServers": {
"rgstr": {
"command": "npx",
"args": ["-y", "@rgstr/mcp"]
}
}
}Pointing npm and pip at rgstr
One setting per client. Unclaimed names fall through to the index unchanged; claimed names resolve to the claimant's package.
npm config set registry https://rgstr.org/api/registry/
pip config set global.index-url https://rgstr.org/api/pypi/simple/Endpoints
Each endpoint below links to its OpenAPI operation by operationId.
GET/api/v1/registry/whois/{name}public
Who has claimed a package name
The name page as JSON: trust level (unclaimed, claimed, verified), state (unclaimed, pending, held — the JSON value for a claimed name), the claiming organization (holder) with its public profile URL, where installs of the name are served from, and relationship — what an unclaimed name is relative to another package, the way search labels it (copy of tsc-rs, a sibling build, a namesake), with the claiming organization behind the original when there is one. Public; no auth. Start here when an agent needs to know whether a package name is claimed and by whom, or whether it is a copy of something else.
name(path, required): Package name. Scoped npm names are@scope/name(URL-encode the slash as%2F, or send two path segments).
curl -sS https://rgstr.org/api/v1/registry/whois/left-padoperationId whoisPackage in /openapi.json
GET/api/registry/-/v1/searchpublic
Search names across npm and PyPI, claimed names first
npm's search response shape (objects[].package, total) so npm search reads it unchanged, reordered so claimed names rank above look-alikes, with an rgstr block per object carrying ecosystem, trust, owner (the claiming organization's slug), tier and demotion. q is an alias for text. Public; no auth.
text(query): Search text (npm's parameter name).q(query): Alias fortext.size(query): Page size, 1–100.from(query): Offset.ecosystem(query): Restrict to one index.
curl -sS 'https://rgstr.org/api/registry/-/v1/search?text=left-pad&size=5'operationId searchPackages in /openapi.json
GET/api/registry/{name}public
npm packument for a name (what `npm install` reads)
The npm registry document for the name, fetched from registry.npmjs.org and passed through with tarball URLs pointed at rgstr so each download answers with a redirect to the real file. This is the endpoint npm config set registry https://rgstr.org/api/registry/ makes npm talk to. Append /{version} for one version. Public; no auth.
name(path, required): Package name. Scoped npm names are@scope/name(URL-encode the slash as%2F, or send two path segments).
curl -sS https://rgstr.org/api/registry/left-pad | head -c 400operationId getNpmPackument in /openapi.json
GET/api/pypi/simple/{name}/public
PyPI simple index for a name (what `pip install` reads)
PEP 503 HTML or PEP 691 JSON (by Accept) for the project, fetched from pypi.org with file URLs pointed at rgstr. This is what pip config set global.index-url https://rgstr.org/api/pypi/simple/ makes pip talk to. Public; no auth.
name(path, required): PyPI project name (PEP 503 normalized).
curl -sS -H 'Accept: application/vnd.pypi.simple.v1+json' https://rgstr.org/api/pypi/simple/requests/ | head -c 400operationId getPypiSimple in /openapi.json
GET/registry/{name}/badge.svgpublic
Trust badge for a name (SVG)
An SVG badge reading unclaimed, claimed or verified for the name. A maintainer puts it in their README; with ?proof=<token> in its URL it is the proof of a claim — rgstr looks for that line in the README it reads (the GitHub repository the package declares, or the README that ships with the package). Public; no auth.
name(path, required): Package name. Scoped npm names are@scope/name(URL-encode the slash as%2F, or send two path segments).
curl -sS https://rgstr.org/registry/left-pad/badge.svgoperationId getRegistryBadge in /openapi.json
POST/api/registry/claim-requestspublic
Ask to claim a name without an account
The public claim form. Give the name, the GitHub username of a maintainer and the package's GitHub repository; rgstr opens an application and answers with the badge to put in the README; once the badge is found a person reviews the application. For a @scope/* claim, proofPackage names the package inside the scope whose README carries the badge. No auth; rate limited per IP. Agents acting for a signed-in maintainer should use POST /api/v1/registry/claims instead.
curl -sS -X POST https://rgstr.org/api/registry/claim-requests -H 'content-type: application/json' -d '{"name":"left-pad","githubUsername":"octocat","repoUrl":"https://github.com/octocat/left-pad"}'operationId submitClaimRequest in /openapi.json
GET/api/v1/registry/claimsbearer token
The signed-in organization's claims
The organization's pending applications (with their badge snippets) under pending, and the names it claims under held (the JSON key for claimed names). Bearer token from rgstr login (device flow at https://rgstr.org/device).
curl -sS -H "Authorization: Bearer $RGSTR_TOKEN" https://rgstr.org/api/v1/registry/claimsoperationId listClaims in /openapi.json
POST/api/v1/registry/claimsbearer token
Claim a name (what `rgstr claim <name>` calls)
Files an application for the signed-in organization and returns the proof to add: the rgstr badge as Markdown, with a token. Put it under the first heading of the README rgstr reads — the GitHub repository the package declares, or the README that ships with the package — then POST …/check-proof (what rgstr claim --check calls); a person reviews the application. A name another organization already claims is filed too (201, with dispute) and is reviewed, not shown publicly. Bearer token required.
curl -sS -X POST -H "Authorization: Bearer $RGSTR_TOKEN" -H 'content-type: application/json' -d '{"name":"left-pad"}' https://rgstr.org/api/v1/registry/claimsoperationId createClaim in /openapi.json
POST/api/v1/registry/claims/{requestId}/check-proofbearer token
Look for a pending claim's badge and record it
Reads the README rgstr reads — the GitHub repository the package declares, and the README published on npm / PyPI — for the badge with this application's token, and records what it found on the application; a person then decides (what rgstr claim --check <name> calls). Not a read: it changes the application. Bearer token required.
requestId(path, required): The claim request id fromcreateClaim.
curl -sS -X POST -H "Authorization: Bearer $RGSTR_TOKEN" https://rgstr.org/api/v1/registry/claims/<requestId>/check-proofoperationId checkClaimProof in /openapi.json