Traps API

GET /api/traps returns the same trap text as the MCP tool, for hooks, shell scripts, and CI.

Not every place you want a trap warning is an MCP client. A shell hook, a CI step, and a pre-commit script all want one request and some text. That is this endpoint.

one request

curl "https://mcp.wellworn.dev/api/traps?library=better-auth&version=1.7.3"

Parameter	Required	Notes
`library`	yes	Package name, slug, or display name. Trimmed and cut at 80 characters.
`version`	no	Narrows to traps whose semver range covers this version. Cut at 40 characters.

The response is text/plain, byte for byte the text the traps tool returns, minus the remaining: line the MCP appends:

TRAPS Better Auth 1.7.3 (2)
  [622e042e] major >=1.0.0: Role or plan changes do not reach the session until the cookie cache expires (default 5 minutes).
  [90232128] minor >=1.0.0: Drizzle adapter cannot find plugin tables (organization, apikey) and fails at runtime, not at build.
pass id for the full fix

There is no id parameter here. One trap in full is an MCP call.

Status codes

Code	Body	Meaning
`200`	The trap text	Traps found, or the library is known and has none verified for that range.
`204`	empty	The library is not in the corpus, so a hook can stay silent.
`400`	`library is required`	The parameter was missing or blank. Checked before anything else, so it costs no call.
`401`	`invalid key`	An `Authorization` header carried a token that does not resolve to a key.
`429`	the limit line	The window is spent.

Separating 204 from 200 is what makes this useful in a hook. 204 means Wellworn has nothing on this package at all; a 200 reading none verified for this range means the package is tracked and your range is clean, which is a stronger statement.

A real refusal, captured today:

$ curl -i "https://mcp.wellworn.dev/api/traps?library=better-auth"
HTTP/2 429
limit reached: no-key 60/60 today (resets 2026-09-09T00:00:00.000Z). Free key or plans: https://wellworn.dev/pricing

In a hook

.git/hooks/pre-commit

traps=$(curl -fsS "https://mcp.wellworn.dev/api/traps?library=$pkg&version=$ver")
[ -n "$traps" ] && printf '%s\n' "$traps"

curl -fsS turns the 400 and 429 into a non-zero exit and prints nothing on 204, so the hook only speaks when there is something to say. Add -H "authorization: Bearer $WELLWORN_KEY" to spend your organization's allowance instead of the anonymous one.

Caching and limits

The endpoint sends cache-control: no-store, so a new trap or a recheck flag reaches you on the next call rather than after a cache expires. It shares one limiter with the MCP tools: the same 60 calls a day per address without a key, the same monthly cap with one, counted in the same counter. Ten calls in a hook are ten calls off the tools. Limits has the numbers.