> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brainstormer.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Models

> Browse and search available AI models synced from OpenRouter.

# Models

Brainstormer syncs available AI models from OpenRouter and stores them locally with pricing, capabilities, and recommendation scoring. These endpoints let you browse, filter, and search models.

<Note>
  All API requests require a valid JWT token in the `Authorization: Bearer <token>` header. The API Gateway decodes the JWT and forwards auth context (`user-id`, `organization-id`, `user-email`, `x-platform-role`, `x-org-role`) as headers to downstream services.
</Note>

## List All Models

<ParamField method="GET" path="/api/models" />

Get all available AI models.

### Query Parameters

<ParamField query="include_inactive" type="string">
  Set to `"true"` to include inactive/deprecated models. Default: only active models.
</ParamField>

### Response (200)

<ResponseField name="success" type="boolean">Always `true`.</ResponseField>
<ResponseField name="count" type="number">Number of models returned.</ResponseField>

<ResponseField name="models" type="object[]">
  Array of model objects.

  <Expandable title="Model object">
    <ResponseField name="id" type="string">Model ID (e.g., `openai/gpt-4o`).</ResponseField>
    <ResponseField name="name" type="string">Human-readable model name.</ResponseField>
    <ResponseField name="provider" type="string">Provider name (e.g., `openai`, `anthropic`, `google`).</ResponseField>
    <ResponseField name="contextLength" type="number">Maximum context window in tokens.</ResponseField>
    <ResponseField name="promptPricePerToken" type="number">Input price per token in USD.</ResponseField>
    <ResponseField name="completionPricePerToken" type="number">Output price per token in USD.</ResponseField>
    <ResponseField name="isActive" type="boolean">Whether the model is currently available.</ResponseField>
    <ResponseField name="isFree" type="boolean">Whether the model is free to use.</ResponseField>
    <ResponseField name="capabilities" type="object">Model capabilities (vision, function calling, etc.).</ResponseField>
    <ResponseField name="recommendationScore" type="number">Platform recommendation score.</ResponseField>
    <ResponseField name="lastSyncedAt" type="string">ISO 8601 timestamp of last sync.</ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```bash curl theme={null}
  curl https://your-domain.com/api/models \
    -H "Authorization: Bearer $TOKEN"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://your-domain.com/api/models", {
    headers: { Authorization: `Bearer ${token}` },
  });

  const { models, count } = await response.json();
  ```
</CodeGroup>

***

## Get Model by ID

<ParamField method="GET" path="/api/models/:id" />

Get detailed information about a specific model.

### Path Parameters

<ParamField path="id" type="string" required>
  Model ID (e.g., `openai/gpt-4o`). The ID includes the provider prefix.
</ParamField>

### Response (200)

<ResponseField name="success" type="boolean">Always `true`.</ResponseField>
<ResponseField name="model" type="object">Full model object (see schema above).</ResponseField>

```bash curl theme={null}
curl https://your-domain.com/api/models/openai%2Fgpt-4o \
  -H "Authorization: Bearer $TOKEN"
```

<Note>
  Model IDs contain a forward slash (e.g., `openai/gpt-4o`). URL-encode the slash as `%2F` in the path.
</Note>

***

## Filter by Provider

<ParamField method="GET" path="/api/models/provider/:provider" />

Get all models from a specific provider.

### Path Parameters

<ParamField path="provider" type="string" required>
  Provider name (e.g., `openai`, `anthropic`, `google`, `meta-llama`).
</ParamField>

### Response (200)

<ResponseField name="success" type="boolean" />

<ResponseField name="models" type="object[]">Filtered model array.</ResponseField>

<ResponseField name="count" type="number" />

<ResponseField name="provider" type="string">The provider filter applied.</ResponseField>

***

## Filter Free Models

<ParamField method="GET" path="/api/models/filter/free" />

Get all models that are free to use (no per-token cost).

### Response (200)

<ResponseField name="success" type="boolean" />

<ResponseField name="models" type="object[]">Free models only.</ResponseField>

<ResponseField name="count" type="number" />

***

## Filter by Use Case

<ParamField method="GET" path="/api/models/usecase/:usecase" />

Get models recommended for a specific use case.

### Path Parameters

<ParamField path="usecase" type="string" required>
  Use case identifier (e.g., `chat`, `coding`, `creative`, `analysis`).
</ParamField>

***

## Search Models

<ParamField method="GET" path="/api/models/search/:query" />

Full-text search across model names, descriptions, and providers.

### Path Parameters

<ParamField path="query" type="string" required>
  Search query string.
</ParamField>

### Response (200)

<ResponseField name="success" type="boolean" />

<ResponseField name="models" type="object[]">Matching models.</ResponseField>

<ResponseField name="count" type="number" />

<ResponseField name="query" type="string">The search query applied.</ResponseField>

```bash curl theme={null}
curl https://your-domain.com/api/models/search/claude \
  -H "Authorization: Bearer $TOKEN"
```

***

## Get Model Validation Rules

<ParamField method="GET" path="/api/models/:id/validation" />

Get validation rules for a specific model (context limits, supported features).

### Path Parameters

<ParamField path="id" type="string" required>Model ID.</ParamField>

### Response (200)

<ResponseField name="success" type="boolean" />

<ResponseField name="modelId" type="string" />

<ResponseField name="validation" type="object">
  Validation rules including max tokens, supported input types, and constraints.
</ResponseField>

***

## Trigger Model Sync (Admin)

<ParamField method="POST" path="/api/admin/model-sync/trigger" />

Trigger a manual sync of models from OpenRouter. Requires superadmin access.

### Response (200)

Returns sync status and count of models updated.

<Note>
  Models are automatically synced on a periodic schedule. Manual sync is only needed if you want to pick up new models immediately.
</Note>