Model discovery

GET /v1/models is one path with two incompatible response shapes, chosen by request headers. This is what lets OpenAI clients (Cursor, Cline/Roo) and Anthropic clients (Claude Code) both discover models from the same endpoint.

Header discrimination

• If anthropic-version or x-api-key is present → the Anthropic list shape.
• Otherwise → the OpenAI list shape.

OpenAI shape

{
  "object": "list",
  "data": [
    {
      "id": "claude-turbo-hub-qwen3-coder",
      "object": "model",
      "created": 1730000000,
      "owned_by": "opengateway"
    }
  ]
}

Anthropic shape

{
  "data": [
    {
      "type": "model",
      "id": "claude-turbo-hub-qwen3-coder",
      "display_name": "Qwen3 Coder",
      "created_at": "2026-01-01T00:00:00Z"
    }
  ],
  "has_more": false,
  "first_id": "claude-turbo-hub-qwen3-coder",
  "last_id": "claude-turbo-hub-gpt-oss-120b"
}

What each client needs

| Client | Needs /v1/models? | Shape | Note | | --- | --- | --- | --- | | Cursor | Required | OpenAI | Must return 200 to verify the key. | | Cline / Roo | Optional | OpenAI | Populates the picker; manual ids work. | | Claude Code | Optional (gated) | Anthropic | Picker only shows claude*/anthropic* ids. | | OpenAI SDK | On demand | OpenAI | client.models.list(). | | Anthropic SDK | On demand | Anthropic | client.models.list(). | | Codex | Avoid | — | Codex wants {"models":[…]}; use model_catalog_json instead. | | OpenCode | Not used | — | Models are declared in config. |

Codex caveat

Codex’s background catalog refresh expects {"models":[…]}, not {"data":[…]}. Don’t satisfy Codex via /v1/models — set model_catalog_json in its config. See Codex setup.

The usable-model contract

Beyond id/object, OpenGateway emits the Claude Code “usable-model” fields (owned_by, capabilities, category, catalog_type, endpoint, metadata.api_shape, and the context-window trio). Without these, Claude Desktop reports “Gateway returned no usable models”. The curated claude-* aliases ensure the picker is populated.

Per-lane discovery

Each lane serves its own catalog:

curl "https://api.opengateway.one/oss/v1/models"       -H "Authorization: Bearer $OPENGATEWAY_API_KEY"
curl "https://api.opengateway.one/frontier/v1/models"  -H "Authorization: Bearer $OPENGATEWAY_API_KEY"