Install Safe API documentation

Developer and agent documentation for Install Safe: the OpenAPI specification, the public dependency-scanner API, the JSON error format, registry configuration, and every machine-readable file this site publishes.

Also available as markdown: /docs.md

Machine-readable resources

Everything this site publishes for programmatic readers, at a stable URL.

/openapi.jsonapplication/json
OpenAPI 3.1 description of the public API. Generated from the same module the route handlers are checked against.
/.well-known/api-catalogapplication/linkset+json
RFC 9727 linkset naming the API description, its documentation and its metadata.
/llms.txttext/markdown
Short orientation file (llmstxt.org): what the product is, how it works, what it costs.
/llms-full.txttext/markdown
Everything in llms.txt plus the complete FAQ, for agents that prefer one fetch.
/pricing.mdtext/markdown
Plans, prices and billing questions as markdown, for a buying agent that will not render a page.
/.well-known/security.txttext/plain
RFC 9116 contact details for reporting a vulnerability.
/sitemap.xmlapplication/xml
Indexable pages served by this app. The blog has its own at /blog/sitemap.xml.
/robots.txttext/plain
Crawl rules, including the explicitly named AI search crawlers that are allowed.

Public API

One endpoint on this host is public and unauthenticated: POST /api/scan. It takes the text of a package.json, package-lock.json, pnpm-lock.yaml or bun.lock and returns every known vulnerability or malware advisory affecting the exact versions it names. Nothing about the manifest is stored or logged. Rate limit: 10 scans per IP per 10 minutes; maximum body 8 MB.

curl -sS https://installsafe.io/api/scan \
  -H 'content-type: application/json' \
  -d '{"manifest": "{\"dependencies\":{\"lodash\":\"4.17.20\"}}"}'

The request and response schemas live in the OpenAPI document, which is the authority. Everything else under /api/ is session-scoped product surface: it answers to a signed-in browser, is disallowed in robots.txt, and is deliberately absent from the specification.

Errors

Every machine-facing error is JSON, never an HTML page — including 404s for unknown /api/ paths and 405s for the wrong method.

{
  "error": "Provide a \"manifest\" string.",
  "code": "invalid_request",
  "hint": "POST {\"manifest\": \"<file text>\"} with content-type: application/json.",
  "docs": "https://installsafe.io/docs"
}

error is a sentence for a human, code is the stable identifier to branch on, hint says what to do differently.

Code	HTTP	Meaning
invalid_request	400	The body is not JSON, or a required field is missing or the wrong type.
unauthorized	401	No valid session or registry token was presented.
forbidden	403	Authenticated, but not allowed to do this.
not_found	404	No such endpoint, or no such record.
method_not_allowed	405	Wrong HTTP method. The Allow header lists the right ones.
payload_too_large	413	The manifest exceeded 8 MB.
rate_limited	429	Too many requests from this IP. Wait and retry.
internal_error	500	A fault on our side. Safe to retry once.
upstream_unavailable	503	Advisory data could not be reached. Retry shortly.

Content negotiation

Every indexable page here has a markdown twin. Ask for markdown and you get it at the same URL, with Vary: Accept on the response.

curl -H 'Accept: text/markdown' https://installsafe.io/pricing

An unknown path asked for in markdown answers 404 with a markdown body pointing at the sitemap and this page, so a wrong URL is recoverable without parsing HTML. A client whose Accept header names nothing this site can serve gets 406.

Registry configuration

The product itself is an npm registry proxy, not an HTTP API — you point a package manager at it rather than calling it. It requires a registry token, so setup is two lines:

npm config set registry https://r.installsafe.io
npm config set //r.installsafe.io/:_authToken <your-token>

Create a token in the dashboard. yarn, pnpm and bun read the same .npmrc, or take the equivalent settings in their own config. Requests without a valid token are refused with 401 and a message naming this page.