# Models

A model is a reusable AI configuration: a system prompt, a base LLM, response rules, and behaviour settings. Models are versioned — you iterate on drafts without affecting your live chatbots, then publish when ready.

## How models and chatbots relate

A chatbot is the deployed, embeddable unit. A model is the underlying AI configuration. You assign one published model version to a chatbot; that version drives every conversation until you assign a different one.

This separation lets you:
- Work on a new version of your model without touching production.
- Roll back to a previous published version instantly.
- Share one model across multiple chatbots (e.g. the same configuration powering a website widget and a mobile app).

## Creating a model

Go to **Models > New model** in the dashboard. Give it a name and description, then configure the first version.

Via the API:

```bash
curl -X POST "https://api.elaras.ai/api/developer/v1/models" \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Assistant",
    "description": "Handles tier-1 support queries for our SaaS product"
  }'
```

The response includes the model `id` and an initial draft version.

## Model versions

Every change to a model's configuration is made on a **version**. Versions move through two states:

| State | Meaning |
|---|---|
| `draft` | Work in progress — not visible to end users |
| `published` | Active — chatbots assigned to this version serve it to users |

Only one version can be published at a time per model. Publishing a new version automatically unpublishes the previous one.

### Creating a version

```bash
curl -X POST "https://api.elaras.ai/api/developer/v1/models/{model_id}/versions" \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "system_prompt": "You are a friendly support assistant for Acme Corp...",
    "base_model": "claude-sonnet",
    "temperature": 0.3
  }'
```

### Updating a draft version

Draft versions are fully editable:

```bash
curl -X PUT "https://api.elaras.ai/api/developer/v1/models/{model_id}/versions/{version_id}" \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "system_prompt": "Updated system prompt..."
  }'
```

### Publishing a version

When your draft is ready, publish it. Chatbots assigned to this model will immediately start using the new configuration.

```bash
curl -X POST "https://api.elaras.ai/api/developer/v1/models/{model_id}/versions/{version_id}/publish" \
  -H "Authorization: Bearer sk_live_your_key_here"
```

### Cloning a version

Clone an existing version to use it as a starting point for a new draft — useful for A/B testing or gradual prompt refinements.

```bash
curl -X POST "https://api.elaras.ai/api/developer/v1/models/{model_id}/versions/{version_id}/clone" \
  -H "Authorization: Bearer sk_live_your_key_here"
```

Returns a new draft version with identical configuration.

## Listing versions

```bash
curl "https://api.elaras.ai/api/developer/v1/models/{model_id}/versions" \
  -H "Authorization: Bearer sk_live_your_key_here"
```

The response lists versions in reverse chronological order, with their state (`draft` or `published`), creation date, and configuration summary.

## Assigning a model to a chatbot

Once a version is published, assign the model to a chatbot:

```bash
curl -X PUT "https://api.elaras.ai/api/developer/v1/chatbots/{chatbot_id}" \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"model_id": "mdl_abc123"}'
```

The chatbot will use the model's currently published version. When you publish a new version later, the chatbot picks it up automatically — no re-assignment needed.

## Deleting a version

You can delete draft versions. You cannot delete the currently published version of a model that is assigned to a chatbot — unpublish or reassign the chatbot first.

```bash
curl -X DELETE "https://api.elaras.ai/api/developer/v1/models/{model_id}/versions/{version_id}" \
  -H "Authorization: Bearer sk_live_your_key_here"
```

## Workflow example

A typical model iteration cycle:

1. Clone the current published version.
2. Edit the system prompt and temperature in the new draft.
3. Test the draft using [Scenarios](/docs/ask/scenarios) or the dashboard preview.
4. Publish the draft — all assigned chatbots switch over immediately.
5. If something is wrong, re-publish the previous version to roll back.