API surface and route ledger
Know which routes are public automation contracts and why browser or operator routes stay outside OpenAPI.
Shiplet's OpenAPI document is the public automation contract. Its method, path, authentication, scopes, schemas, and Code Mode marker are supported together.
A browser route is not an undocumented public API merely because its path starts with /api. The executable api-route-ledger.json classifies every statically registered Worker route, including paths supplied through local or imported string constants. Each must appear in OpenAPI or match exactly one narrow exclusion family. Dynamic or unresolvable registration fails closed, as do missing, duplicate, and stale classifications.
What stays outside OpenAPI
| Class | Examples | Why separate |
|---|---|---|
| Browser-only identity ceremony | WorkOS login, account switching, Cloudflare OAuth return | Trusted cookies, redirects, and user confirmation. |
| First-party browser model | Dashboard, inbox, account, presence, watches | Aggregated state for Shiplet's own UI. |
| Trusted review or embed protocol | Sandboxed active and validated-revision preview frames, host assets, WordPress exchange | Origin-bound protocol with a dedicated security contract; frame URLs are children of the documented authenticated preview host, not independent automation. |
| Human approval | Ownership, MCP approval, quarantine release | A trusted top-level operation is required. |
| Operator-internal recovery | Production bootstrap and reconciliation | Narrow operational compatibility, not customer integration. |
| Public representation | Docs, discovery, icons, OpenAPI JSON | Files and representations, not REST operations. |
Classification never weakens authorization. Browser-only and operator-internal routes still authenticate, authorize, scope, limit, and audit under their behavior contract.
Choose the supported surface
- For REST or Code Mode automation, use only operations discovered in OpenAPI.
- For interactive MCP, connect with browser OAuth and call
searchbeforeexecute. - For review, embeds, ownership, and account administration, use the first-party browser flow.
- If an operation is absent from OpenAPI, do not reverse-engineer a browser-only request.
Executable verification
The gate parses the real Hono route registrations, statically resolves local and relative-imported string constants such as asset paths, compares them with the complete candidate OpenAPI document, and loads docs/public-documentation/api-route-ledger.json. It rejects dynamic or unresolvable registration, missing runtime operations, unclassified routes, duplicate exclusions, and stale rules.
Next: use API keys for server automation or Code Mode MCP for interactive browser OAuth.