feat: scope model params by API surface

CONTRIBUTING.md

@@ -29,7 +29,13 @@ You don't need to know the schema to file one. A link to the official docs is th
    # yaml-language-server: $schema=https://modelparams.dev/api/v1/schema.json
    ```
 
-3. **Required top-level fields:** `provider`, `authType` (`api_key` or `subscription`), `model`, `params`.
+3. **Required top-level fields:** `provider`, `authType` (`api_key` or `subscription`),
+   `apiSurface`, `model`, `params`.
+
+   `apiSurface` names the API or SDK request family that accepts these paths.
+   Use one of the values in the [schema convention](docs/model-parameters-schema.md#catalog-entry).
+   Do not mix Chat Completions and Responses fields, or any other two surfaces,
+   in one entry.
 
    Optional lifecycle fields are `status` (`active`, `deprecated`, or
    `retired`), `replacement` (a provider-qualified model id), and `shutdownOn`
@@ -83,6 +89,7 @@ You don't need to know the schema to file one. A link to the official docs is th
 # yaml-language-server: $schema=https://modelparams.dev/api/v1/schema.json
 provider: anthropic
 authType: api_key
+apiSurface: anthropic-messages
 model: claude-sonnet-4-6
 params:
   - path: max_tokens

README.md

@@ -146,20 +146,21 @@ The same model accepts different parameters on each host that serves it. The cat
 
 ## API surfaces
 
-One entry documents one wire format.
+Every catalog entry declares an `apiSurface`. It scopes the parameter paths to
+one request and SDK family, independently of provider, model, and auth type.
 
 | Surface                                                                                               | Status |
 | ----------------------------------------------------------------------------------------------------- | ------ |
 | OpenAI Chat Completions — openai, deepseek, xai, mistral, moonshot, alibaba, z-ai, groq, fireworks, … | ✅     |
+| OpenAI Responses — OpenAI subscription entries and xAI multi-agent models                             | ✅     |
 | Anthropic Messages                                                                                    | ✅     |
 | Google `generateContent`                                                                              | ✅     |
 | Amazon Bedrock `Converse` — every `bedrock/*` entry                                                   | ✅     |
 | Vertex AI `generateContent` — every `vertex/*` entry                                                  | ✅     |
-| Subscription plans (`-subscription` entries)                                                          | ✅     |
+| Cohere Chat                                                                                           | ✅     |
 | Amazon Bedrock `InvokeModel` (native per-vendor bodies)                                               | ❌     |
 | Vertex AI `rawPredict` (Anthropic, Meta, Mistral on Vertex)                                           | ❌     |
 | MiniMax native endpoint                                                                               | ❌     |
-| OpenAI Responses API                                                                                  | ❌     |
 | Google Interactions API                                                                               | ❌     |
 | xAI native SDK                                                                                        | ❌     |
 

api/v1/validate.ts

@@ -190,6 +190,7 @@ export default {
       model: resolved.id,
       provider: entry.provider,
       authType: entry.authType,
+      apiSurface: entry.apiSurface,
       // The exact string to put in the API request when the host's wire id
       // differs from the catalog slug (fireworks, groq).
       ...("wireId" in entry ? { wireId: entry.wireId } : {}),

docs/model-parameters-schema.md

@@ -2,7 +2,7 @@
 
 The Model Parameters Schema (MPS) convention is the JSON/YAML shape used by
 modelparams.dev to describe the request parameters available for a specific
-provider, auth type, and model.
+provider, model, auth type, and API/SDK surface.
 
 This catalog is metadata. It describes knobs a consumer can put into an outbound
 model request, such as `temperature`, `top_p`, `max_tokens`,
@@ -17,13 +17,14 @@ The public runtime sources are:
 
 ## Catalog Entry
 
-Each entry describes exactly one provider/auth/model tuple and its available
+Each entry describes exactly one provider/model/auth/API-surface tuple and its available
 parameters.
 
 ```json
 {
   "provider": "anthropic",
   "authType": "api_key",
+  "apiSurface": "anthropic-messages",
   "model": "claude-haiku-4-5",
   "status": "active",
   "params": [
@@ -45,16 +46,12 @@ parameters.
 
 Conventions:
 
-- `provider`, `authType`, and `model` identify exactly one model route.
+- `provider`, `model`, `authType`, and `apiSurface` scope one parameter set.
 - `model` reuses the slug the catalog already uses for that model elsewhere,
   when the vendor publishes it first-party. `bedrock/claude-sonnet-4-5` matches
   `anthropic/claude-sonnet-4-5` on purpose: the provider axis only means
   something if the same model carries the same slug on every host.
-- `provider` is a kebab-case slug. It also fixes the wire format the entry
-  documents: every `params` path must belong to that one surface. Where a host
-  serves two (Bedrock's `Converse` and `InvokeModel`), the catalog documents the
-  one listed in the README's API surfaces table and omits the other rather than
-  mixing both vocabularies in one entry.
+- `provider` is a kebab-case slug.
 - `model` is the provider-native model id without path separators. Preserve
   upstream casing; it may contain dots or colons when the upstream model id does.
 - `wireId` is optional: the exact string to put in the request's own `model`
@@ -67,6 +64,14 @@ Conventions:
   go stale the next time the host adds a region. Availability per region is
   account state and is deliberately not recorded here.
 - `authType` is `api_key` or `subscription`.
+- `apiSurface` identifies the request and SDK family whose field names appear in
+  `params`. For example, OpenAI Chat Completions uses
+  `max_completion_tokens`, while OpenAI Responses uses
+  `max_output_tokens`. Do not combine fields from two surfaces in one entry.
+  Supported values are `openai-chat-completions`, `openai-responses`,
+  `anthropic-messages`, `google-generate-content`,
+  `amazon-bedrock-converse`, `google-vertex-generate-content`, and
+  `cohere-chat`.
 - `status` is `active`, `deprecated`, or `retired`. Omit it when lifecycle
   status has not been tracked; generated catalog data preserves the omission.
 - `replacement` is an optional provider-qualified model id, such as
@@ -105,7 +110,7 @@ up the target directly.
 ## Parameter Scope
 
 MPS entries should describe only parameters the user or consumer can configure
-for the selected provider/auth/model tuple.
+for the selected provider/model/auth/API-surface tuple.
 
 For `authType: api_key`, list parameters from the official provider API
 reference. Do not invent request fields the upstream API does not accept.

models/alibaba/deepseek-v3.2.yaml

@@ -1,6 +1,7 @@
 # yaml-language-server: $schema=https://modelparams.dev/api/v1/schema.json
 provider: alibaba
 authType: api_key
+apiSurface: openai-chat-completions
 model: deepseek-v3.2
 params:
   - path: max_completion_tokens

models/alibaba/deepseek-v4-flash-0731.yaml

@@ -1,6 +1,7 @@
 # yaml-language-server: $schema=https://modelparams.dev/api/v1/schema.json
 provider: alibaba
 authType: api_key
+apiSurface: openai-chat-completions
 model: deepseek-v4-flash-0731
 params:
   - path: max_completion_tokens

models/alibaba/deepseek-v4-flash.yaml

@@ -1,6 +1,7 @@
 # yaml-language-server: $schema=https://modelparams.dev/api/v1/schema.json
 provider: alibaba
 authType: api_key
+apiSurface: openai-chat-completions
 model: deepseek-v4-flash
 params:
   - path: max_completion_tokens

models/alibaba/deepseek-v4-pro-0813.yaml

@@ -1,6 +1,7 @@
 # yaml-language-server: $schema=https://modelparams.dev/api/v1/schema.json
 provider: alibaba
 authType: api_key
+apiSurface: openai-chat-completions
 model: deepseek-v4-pro-0813
 params:
   - path: max_completion_tokens

models/alibaba/deepseek-v4-pro.yaml

@@ -1,6 +1,7 @@
 # yaml-language-server: $schema=https://modelparams.dev/api/v1/schema.json
 provider: alibaba
 authType: api_key
+apiSurface: openai-chat-completions
 model: deepseek-v4-pro
 params:
   - path: max_completion_tokens

models/alibaba/glm-5.1.yaml

@@ -1,6 +1,7 @@
 # yaml-language-server: $schema=https://modelparams.dev/api/v1/schema.json
 provider: alibaba
 authType: api_key
+apiSurface: openai-chat-completions
 model: glm-5.1
 params:
   - path: max_completion_tokens

models/alibaba/glm-5.2.yaml

@@ -1,6 +1,7 @@
 # yaml-language-server: $schema=https://modelparams.dev/api/v1/schema.json
 provider: alibaba
 authType: api_key
+apiSurface: openai-chat-completions
 model: glm-5.2
 params:
   - path: max_completion_tokens

models/alibaba/kimi-k2.7-code.yaml

@@ -1,6 +1,7 @@
 # yaml-language-server: $schema=https://modelparams.dev/api/v1/schema.json
 provider: alibaba
 authType: api_key
+apiSurface: openai-chat-completions
 model: kimi-k2.7-code
 params:
   - path: max_completion_tokens

models/alibaba/qwen-flash.yaml

@@ -1,6 +1,7 @@
 # yaml-language-server: $schema=https://modelparams.dev/api/v1/schema.json
 provider: alibaba
 authType: api_key
+apiSurface: openai-chat-completions
 model: qwen-flash
 params:
   - path: max_tokens

models/alibaba/qwen-max.yaml

@@ -1,6 +1,7 @@
 # yaml-language-server: $schema=https://modelparams.dev/api/v1/schema.json
 provider: alibaba
 authType: api_key
+apiSurface: openai-chat-completions
 model: qwen-max
 params:
   - path: max_tokens

models/alibaba/qwen-plus.yaml

@@ -1,6 +1,7 @@
 # yaml-language-server: $schema=https://modelparams.dev/api/v1/schema.json
 provider: alibaba
 authType: api_key
+apiSurface: openai-chat-completions
 model: qwen-plus
 params:
   - path: max_tokens

models/alibaba/qwen-turbo.yaml

@@ -1,6 +1,7 @@
 # yaml-language-server: $schema=https://modelparams.dev/api/v1/schema.json
 provider: alibaba
 authType: api_key
+apiSurface: openai-chat-completions
 model: qwen-turbo
 params:
   - path: max_tokens

models/alibaba/qwen3-235b-a22b-thinking-2507.yaml

@@ -1,6 +1,7 @@
 # yaml-language-server: $schema=https://modelparams.dev/api/v1/schema.json
 provider: alibaba
 authType: api_key
+apiSurface: openai-chat-completions
 model: qwen3-235b-a22b-thinking-2507
 params:
   - path: max_tokens

models/alibaba/qwen3-30b-a3b-instruct-2507.yaml

@@ -1,6 +1,7 @@
 # yaml-language-server: $schema=https://modelparams.dev/api/v1/schema.json
 provider: alibaba
 authType: api_key
+apiSurface: openai-chat-completions
 model: qwen3-30b-a3b-instruct-2507
 params:
   - path: max_tokens

models/alibaba/qwen3-30b-a3b-thinking-2507.yaml

@@ -1,6 +1,7 @@
 # yaml-language-server: $schema=https://modelparams.dev/api/v1/schema.json
 provider: alibaba
 authType: api_key
+apiSurface: openai-chat-completions
 model: qwen3-30b-a3b-thinking-2507
 params:
   - path: max_tokens

models/alibaba/qwen3-coder-flash.yaml

@@ -1,6 +1,7 @@
 # yaml-language-server: $schema=https://modelparams.dev/api/v1/schema.json
 provider: alibaba
 authType: api_key
+apiSurface: openai-chat-completions
 model: qwen3-coder-flash
 params:
   - path: max_tokens

models/alibaba/qwen3-coder-next.yaml

@@ -1,6 +1,7 @@
 # yaml-language-server: $schema=https://modelparams.dev/api/v1/schema.json
 provider: alibaba
 authType: api_key
+apiSurface: openai-chat-completions
 model: qwen3-coder-next
 params:
   - path: max_tokens

models/alibaba/qwen3-coder-plus.yaml

@@ -1,6 +1,7 @@
 # yaml-language-server: $schema=https://modelparams.dev/api/v1/schema.json
 provider: alibaba
 authType: api_key
+apiSurface: openai-chat-completions
 model: qwen3-coder-plus
 status: deprecated
 replacement: alibaba/qwen3.7-plus

models/alibaba/qwen3-max.yaml

@@ -1,6 +1,7 @@
 # yaml-language-server: $schema=https://modelparams.dev/api/v1/schema.json
 provider: alibaba
 authType: api_key
+apiSurface: openai-chat-completions
 model: qwen3-max
 status: active
 params:

models/alibaba/qwen3-next-80b-a3b-instruct.yaml

@@ -1,6 +1,7 @@
 # yaml-language-server: $schema=https://modelparams.dev/api/v1/schema.json
 provider: alibaba
 authType: api_key
+apiSurface: openai-chat-completions
 model: qwen3-next-80b-a3b-instruct
 params:
   - path: max_tokens

models/alibaba/qwen3-next-80b-a3b-thinking.yaml

@@ -1,6 +1,7 @@
 # yaml-language-server: $schema=https://modelparams.dev/api/v1/schema.json
 provider: alibaba
 authType: api_key
+apiSurface: openai-chat-completions
 model: qwen3-next-80b-a3b-thinking
 params:
   - path: max_tokens

models/alibaba/qwen3-vl-235b-a22b-instruct.yaml

@@ -1,6 +1,7 @@
 # yaml-language-server: $schema=https://modelparams.dev/api/v1/schema.json
 provider: alibaba
 authType: api_key
+apiSurface: openai-chat-completions
 model: qwen3-vl-235b-a22b-instruct
 params:
   - path: max_tokens

models/alibaba/qwen3-vl-235b-a22b-thinking.yaml

@@ -1,6 +1,7 @@
 # yaml-language-server: $schema=https://modelparams.dev/api/v1/schema.json
 provider: alibaba
 authType: api_key
+apiSurface: openai-chat-completions
 model: qwen3-vl-235b-a22b-thinking
 params:
   - path: max_tokens

models/alibaba/qwen3.5-122b-a10b.yaml

@@ -1,6 +1,7 @@
 # yaml-language-server: $schema=https://modelparams.dev/api/v1/schema.json
 provider: alibaba
 authType: api_key
+apiSurface: openai-chat-completions
 model: qwen3.5-122b-a10b
 params:
   - path: max_tokens

models/alibaba/qwen3.5-27b.yaml

@@ -1,6 +1,7 @@
 # yaml-language-server: $schema=https://modelparams.dev/api/v1/schema.json
 provider: alibaba
 authType: api_key
+apiSurface: openai-chat-completions
 model: qwen3.5-27b
 params:
   - path: max_tokens

models/alibaba/qwen3.5-35b-a3b.yaml

@@ -1,6 +1,7 @@
 # yaml-language-server: $schema=https://modelparams.dev/api/v1/schema.json
 provider: alibaba
 authType: api_key
+apiSurface: openai-chat-completions
 model: qwen3.5-35b-a3b
 params:
   - path: max_tokens

models/alibaba/qwen3.5-397b-a17b.yaml

@@ -1,6 +1,7 @@
 # yaml-language-server: $schema=https://modelparams.dev/api/v1/schema.json
 provider: alibaba
 authType: api_key
+apiSurface: openai-chat-completions
 model: qwen3.5-397b-a17b
 params:
   - path: max_tokens

models/alibaba/qwen3.5-flash.yaml

@@ -1,6 +1,7 @@
 # yaml-language-server: $schema=https://modelparams.dev/api/v1/schema.json
 provider: alibaba
 authType: api_key
+apiSurface: openai-chat-completions
 model: qwen3.5-flash
 params:
   - path: max_tokens

models/alibaba/qwen3.5.yaml

@@ -1,6 +1,7 @@
 # yaml-language-server: $schema=https://modelparams.dev/api/v1/schema.json
 provider: alibaba
 authType: api_key
+apiSurface: openai-chat-completions
 model: qwen3.5
 params:
   - path: max_tokens

models/alibaba/qwen3.6-27b.yaml

@@ -1,6 +1,7 @@
 # yaml-language-server: $schema=https://modelparams.dev/api/v1/schema.json
 provider: alibaba
 authType: api_key
+apiSurface: openai-chat-completions
 model: qwen3.6-27b
 params:
   - path: max_completion_tokens

models/alibaba/qwen3.6-35b-a3b.yaml

@@ -1,6 +1,7 @@
 # yaml-language-server: $schema=https://modelparams.dev/api/v1/schema.json
 provider: alibaba
 authType: api_key
+apiSurface: openai-chat-completions
 model: qwen3.6-35b-a3b
 params:
   - path: max_completion_tokens

models/alibaba/qwen3.6-flash.yaml

@@ -1,6 +1,7 @@
 # yaml-language-server: $schema=https://modelparams.dev/api/v1/schema.json
 provider: alibaba
 authType: api_key
+apiSurface: openai-chat-completions
 model: qwen3.6-flash
 status: active
 params:

models/alibaba/qwen3.6-max-preview.yaml

@@ -1,6 +1,7 @@
 # yaml-language-server: $schema=https://modelparams.dev/api/v1/schema.json
 provider: alibaba
 authType: api_key
+apiSurface: openai-chat-completions
 model: qwen3.6-max-preview
 status: deprecated
 replacement: alibaba/qwen3.7-max

models/alibaba/qwen3.6-plus.yaml

@@ -1,6 +1,7 @@
 # yaml-language-server: $schema=https://modelparams.dev/api/v1/schema.json
 provider: alibaba
 authType: api_key
+apiSurface: openai-chat-completions
 model: qwen3.6-plus
 params:
   - path: max_completion_tokens