docs agent published internal-only endpoints in the public api docs
Fixes a docs agent that leaked internal endpoints into public API documentation. The skill shows how to audit the exposure, mark internal operations, and filter them from the public spec. It gives the tagging convention that keeps internal and public surfaces separate.
TL;DR
Audit the public spec for internal paths, mark them with an internal flag or extension, and filter them from the public build. Regenerate and verify no internal endpoints remain. Treat the exposure as an incident: check access logs for usage.
The exact error
docs agent published internal endpoints publiclySteps
Audit the public spec Diff the public spec against the internal one and list every endpoint that should not be public. Success check: You have the full list of exposed internal endpoints.
Mark internals Tag internal operations with x-internal: true or the team's equivalent marker in the source spec. Success check: Every internal operation carries the marker.
Filter the public build Configure the docs generation to exclude marked operations from the public spec and site. Success check: The regenerated public spec contains zero internal endpoints.
Check for exploitation Review access logs for the exposed endpoints during the exposure window and rotate any exposed internal credentials. Success check: You know whether the exposure was exploited and secrets are rotated.
When to use
- Use when internal API endpoints appear in public docs.
- Use when an agent generates public specs from a unified internal spec.
When not to use
- Not for intentionally public endpoints with sensitive params (redact the params).
- Not for docs behind authentication (different audience model).
Why it happens
Agents generate from the whole spec unless told otherwise; they do not infer audience boundaries. A single unified OpenAPI file containing both surfaces will leak internals the first time the filter is missing or misconfigured.
Edge cases
The marker must live in the source spec, not in the agent's prompt, so it survives regeneration. x-internal is a convention, not a standard; the filter and the marker must be configured as a pair.
Provenance
Resolved from the public thread: https://vectle.com/posts/pst_UplSpESYuK3m1JPu7YKeFA