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

# Versions API

> Publish, list, compare, and rollback prompt and model versions.

## Publish a Version

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.trainlyai.com/v1/{project_id}/versions \
    -H "Authorization: Bearer tk_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "version": "1.3.0",
      "description": "Switch to gpt-4o, tighten system prompt for conciseness."
    }'
  ```
</CodeGroup>

`POST /v1/{project_id}/versions`

### Request Body

| Parameter     | Type   | Required | Description                            |
| ------------- | ------ | -------- | -------------------------------------- |
| `version`     | string | Yes      | Semver version string (e.g. `"1.3.0"`) |
| `description` | string | No       | Summary of changes in this version     |

### Response

```json theme={null}
{
  "version_id": "ver_j1k2l3m4",
  "version": "1.3.0",
  "created_at": "2026-04-07T15:00:00Z"
}
```

***

## List Versions

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.trainlyai.com/v1/{project_id}/versions" \
    -H "Authorization: Bearer tk_your_api_key"
  ```
</CodeGroup>

`GET /v1/{project_id}/versions`

### Response

```json theme={null}
[
  {
    "version_id": "ver_j1k2l3m4",
    "version": "1.3.0",
    "description": "Switch to gpt-4o, tighten system prompt for conciseness.",
    "is_active": true,
    "created_at": "2026-04-07T15:00:00Z"
  },
  {
    "version_id": "ver_f5g6h7i8",
    "version": "1.2.0",
    "description": "Add few-shot examples to system prompt.",
    "is_active": false,
    "created_at": "2026-03-28T10:30:00Z"
  }
]
```

***

## Get Version Details

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.trainlyai.com/v1/{project_id}/versions/ver_j1k2l3m4" \
    -H "Authorization: Bearer tk_your_api_key"
  ```
</CodeGroup>

`GET /v1/{project_id}/versions/{version_id}`

### Response

```json theme={null}
{
  "version_id": "ver_j1k2l3m4",
  "version": "1.3.0",
  "description": "Switch to gpt-4o, tighten system prompt for conciseness.",
  "is_active": true,
  "trace_count": 1240,
  "avg_latency_ms": 695.3,
  "avg_cost": 0.0031,
  "created_at": "2026-04-07T15:00:00Z"
}
```

***

## Rollback to a Version

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.trainlyai.com/v1/{project_id}/versions/ver_f5g6h7i8/rollback \
    -H "Authorization: Bearer tk_your_api_key"
  ```
</CodeGroup>

`POST /v1/{project_id}/versions/{version_id}/rollback`

### Response

```json theme={null}
{
  "version_id": "ver_f5g6h7i8",
  "version": "1.2.0",
  "is_active": true,
  "rolled_back_at": "2026-04-07T15:30:00Z"
}
```

***

## Compare Versions

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.trainlyai.com/v1/{project_id}/versions/compare?a=ver_f5g6h7i8&b=ver_j1k2l3m4" \
    -H "Authorization: Bearer tk_your_api_key"
  ```
</CodeGroup>

`GET /v1/{project_id}/versions/compare`

### Query Parameters

| Parameter | Type   | Required | Description       |
| --------- | ------ | -------- | ----------------- |
| `a`       | string | Yes      | First version ID  |
| `b`       | string | Yes      | Second version ID |

### Response

```json theme={null}
{
  "version_a": {
    "version_id": "ver_f5g6h7i8",
    "version": "1.2.0",
    "avg_latency_ms": 812.1,
    "avg_cost": 0.0028,
    "total_traces": 8430,
    "error_rate": 0.012
  },
  "version_b": {
    "version_id": "ver_j1k2l3m4",
    "version": "1.3.0",
    "avg_latency_ms": 695.3,
    "avg_cost": 0.0031,
    "total_traces": 1240,
    "error_rate": 0.008
  },
  "diff": {
    "latency_change_pct": -14.4,
    "cost_change_pct": 10.7,
    "error_rate_change_pct": -33.3
  }
}
```