> ## Documentation Index > Fetch the complete documentation index at: https://docs.near.ai/llms.txt > Use this file to discover all available pages before exploring further. # Deprecate a model in favor of another (Admin only) > Atomically marks `modelId` as deprecated and routes its traffic to `successorModelId`: 1. Adds `modelId` as an alias of `successorModelId`, so existing clients sending `model: ""` keep working — the alias resolver rewrites the request-side `model` field to the successor before backend dispatch, and the response's `model` field reflects the canonical (successor) name. 2. Re-points any pre-existing inbound aliases of `modelId` at the successor, so historical aliases keep resolving. 3. Sets `modelId.isActive = false` so it is hidden from public `GET /v1/models` and from `GET /v1/admin/models` unless `include_inactive=true`. 4. Records a `model_history` entry for audit purposes. All steps run in a single DB transaction. If the successor is inactive or either model is missing, returns 404 without modifying state. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/admin/models/deprecate openapi: 3.1.0 info: title: NEAR AI Cloud API description: >- NEAR AI Cloud API for private AI model inference and organization administration. contact: name: NEAR AI Team email: support@near.ai license: name: MIT version: 1.0.0 servers: - url: https://cloud-api.near.ai description: NEAR AI Cloud security: - session_token: [] - api_key: [] tags: - name: Chat description: Chat completion endpoints for AI model inference - name: Images description: Image generation endpoints - name: Audio description: Audio transcription endpoints - name: Rerank description: Document reranking endpoints - name: Score description: Text similarity scoring endpoints - name: Privacy description: Privacy classification (PII span detection) endpoints - name: Models description: Public model catalog and information - name: Responses description: >- Stateless response inference (`store: false` only). Raw request/response content, response items, and history are not persisted. Clients must include any prior context in each request. Every successful Responses inference makes exactly one Chat Completions call. Only custom `function` tools are supported. They are client-managed: Cloud returns `function_call` items but never executes them; a later `store: false` request replays the individual call (the raw item from output is accepted) with its matching `function_call_output`, alongside caller-managed message history and the same function tool definitions. The minimal replay path also accepts assistant `message` text parts of type `output_text`, but not reasoning or arbitrary full `response.output` items. Server-executed tools (`web_search`, `web_context_search`, `file_search`, `code_interpreter`, `computer`, and remote `mcp`) and image-generation/editing models are rejected. The separate `POST /mcp` endpoint continues to expose its `web_search` tool independently of Responses; use `/v1/images/*` for image generation/editing. Existing completed-response gateway attestation is preserved best-effort: when the signature write succeeds, `GET /v1/signature/resp_*` retrieves signatures over SHA-256 request/response digests, never raw content. Interrupted streams create no `resp_*` attestation record or legacy disconnect fallback. Conversations, response history, and file input are rejected. - name: Organizations description: Organization management - name: Organization Members description: Organization member and invitation management - name: Workspaces description: Workspace and API key management - name: Users description: User profile and token management - name: Invitations description: Token-based invitation handling - name: Usage description: Usage tracking and billing information - name: Reporting description: Read-only customer usage reporting - name: Billing description: Billing costs endpoint (HuggingFace integration) - name: Staking Farm description: House of Stake farm credit configuration and synchronization - name: Health description: Health check endpoints - name: Attestation description: Attestation and verification endpoints - name: Gateway description: Model gateway integration endpoints - name: Admin description: Administrative endpoints (admin access required) - name: Services description: Public platform services (e.g. web_search pricing) paths: /v1/admin/models/deprecate: post: tags: - Admin summary: Deprecate a model in favor of another (Admin only) description: >- Atomically marks `modelId` as deprecated and routes its traffic to `successorModelId`: 1. Adds `modelId` as an alias of `successorModelId`, so existing clients sending `model: ""` keep working — the alias resolver rewrites the request-side `model` field to the successor before backend dispatch, and the response's `model` field reflects the canonical (successor) name. 2. Re-points any pre-existing inbound aliases of `modelId` at the successor, so historical aliases keep resolving. 3. Sets `modelId.isActive = false` so it is hidden from public `GET /v1/models` and from `GET /v1/admin/models` unless `include_inactive=true`. 4. Records a `model_history` entry for audit purposes. All steps run in a single DB transaction. If the successor is inactive or either model is missing, returns 404 without modifying state. operationId: deprecate_model requestBody: content: application/json: schema: $ref: '#/components/schemas/DeprecateModelRequest' required: true responses: '200': description: Model deprecated successfully content: application/json: schema: $ref: '#/components/schemas/DeprecateModelResponse' '400': description: Invalid request (e.g. self-deprecation, empty model id) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Either model not found, or successor is not active content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - session_token: [] components: schemas: DeprecateModelRequest: type: object description: |- 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). required: - modelId - successorModelId properties: changeReason: type: - string - 'null' description: Optional reason recorded in the model history. modelId: type: string description: Canonical model_name of the model being deprecated. successorModelId: type: string description: Canonical model_name of the replacement model. Must be active. DeprecateModelResponse: type: object description: |- 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`. required: - deprecated - successor - aliasesCarried properties: aliasesCarried: type: integer format: int32 description: >- 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). minimum: 0 deprecated: $ref: '#/components/schemas/ModelWithPricing' description: |- State of the deprecated model after the operation (canonical name echoed back in `modelId`; merged alias list reflects the moves). successor: $ref: '#/components/schemas/ModelWithPricing' description: >- State of the successor model after the operation. Its `metadata.aliases` includes the deprecated `modelId` plus any inbound aliases that were re-pointed. ErrorResponse: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorDetail' ModelWithPricing: type: object description: Model with pricing information required: - modelId - inputCostPerToken - outputCostPerToken - costPerImage - metadata properties: cacheReadCostPerToken: oneOf: - type: 'null' - $ref: '#/components/schemas/DecimalPrice' description: >- Cost per cached input token. Omitted when cache pricing is disabled; an amount of 0 means cached tokens are genuinely free. costPerImage: $ref: '#/components/schemas/DecimalPrice' inputCostPerToken: $ref: '#/components/schemas/DecimalPrice' metadata: $ref: '#/components/schemas/ModelMetadata' modelId: type: string outputCostPerToken: $ref: '#/components/schemas/DecimalPrice' ErrorDetail: type: object required: - message - type properties: code: type: - string - 'null' message: type: string param: type: - string - 'null' type: type: string DecimalPrice: type: object description: >- Decimal price for API responses The system uses a fixed scale of 9 (nano-dollars = 1 billionth of a dollar). The scale field is included in responses for client convenience. required: - amount - scale - currency properties: amount: type: integer format: int64 currency: type: string scale: type: integer format: int64 ModelMetadata: type: object description: Model metadata required: - verifiable - contextLength - modelDisplayName - modelDescription - ownedBy - providerType - attestationSupported properties: aliases: type: array items: type: string architecture: oneOf: - type: 'null' - $ref: '#/components/schemas/ModelArchitecture' description: Model architecture (input/output modalities) attestationSupported: type: boolean description: Whether this model supports TEE attestation contextLength: type: integer format: int32 datacenters: type: - array - 'null' items: $ref: '#/components/schemas/Datacenter' description: |- Datacenters the model runs in (OpenRouter `datacenters`), e.g. `[{ "country_code": "US" }]`. Omitted when unset. deprecationDate: type: - string - 'null' description: >- OpenRouter `deprecation_date`: planned deprecation date as an ISO 8601 string. Omitted when there is no planned deprecation. huggingFaceId: type: - string - 'null' description: HuggingFace identifier (OpenRouter `hugging_face_id`). inferenceUrl: type: - string - 'null' description: Base URL for the model's inference endpoint isReady: type: - boolean - 'null' description: 'OpenRouter `is_ready`: stored/exposed verbatim. Omitted when unset.' maxOutputLength: type: - integer - 'null' format: int32 description: Maximum output tokens per response (OpenRouter `max_output_length`). modelDescription: type: string modelDisplayName: type: string modelIcon: type: - string - 'null' openrouterSlug: type: - string - 'null' description: >- OpenRouter `openrouter.slug` override (lowercase `author/slug`). Omitted when unset. On public `GET /v1/models` this surfaces as the nested `openrouter: { slug }` object; the admin view exposes the raw value. ownedBy: type: string providerConfig: description: JSON config for external providers (backend, base_url, etc.) providerType: type: string description: 'Provider type: "vllm" (TEE-enabled) or "external" (3rd party)' quantization: type: - string - 'null' description: Quantization label (int4/int8/fp4/fp6/fp8/fp16/bf16/fp32). supportedFeatures: type: array items: type: string description: Feature capabilities (OpenRouter `supported_features`). supportedSamplingParameters: type: array items: type: string description: >- Sampling parameters accepted by the model (OpenRouter `supported_sampling_parameters`). verifiable: type: boolean ModelArchitecture: type: object description: Model architecture describing input/output modalities required: - inputModalities - outputModalities properties: inputModalities: type: array items: type: string description: >- Input modalities the model accepts, e.g., ["text"], ["text", "image"] outputModalities: type: array items: type: string description: Output modalities the model produces, e.g., ["text"], ["image"] Datacenter: type: object description: |- OpenRouter `datacenters` entry: a single datacenter the model runs in. The provider spec (https://openrouter.ai/docs/guides/community/for-providers) models `datacenters` as an array of objects, each with an ISO 3166 Alpha-2 `country_code`. We store only the country codes (a `TEXT[]`) and reconstruct this object wrapper at serialization time. required: - country_code properties: country_code: type: string description: ISO 3166 Alpha-2 country code (e.g. "US"), uppercase. securitySchemes: session_token: type: http scheme: bearer bearerFormat: JWT description: >- JWT access token for user authentication (Authorization: Bearer ). Create via POST /users/me/access_tokens. api_key: type: http scheme: bearer bearerFormat: api_key description: 'API key for programmatic access (Authorization: Bearer sk-)' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.