feat(api): publish per-model capability metadata #105

Context

NaN's OpenAI-compatible GET /v1/models currently returns the standard identity fields (id, object, created, owned_by) but not the model limits or capabilities that clients need to configure a model correctly. As a result, clients such as the official CLI, Pi provider, and third-party VS Code Language Model Chat Providers maintain separate model catalogs; those catalogs drift when NaN adds or changes models. This also relates to #11, which investigates model discovery for VS Code.

The recently documented GET /v1/usage helps with token-usage metrics, but does not provide model capability metadata. This request is separate from #98, which concerns account usage/quota.

Goal

Let API-key clients discover the capabilities and limits of the models returned for that key from a documented, machine-readable NaN catalog, without maintaining a hand-curated model list.

Requested scope

• Extend /v1/models additively with optional, documented per-model metadata, or provide a linked model-detail/catalog endpoint if that is safer for OpenAI SDK compatibility.
• Evaluate fields that clients can consume consistently, such as:
  • context-window and maximum-output-token limits;
  • input/output modalities;
  • tool-calling support and, where relevant, the supported protocol/format (for example, OpenAI function tool calls versus XML);
  • reasoning support and documented effort values, distinguishing adjustable, adaptive, and model-managed behavior;
  • model availability/tier and published quota limits/windows, when those values are authoritative for the API key.
• Keep the schema OpenAPI-documented and define whether absent fields mean unknown, unsupported, or not applicable. Do not make clients infer false or unlimited from a missing field.
• Keep the list key-aware so it remains the source of truth for which model IDs the user's API key can actually use.
• Define how the catalog is versioned/refreshed and how capability changes are communicated.

Pricing question (not a blocker)

NaN is subscription/quota based, so a per-token USD price should not be presented as a charge from NaN. However, model routers and pickers sometimes consume price metadata. Please evaluate whether an optional, explicitly reference-only upstream/provider price could be useful to clients. If so, it should identify source, currency, unit (for example, per million input/output tokens), and observation/update time, and must not be confused with NaN billing or quota consumption. It is also acceptable to omit pricing entirely unless NaN can publish trustworthy, current values.

Non-goals

• Change NaN's subscription billing or introduce per-token billing.
• Return account-wide usage/remaining quota here; see feat(api): expose documented usage and quota for API-key clients #98 and the usage endpoint work tracked by feat: public usage endpoint GET /v1/usage for member token metrics #102.
• Require clients to trust third-party model catalogs as the source of truth for NaN deployments.

Acceptance criteria

• Given a valid API key, when a client calls the published model catalog, then it receives the models available to that key and documented capability metadata for fields NaN can authoritatively provide.
• Given a model without a known value for a field, when it is returned, then the schema represents that field as absent/unknown rather than asserting unsupported or unlimited.
• The OpenAPI schema, examples, and model documentation describe the fields and their semantics.
• Changes remain backward-compatible with OpenAI-compatible clients that only read standard model identity fields.
• Pricing, if published, is clearly reference-only and cannot be mistaken for NaN's subscription cost; otherwise the spec omits it.
• At least one API client can consume the catalog without maintaining a duplicate hard-coded capability list.

Validation

Validate the OpenAPI contract and examples, verify returned values against deployed models, and test list filtering against API-key model access. Verify that unknown/null fields cannot be interpreted as zero, unsupported, or unlimited by clients.

Related work

• VS Code provider/model discovery investigation: Detección automática de modelos para VS Code (INVESTIGANDO...) #11
• API-key usage and quota contract: feat(api): expose documented usage and quota for API-key clients #98
• Usage metrics endpoint: feat: public usage endpoint GET /v1/usage for member token metrics #102 and documentation PR #103
• VS Code's extension-provider reasoning forwarding: microsoft/vscode#319794