Skip to main content
POST
Deprecate a model in favor of another (Admin only)

Authorizations

Authorization
string
header
required

JWT access token for user authentication (Authorization: Bearer <jwt_token>). Create via POST /users/me/access_tokens.

Body

application/json

Request to deprecate one model in favor of another.

Atomically:

  • adds modelId as an alias of successorModelId (so existing clients continue to work, with their request-side model rewritten to the successor at resolution time),
  • re-points any existing inbound aliases of modelId at the successor,
  • sets modelId.isActive = false so it is hidden from GET /v1/models and GET /v1/admin/models (unless include_inactive is set).
modelId
string
required

Canonical model_name of the model being deprecated.

successorModelId
string
required

Canonical model_name of the replacement model. Must be active.

changeReason
string | null

Optional reason recorded in the model history.

Response

Model deprecated successfully

Response from a deprecation operation.

Both sides use the public ModelWithPricing shape (no isActive / timestamps). Confirmation that the deprecation took effect is implicit: the deprecated model is hidden from GET /v1/admin/models (default listing) and from public GET /v1/models. To inspect isActive directly, call GET /v1/admin/models?include_inactive=true.

aliasesCarried
integer<int32>
required

Number of pre-existing active inbound aliases of the deprecated model that were re-pointed at the successor. Does not include the deprecated model's own canonical name (which is added unconditionally as a new alias) and does not include inactive inbound aliases (which are left untouched — see repository docs).

Required range: x >= 0
deprecated
object
required

State of the deprecated model after the operation (canonical name echoed back in modelId; merged alias list reflects the moves).

successor
object
required

State of the successor model after the operation. Its metadata.aliases includes the deprecated modelId plus any inbound aliases that were re-pointed.