docs agent published internal-only endpoints in the public api docs

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 publicly

Steps

1. 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.

2. 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.

3. 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.

4. 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