> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.agentrouter.to/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.agentrouter.to/_mcp/server.

# Models

The `models` domain gives an agent one API key for model discovery and inference.

The normal flow is:

1. call **List All Models** to get the live catalog
2. copy a returned `models[].id`
3. pass that ID as `model` to **Chat Completion**
4. read the generated text from `completionText`
5. read the final debit from `creditsCharged`

> **Note**
>
> `models[].id` is the value used by Chat Completion's `model` field. Code Completion uses route-specific model IDs, so do not assume every chat model supports the code endpoint.

## Models APIs

| API                                                | Use it for                                                           | Required input      | Price              |
| -------------------------------------------------- | -------------------------------------------------------------------- | ------------------- | ------------------ |
| [List All Models](/domains/models/list-all-models) | Live IDs, context windows, supported parameters, and price estimates | none                | 0 credits          |
| [Chat Completion](/domains/models/chat-completion) | Writing, reasoning, extraction, JSON, HTML, and conversational work  | `model`, `messages` | quoted per request |
| [Code Completion](/domains/models/code-completion) | Complete code after a prefix or fill between a prefix and suffix     | `model`, `prompt`   | quoted per request |

## Install and authenticate

```bash
npm install @agentrouter/agentrouter
export AGENTIC_API_KEY=aak_...
```

```ts
import { AgentRouterClient } from "@agentrouter/agentrouter";

const client = new AgentRouterClient({
  apiKey: process.env.AGENTIC_API_KEY,
});
```

Keep the API key on your server. Do not place it in browser code.

## Complete example

```ts
const catalog = await client.models.catalog.list();

const model = catalog.models.find(
  (candidate) => candidate.id === "openai/gpt-4.1-nano",
);

if (!model) throw new Error("Model is not currently available");

const result = await client.models.chat.complete.execute(
  {
    model: model.id,
    messages: [
      { role: "user", content: "Write a one-line product hero." },
    ],
    max_tokens: 120,
  },
  { allowFallback: true },
);

console.log(result.completionText);
console.log(result.creditsCharged);
```

## Pricing model

AgentRouter uses credits, where **1,000 credits = \$1 USD**.

The model catalog exposes estimated input and output rates in credits per one million tokens. Paid inference is quoted for the concrete request. The returned `creditsCharged` value is the authoritative final debit.

```text
estimated request credits
= input tokens × input credits per 1M / 1,000,000
+ output tokens × output credits per 1M / 1,000,000
```

The estimate helps compare models; it is not a flat per-request price.

## Routing

AgentRouter currently exposes model routes through OpenRouter, DeepSeek, and Groq. You can let AgentRouter choose a compatible route or pin one with `routeKey`.

```ts
const result = await client.models.chat.complete.execute(input, {
  routeKey: "models.chat.complete.openrouter.mpp",
  allowFallback: false,
});
```

Use route context for the exact provider-specific parameters:

```ts
const context = await client.catalog.routes.context(
  "models.chat.complete.openrouter.mpp",
);

console.log(context.execute?.fields);
```

> **Note**
>
> The top-level models capability contract is currently partial. Route context is the machine-readable source of truth for the exact executable fields on a concrete route.

## Next steps

* [List All Models](/domains/models/list-all-models)
* [Run Chat Completion](/domains/models/chat-completion)
* [Run Code Completion](/domains/models/code-completion)