Models

The /v1/models endpoint returns the complete catalog of artificial intelligence models, multimodal engines, and smart router aliases available to your authenticated virtual key (sk-nrouter-...). Use this endpoint to dynamically discover available models, query context window ceilings, verify provider availability, and build responsive model selectors in client applications.

GET https://api.nrouter.ai/v1/models

Architectural Role & Lifecycle

Model discovery is decoupled from rigid vendor configurations through nRouter's dynamic catalog architecture:

1. Phase 1: In-Memory Key Auth & ACL Filtering: When a request reaches /v1/models, nRouter hashes the virtual key (sk-nrouter-...) and inspects the tenant's organization policy. The returned catalog is dynamically filtered so that caller applications only see models they are permitted to route to.
2. Catalog Synchronization: The model catalog is synchronized across gateway nodes and hot-reloads within 60 seconds whenever models are added, updated, or deprecated by administrators.
3. Zero Inference Billing: Querying /v1/models is a metadata retrieval operation and incurs $0 in token spend. No credit reservation hold is applied.
4. Router Aliases vs. Concrete Models: The endpoint returns both concrete physical models (e.g. gpt-5.5, claude-sonnet-4-5-20250929, gemini-2.5-pro) and virtual smart router aliases (e.g. nrouter/auto, fastest-claude) that dynamically resolve routing chains based on real-time cloud latency and price ceilings.

Request Headers

Response Payloads

Standard Response Structure

{
  "object": "list",
  "data": [
    {
      "id": "gpt-5.5",
      "object": "model",
      "created": 1709251200,
      "owned_by": "openai"
    },
    {
      "id": "claude-sonnet-4-5-20250929",
      "object": "model",
      "created": 1709251200,
      "owned_by": "anthropic"
    },
    {
      "id": "gemini-2.5-pro",
      "object": "model",
      "created": 1709251200,
      "owned_by": "google"
    },
    {
      "id": "nrouter/auto",
      "object": "model",
      "created": 1709251200,
      "owned_by": "nrouter"
    }
  ]
}

Response Field Breakdown

Supported Provider Clouds & Model Families

nRouter routes requests across six enterprise cloud provider networks behind a single unified API key:

SDK Code Examples

import { nRouter } from "@nrouter_ai/sdk";

const client = new nRouter({
  apiKey: process.env.NROUTER_API_KEY,
});

const models = await client.models.list();
console.log(`Found ${models.data.length} available models:`);

for (const model of models.data) {
  console.log(`- ${model.id} (${model.owned_by})`);
}

Dynamic Model Selection Pattern

Using /v1/models, frontend and backend applications can dynamically generate model selection dropdowns that stay automatically synchronized with your organization's enabled catalog:

import OpenAI from "openai";

export async function fetchEligibleModels(): Promise<string[]> {
  const client = new OpenAI({
    apiKey: process.env.NROUTER_API_KEY,
    baseURL: "https://api.nrouter.ai/v1",
  });

  const response = await client.models.list();
  return response.data
    .map((m) => m.id)
    .sort((a, b) => a.localeCompare(b));
}

Error Handling & Status Codes

{
  "error": {
    "type": "invalid_api_key",
    "message": "Invalid or missing virtual key.",
    "code": "invalid_api_key"
  }
}