# AI Models

An **AI Model** is an LLM (or transcription / file-analysis model) that Frontline exposes to agents and workflows. Models are managed by Frontline — you cannot create or modify them via the Public API. You only **discover** them and reference them by `id` or by `model` + `aiVendor` from elsewhere.

## Identity

| Field | Type | Notes |
|  --- | --- | --- |
| `id` | number | Catalog ids are often negative; use as `aiModelId` when configuring agents or nodes. |
| `name` | string | Display name (e.g. `GPT-4o`, `Claude 3.5 Sonnet`). |
| `description` | string? | Marketing-style summary. |
| `type` | enum | `TEXT` · `TRANSCRIPTION` · `FILE_ANALYSIS`. |
| `aiVendor` | string? | E.g. `OPENAI`, `ANTHROPIC`, `GOOGLE`. |
| `reasoningModel` | boolean? | `true` for thinking-tier models. |
| `creditsPerMessage` | number? | Cost in Frontline credits per message generated. |
| `isDefault` | boolean? | Whether this is the default model for its `type`. |
| `order` | number? | Display order in the UI. |
| `analyticsColor` | string? | Hex color used in dashboards. |
| `externalId` | string? | Provider-side identifier (use as `model` on nodes). |


## Model types and where to use them

| `type` | Typical use |
|  --- | --- |
| `TEXT` | Agent settings, `TOOLS_AI`, `AI_CAPTURE`, `DATA_TRANSFORMER`, `CONDITIONAL_ROUTING` (AI mode), `SAY_AI`, `RESPONSE_AI`, and `SEND_MESSAGE` dynamic messages. |
| `TRANSCRIPTION` | Automation `TRANSCRIPTION` nodes. |
| `FILE_ANALYSIS` | Automation `FILE_ANALYSIS` nodes (OCR + structured analysis). |


Pick models with `GET /public/v1/ai-models?type=TEXT` (or `TRANSCRIPTION` / `FILE_ANALYSIS`). The API validates that each node references an existing, non-deprecated model of the correct type.

## Where they are used

- **[Agent](/docs/concepts/agents) settings** — set `aiModelId` in `PUT /agents/{agentId}/agent-setting` to change the model an agent uses for conversation. Frontline validates the ID before saving.
- **Workflow nodes** — AI-flavored nodes may set `aiModelId`, or `model` + `aiVendor`. When omitted, the runtime may use account defaults where supported; any explicit reference is validated at save time.
- **Transcription / file analysis** — use models whose `type` matches the node.


## Defaults

Frontline ships defaults per model `type`:

```
GET /public/v1/ai-models/default?type=TEXT
GET /public/v1/ai-models/default?type=TRANSCRIPTION
GET /public/v1/ai-models/default?type=FILE_ANALYSIS
```

If you don't pin a specific `aiModelId`, Frontline falls back to these where the node allows it.

## Operations

| Verb | Path | Purpose |
|  --- | --- | --- |
| `GET` | `/public/v1/ai-models` | List (optional `type` filter) |
| `GET` | `/public/v1/ai-models/default` | Get default for a `type` |
| `GET` | `/public/v1/ai-models/{aiModelId}` | Detail |


Read-only. Listing accepts `type=TEXT`, `type=TRANSCRIPTION`, or `type=FILE_ANALYSIS` to filter.

## CLI

```bash
frontline ai-models list --type TEXT --table
frontline ai-models list --type FILE_ANALYSIS --table
frontline ai-models default --type TEXT
frontline ai-models describe -1
```

Use the returned `id` as `aiModelId`, or `externalId` + `aiVendor` as `model` + `aiVendor` on workflow nodes.