Route status
Route existence in OpenAPI is not the same thing as public product approval. Every endpoint page shows a conservative route class before examples.
Current posture
Generated OpenAPI is the endpoint source of truth, but expanded external publication, SDKs, and production recipes wait on route registry and release evidence.
Status vocabulary
| Status | Meaning | Publication | Action |
|---|---|---|---|
| PUBLIC_REFERENCE | Generated endpoint contract can be shown as a baseline reference with caveats. | Allowed for internal or limited baseline reference only until release evidence is attached. | Keep route status, side effects, async/idempotency, file policy, and release evidence visible. |
| COMPATIBILITY_LIMITED | Route exists, but versioning or behavior is not stable enough for happy-path docs. | May be listed with warnings; exclude from quickstarts, SDKs, and workflow recipes. | Exclude from quickstarts, SDKs, and workflow recipes until classified. |
| Needs publication review | Product, tenancy, side-effect, credential, file, PHI, or security semantics still need approval. | Show the contract with caveats, but do not promote it as an ordinary production public API. | Route through product, security/compliance, module-owner, and developer-experience review. |
| PRIVATE_OR_INTERNAL | Operational, worker, callback, admin, or internal route. | Excluded from public developer documentation. | Exclude from public developer docs. |
Current baseline facts
| Fact | Value |
|---|---|
| Generated operations | 427 operations across 374 paths |
| Primary public prefix | 371 generated paths use /api/v1 |
| Compatibility prefixes | 2 generated paths use /v2 and 1 generated path uses legacy /api |
| Compatibility routes | POST /api/credentialing/update-status, POST /v2/era, GET /v2/era/{eraId} |
| Bearer auth gap | GET /api/v1/medical-coding/code-systems needs security review before public use |
Required route metadata
| Field | Why |
|---|---|
| Route class | Distinguishes generated baseline routes from compatibility, private, worker, guest, webhook, or internal surfaces. |
| Auth class and scopes | Shows whether bearer API key security applies and whether product scopes, feature flags, or RBAC can deny access. |
| Tenant source | Confirms whether the API key selects tenant context or whether a compatibility field still needs classification. |
| Side-effect mode | Prevents local, queued, dry-run, simulated, metadata-only, or file behavior from being documented as live execution. |
| Release evidence | Links route classification to the tests and no-sensitive-data checks required before external publication. |
Publication rules by surface
| Surface | Rule |
|---|---|
| Quickstart | Use only a classified safe route with PHI-safe examples and current release evidence. |
| Endpoint index | Show route class and caveats before request examples or try-out controls. |
| Workflow guides | Link to platform primitives instead of repeating local exceptions as if they were global policy. |
| SDKs | Exclude compatibility-limited, private, internal, file-risk, credential-risk, live side-effect-risk, and publication-review routes. |