---
title: "Upsert one model-catalog overlay row"
method: PUT
path: "/api/models-catalog/overlay"
tags: ["Pricing"]
---

# Upsert one model-catalog overlay row

`PUT /api/models-catalog/overlay`

Overlay facts win per non-null field over the models.dev row; overlay-only models are served too. Overlay prices fill pricing-table gaps (never override an active price). With `expiresWhenUpstreamMatches` (default true) the row is deleted once upstream matches every non-null fact.

## Request body

- object
  - `provider` string, required
  - `modelId` string, required
  - `name` string
  - `family` string
  - `releaseDate` string
  - `contextWindow` integer
  - `maxOutput` integer
  - `reasoning` boolean
  - `reasoningOptions` object[]
    - `type` string, required
    - `values` string[]
  - `pricing` object
    - `input` number
    - `output` number
    - `cache_read` number
    - `cache_write` number
  - `status` string
  - `reason` string, required
  - `verifiedBy` string
  - `expiresWhenUpstreamMatches` boolean

## Response `200`

Overlay row upserted

- object
  - `provider` string, required
  - `modelId` string, required
  - `name` string, nullable
  - `family` string, nullable
  - `releaseDate` string, nullable
  - `contextWindow` number, nullable
  - `maxOutput` number, nullable
  - `reasoning` boolean, nullable
  - `reasoningOptions` object[], nullable
    - `type` string, required
    - `values` string[]
  - `pricing` object, nullable
    - `input` number
    - `output` number
    - `cache_read` number
    - `cache_write` number
  - `status` string, nullable
  - `reason` string, required
  - `verifiedBy` string, nullable
  - `expiresWhenUpstreamMatches` boolean, required
  - `createdAt` number, required
  - `updatedAt` number, required

## Other responses

- `403` — Forbidden

## Changes

- **2026-09-30** `e248ce78b701` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/desplega-ai/apis/agent-swarm-api/changes/api/models-catalog/overlay/put.md)

---

[API](https://skmtc.dev/desplega-ai/apis/agent-swarm-api.md) · [All operations](https://skmtc.dev/desplega-ai/apis/agent-swarm-api/llms.txt) · [OpenAPI document](https://skmtc.dev/desplega-ai/apis/agent-swarm-api/revisions/78f58e6d81be?raw)