Teams managing APIs for multiple audiences often end up with diverging hand-edited spec copies. OpenAPI Overlays solve this by keeping one parent OpenAPI definition as the source of truth and applying separate overlay documents to filter out operations per audience. A public overlay removes delete, put, and cancel operations. A partner overlay keeps write access but strips experimental paths and internal response examples. The post also warns about a key gotcha: the `remove` action deletes only the targeted node and does not chase `$ref` references, so removing shared components that other operations still reference will produce dangling refs that fail validation. The recommended approach is to treat the full internal spec as the single source of truth and generate all audience-specific views via small, reviewable overlay files.
