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

# Models API

> Create and configure AI assistants with the Cuadra AI Models API. Choose LLM providers, link datasets for RAG, and attach system prompts.

## Available Models

Cuadra AI supports models from multiple leading AI providers. Use the catalog endpoint to discover what's available:

```bash theme={null}
curl https://api.cuadra.ai/v1/models/catalog \
  -H "Authorization: Bearer YOUR_TOKEN"
```

<Tip>
  The catalog returns all available base models with their capabilities, context windows, and pricing. Use `parentModelId` from the catalog when creating your custom model.
</Tip>

***

## Quick Start

First, get a `parentModelId` from the catalog, then create your custom model:

<CodeGroup>
  ```bash curl theme={null}
  # 1. List available base models
  curl https://api.cuadra.ai/v1/models/catalog \
    -H "Authorization: Bearer YOUR_TOKEN"

  # 2. Create a model using a parent model ID
  curl -X POST https://api.cuadra.ai/v1/models \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: create-model-001" \
    -d '{
      "parentModelId": "PARENT_MODEL_ID_FROM_CATALOG",
      "displayName": "Support Bot"
    }'
  ```

  ```python Python theme={null}
  import httpx

  # 1. Get parent model ID from catalog
  catalog = httpx.get(
      "https://api.cuadra.ai/v1/models/catalog",
      headers={"Authorization": "Bearer YOUR_TOKEN"}
  ).json()
  parent_id = catalog["items"][0]["id"]

  # 2. Create your model
  response = httpx.post(
      "https://api.cuadra.ai/v1/models",
      headers={"Authorization": "Bearer YOUR_TOKEN", "Idempotency-Key": "create-model-001"},
      json={"parentModelId": parent_id, "displayName": "Support Bot"}
  )
  model = response.json()
  print(f"Created model: {model['id']}")
  ```

  ```typescript Node.js theme={null}
  // 1. Get parent model ID from catalog
  const catalogRes = await fetch('https://api.cuadra.ai/v1/models/catalog', {
    headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
  });
  const catalog = await catalogRes.json();
  const parentId = catalog.items[0].id;

  // 2. Create your model
  const response = await fetch('https://api.cuadra.ai/v1/models', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json',
      'Idempotency-Key': 'create-model-001'
    },
    body: JSON.stringify({ 
      parentModelId: parentId, 
      displayName: 'Support Bot'
    })
  });
  const model = await response.json();
  console.log(`Created model: ${model.id}`);
  ```
</CodeGroup>

<Tip>
  The `parentModelId` comes from `GET /v1/models/catalog`. These are pre-configured system models with standard pricing.
</Tip>

***

## Linking Datasets (RAG)

Connect a knowledge base to enable retrieval-augmented generation:

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.cuadra.ai/v1/models/model_abc123/datasets \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"datasetId": "ds_xyz789", "usageType": "rag"}'
  ```

  ```python Python theme={null}
  import httpx

  response = httpx.post(
      "https://api.cuadra.ai/v1/models/model_abc123/datasets",
      headers={"Authorization": "Bearer YOUR_TOKEN"},
      json={"datasetId": "ds_xyz789", "usageType": "rag"}
  )
  print("Dataset linked to model")
  ```

  ```typescript Node.js theme={null}
  await fetch('https://api.cuadra.ai/v1/models/model_abc123/datasets', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ datasetId: 'ds_xyz789', usageType: 'rag' })
  });
  console.log('Dataset linked to model');
  ```
</CodeGroup>

### Usage Types

| Usage Type | Behavior                                      | Best For                    |
| ---------- | --------------------------------------------- | --------------------------- |
| `rag`      | Search and retrieve relevant chunks per query | Large knowledge bases       |
| `context`  | Always include entire dataset in context      | Small, always-relevant docs |

***

## Attaching System Prompts

Configure model behavior with a system prompt:

```bash theme={null}
curl -X PATCH https://api.cuadra.ai/v1/models/model_abc123 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"systemPromptId": "sysprompt_xyz"}'
```

<Tip>
  Use the [Particles API](/api-reference/particles) to create modular, reusable prompt components.
</Tip>

***

## FAQ

### Can I switch LLM providers without changing code?

Yes. Update the model's `parentModelId` via PATCH to point to a different base model. Your integration code using `modelId` stays the same.

### What's the difference between model and parentModelId?

Your `model` is a Cuadra AI model (custom displayName, linked datasets, system prompt). `parentModelId` references the underlying base model from the catalog.

### How many datasets can I link?

No hard limit. However, more datasets = more RAG tokens = higher cost. Link only relevant datasets.

### Do model changes affect existing conversations?

No. Conversations use the model configuration at creation time. Changes apply to new chats only.

***

## Related

<CardGroup cols={2}>
  <Card title="Chat API" icon="comments" href="/api-reference/chat">
    Use models in chat
  </Card>

  <Card title="System Prompts" icon="sliders" href="/guides/system-prompts">
    Configure behavior
  </Card>
</CardGroup>