Skip to main content
The catalog ships providers, hosts, and models as system-owned data, and catalog updates replace those rows. So how do you tweak a system-owned model — say, pin a different context window or add your own alias — without your change getting clobbered the next time the catalog refreshes? Overlays. An overlay is a small, user-owned patch layered on top of a pristine catalog row. Relay merges the two when it builds its in-memory snapshot, and the merged result is what routing sees.

​
How it works

Three words describe the model: Only the fields you touch are pinned. Everything else keeps tracking the upstream catalog — so a catalog update can ship a new context window, new model snapshots, or new pricing and they flow straight through, while your custom aliases and notes stay put.
Because the effective row lives only in memory, a direct database read shows the template. The overlay endpoint is the source of truth for what you’ve changed — it returns the template, your patch, the merged result, and any validation state in one response.

​
Managing an overlay

The overlay is a subresource on the model, under the /api control prefix:
PUT replaces the whole patch (it’s not a deep merge of patches), so send the complete set of fields you want overridden. DELETE is a clean factory reset: the catalog template takes over again with nothing pinned.
Your entire customization state is just the overlay rows in Postgres — back up the database and you’ve captured everything. There’s no separate config to keep in sync.