{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/llmintel-ai/json-schema/llmintel-ai-model-detail-schema.json",
  "title": "ModelDetail",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/llmintel-ai-openapi.json#/components/schemas/ModelDetail",
  "allOf": [
    {
      "$ref": "#/$defs/Model"
    },
    {
      "type": "object",
      "properties": {
        "spec": {
          "$ref": "#/$defs/ModelSpec"
        },
        "history": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Event"
          }
        },
        "migration": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "recommendedReplacementIds": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "resolvedReplacementIds": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "pricingDelta": {
              "type": [
                "object",
                "null"
              ]
            },
            "contextWindowDelta": {
              "type": [
                "integer",
                "null"
              ]
            },
            "breakingNotes": {
              "type": [
                "string",
                "null"
              ]
            },
            "confidence": {
              "type": "string"
            },
            "replacementSpec": {
              "$ref": "#/$defs/ModelSpec"
            }
          }
        },
        "optimization": {
          "type": [
            "object",
            "null"
          ],
          "description": "Advisory 'you could switch to…' suggestions (paid keys only; null otherwise). Editorial, with checkable reasons; never asserts equivalence beyond capability class.",
          "properties": {
            "confidence": {
              "type": "string"
            },
            "analysisSource": {
              "type": "string"
            },
            "candidates": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "candidateId": {
                    "type": "string"
                  },
                  "candidateDisplayName": {
                    "type": "string"
                  },
                  "candidateProvider": {
                    "type": "string"
                  },
                  "capabilityClass": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "enum": [
                      "flagship",
                      "balanced",
                      "lite",
                      null
                    ]
                  },
                  "reasons": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "pricingDeltaPct": {
                    "type": "object"
                  },
                  "contextWindowDelta": {
                    "type": [
                      "integer",
                      "null"
                    ]
                  },
                  "speedDelta": {
                    "type": [
                      "number",
                      "null"
                    ]
                  },
                  "crossProvider": {
                    "type": "boolean",
                    "description": "True when adopting this candidate means switching provider (extra migration effort)."
                  }
                }
              }
            }
          }
        }
      }
    }
  ],
  "$defs": {
    "Event": {
      "type": "object",
      "required": [
        "id",
        "modelId",
        "toState"
      ],
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid"
        },
        "modelId": {
          "type": "string"
        },
        "fromState": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "announced",
            "active",
            "legacy",
            "deprecated",
            "retiring",
            "retired",
            null
          ]
        },
        "toState": {
          "type": "string",
          "enum": [
            "announced",
            "active",
            "legacy",
            "deprecated",
            "retiring",
            "retired"
          ]
        },
        "detectedAt": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "verifiedAt": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        }
      }
    },
    "Model": {
      "type": "object",
      "required": [
        "id",
        "provider",
        "displayName",
        "aliases",
        "lifecycleState",
        "sourceUrl",
        "sourceTerm"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "Canonical model id (provider/model)."
        },
        "provider": {
          "type": "string",
          "enum": [
            "openai",
            "anthropic",
            "azure",
            "bedrock",
            "google",
            "vertex",
            "mistral",
            "cohere"
          ]
        },
        "displayName": {
          "type": "string"
        },
        "aliases": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "lifecycleState": {
          "type": "string",
          "enum": [
            "announced",
            "active",
            "legacy",
            "deprecated",
            "retiring",
            "retired"
          ],
          "description": "- `announced` — Model has been announced by the provider but is not yet generally available.\n- `active` — Generally available. API calls succeed; recommended for new workloads.\n- `legacy` — Still callable, but superseded and no longer recommended for new workloads.\n- `deprecated` — No new customers/usage onboarding; existing API calls still succeed.\n- `retiring` — A hard retirement date is scheduled and imminent; calls still succeed until then.\n- `retired` — Shut down. API calls fail."
        },
        "announcedDate": {
          "type": [
            "string",
            "null"
          ],
          "format": "date"
        },
        "deprecatedDate": {
          "type": [
            "string",
            "null"
          ],
          "format": "date"
        },
        "retirementDate": {
          "type": [
            "string",
            "null"
          ],
          "format": "date"
        },
        "sourceUrl": {
          "type": "string",
          "format": "uri",
          "description": "Primary provider source the record was verified against."
        },
        "sourceTerm": {
          "type": "string",
          "description": "Verbatim provider term that mapped to the canonical state."
        },
        "openWeights": {
          "type": "boolean",
          "description": "The model ships downloadable weights and can be self-hosted. Use this to tell a null `inputUsdPerMillion` that means \"no per-token rate exists\" apart from one that means \"not in our data yet\". Independent of pricing: a model may have public weights and a published per-token rate at the same time."
        },
        "lastVerifiedAt": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        }
      }
    },
    "ModelSpec": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "inputUsdPerMillion": {
          "type": [
            "number",
            "null"
          ]
        },
        "outputUsdPerMillion": {
          "type": [
            "number",
            "null"
          ]
        },
        "contextWindowTokens": {
          "type": [
            "integer",
            "null"
          ]
        },
        "maxOutputTokens": {
          "type": [
            "integer",
            "null"
          ]
        },
        "source": {
          "type": [
            "string",
            "null"
          ]
        },
        "updatedAt": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "capabilityClass": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "flagship",
            "balanced",
            "lite",
            null
          ],
          "description": "Benchmark-derived capability tier (paid keys only)."
        },
        "tokensPerSecond": {
          "type": [
            "number",
            "null"
          ],
          "description": "Median output tokens/sec (paid keys only)."
        },
        "timeToFirstTokenSeconds": {
          "type": [
            "number",
            "null"
          ],
          "description": "Median TTFT in seconds (paid keys only)."
        },
        "benchmarkSource": {
          "type": [
            "string",
            "null"
          ],
          "description": "Attribution for performance fields (paid keys only)."
        }
      }
    }
  }
}