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

# Train a value candidate

> Start an asynchronous value fit with explicit initialization, observation selection, comparison options, validation settings, and installation controls.

Start a value fit with a required `session_id` and `request_id`. HTTP 202 acknowledges the request; monitor `training.status` through [value state](https://docs.reilabs.org/docs/neuroadapt/value-api/state.md). Set `install: false` for a candidate evaluated separately from the incumbent. [Value training](https://docs.reilabs.org/docs/neuroadapt/value-training.md) explains options, model guards, and report interpretation.

The tables below reproduce request fields from archived schema-version-5 build `0136121bd2cf9d4cdbcb114565c7e1ffb74c5a63`. A default marked "Not declared" is absent from that schema; it does not mean `null`. See [source and response notes](https://docs.reilabs.org/docs/neuroadapt/value-api.md#authentication-and-schema-source) for the evidence scope.

## Path, headers, and query

Send the hosted API key as `Authorization: Bearer <ADAPT1_API_KEY>`. The authenticated identity determines ownership; follow [HTTP and contracts](https://docs.reilabs.org/docs/neuroadapt/request-contracts.md) for the session placeholder.

| Parameter | Location | Required | Type | Constraints |
| - | - | - | - | - |
| `domain_id` | path | Yes | `string` | No further constraint declared |
| `X-Neuroadapt-Session-Id` | header | No | `string` or `null` | No further constraint declared |

`X-Neuroadapt-Session-Id` is a compatibility header present in the archived backend schema. It does not replace the hosted bearer identity.

## JSON body contract

Content type: `application/json`. The HTTP request body is required. The following table describes its fields; linked schema names lead to the complete nested definitions on this page. When an array type also permits `null`, that alternative applies to the entire field, not to individual array items.

## Request body

Schema: `ValueTrainRequest`.

Fields outside this object's declared properties are rejected by the schema.

| Field | Required | Type | Declared default | Constraints |
| - | - | - | - | - |
| `application_cases` | No | array of [ValueApplicationCase](#valueapplicationcase) or `null` | Not declared | 2 to 4096 items |
| `expected_initial_model_sha256` | No | `string` or `null` | Not declared | Pattern `^[0-9a-f]{64}$` |
| `install` | No | `boolean` | `true` | No further constraint declared |
| `observation_ids` | No | array of `string` or `null` | Not declared | 4 to 20000 items |
| `options` | No | [ValueTrainOptions](#valuetrainoptions) | Not declared | No further constraint declared |
| `request_id` | Yes | `string` | Not declared | 1 to 256 characters |
| `session_id` | Yes | `string` | Not declared | At least 1 character |
| `warm_start_source` | No | `string` | `installed` | Values: `installed`, `candidate` |

## ValueApplicationCase

Schema: `ValueApplicationCase`.

Fields outside this object's declared properties are rejected by the schema.

| Field | Required | Type | Declared default | Constraints |
| - | - | - | - | - |
| `case_id` | Yes | `string` | Not declared | 1 to 256 characters |
| `context_sha256` | Yes | `string` | Not declared | Pattern `^[0-9a-f]{64}$` |

## ValueTrainOptions

Schema: `ValueTrainOptions`.

Fields outside this object's declared properties are rejected by the schema.

| Field | Required | Type | Declared default | Constraints |
| - | - | - | - | - |
| `comparison_loss` | No | `string` | `squared` | Values: `squared`, `regret` |
| `comparison_weight` | No | `number` | `0` | Minimum `0`; Maximum `10` |
| `dense_hidden_dimensions` | No | `integer` or `null` | Not declared | Minimum `8`; Maximum `256` |
| `dense_inputs` | No | `boolean` | `true` | No further constraint declared |
| `dimensions` | No | `integer` | `64` | Minimum `8`; Maximum `4096` |
| `epochs` | No | `integer` | `200` | Minimum `1`; Maximum `2000` |
| `function_retention_weight` | No | `number` | `0` | Minimum `0`; Maximum `100` |
| `interaction_selection` | No | `string` or `null` | Not declared | Values: `lexical`, `evidence` |
| `learning_rate` | No | `number` | `0.003` | Greater than `0`; Maximum `1` |
| `loss_function` | No | `string` | `squared` | Values: `squared`, `log_loss` |
| `model_type` | No | `string` | `mlp_v2` | Values: `linear`, `mlp_v2`, `object_value` |
| `object_hidden_dimensions` | No | `integer` or `null` | Not declared | Minimum `8`; Maximum `256` |
| `pair_geometry` | No | `boolean` | `false` | No further constraint declared |
| `peak_pooling` | No | `boolean` or `null` | Not declared | No further constraint declared |
| `preserve_binary_inputs` | No | `boolean` | `true` | No further constraint declared |
| `primary_validation_episode_ids` | No | array of `string` or `null` | Not declared | 1 to 10000 items |
| `quadratic_pairs` | No | `boolean` | `false` | No further constraint declared |
| `selection_objective` | No | `string` | `prediction` | Values: `prediction`, `comparison_regret`, `adaptation_prediction` |
| `supervision_scope` | No | `string` | `all` | Values: `all`, `terminal_and_continuation`, `provided_and_terminal`, `provided_terminal_and_continuation` |
| `trainable_layers` | No | `string` | `all` | Values: `all`, `readout`, `new_inputs` |
| `validation_episode_ids` | No | array of `string` or `null` | Not declared | 1 to 10000 items |
| `validation_mode` | No | `string` | `chronological` | Values: `chronological`, `episode_hash` |
| `warm_start` | No | `boolean` | `true` | No further constraint declared |

## Responses

| HTTP status | Archived contract |
| - | - |
| 202 | Accepted training request; inspect `training.status` through [value state](https://docs.reilabs.org/docs/neuroadapt/value-api/state.md). |
| 422 | Request validation error; the archived schema references `HTTPValidationError`. |

The archived validation shape has an optional `detail` array. Each validation entry requires `loc` (an array of strings or integers), `msg` (string), and `type` (string); it can also include `ctx` (object) and `input` (any JSON value). Recorded operational refusals can have their own error details.

`warm_start_source`, `install`, `observation_ids`, and `expected_initial_model_sha256` are request-level fields. `warm_start` and the other fitting controls belong inside `options`. The per-fit continuation workload limit is separate from per-row schema bounds; see [training and reports](https://docs.reilabs.org/docs/neuroadapt/value-training.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.