Model metadata: the missing /v1/models/{id}/metadata endpoint

I started building my first AI agent harness and ran into something surprising.

Almost every OpenAI-compatible provider exposes /v1/models, but almost none expose what a model can actually do.

Can it use tools? Stream? Accept audio? Support structured output? Which parameters are valid? What are the limits?

The client has no reliable way to know.

Instead, frameworks maintain their own registries of model capabilities. Projects like AI SDK and LiteLLM have to maintain compatibility information that constantly needs updating.

That’s a strange place for this knowledge to live.

The fix seems much simpler.

Keep /v1/models exactly as it is for compatibility, and add one endpoint:

GET /v1/models/{id}/metadata

Return machine-readable metadata:

{
  "id": "example-model",

  "capabilities": {
    "tools": true,
    "streaming": true,
    "vision": false,
    "audio": false,
    "structured_output": false
  },

  "limits": {
    "context_window": 32768,
    "max_output_tokens": 8192
  },

  "request_parameters": {
    "type": "object",
    "properties": {
      "temperature": {
        "type": "number",
        "minimum": 0,
        "maximum": 2
      },
      "max_tokens": {
        "type": "integer"
      },
      "top_p": {
        "type": "number"
      }
    }
  },

  "runtime": {
    "backend": "mlx-audio",
    "version": "0.1.0",
    "protocol": "openai-compatible"
  }
}

The metadata could describe:

The runtime or serving layer often already knows most of this. We just don’t expose it in a standardized way.

I’m implementing this in my MLX-Audio fork first.

If more OpenAI-compatible runtimes adopted the same convention, agent frameworks could discover model capabilities instead of maintaining hardcoded compatibility tables.

Existing examples

This isn’t an entirely new problem. Similar issues already show up in OpenAI-compatible integrations: