> ## 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.

# Value learner API reference

> Find all eight value routes, their request envelopes and limits, model identity controls, and the schema sources used by the integration guides.

The Adapt-1 value API manages observations, fitting, prediction, candidates, and the retained value model for a Domain. All eight operations use `POST /api/v1/domains/{domain_id}/value/` followed by the operation name. Use the [learning workflow](https://docs.reilabs.org/docs/neuroadapt/value-learning.md) for their execution order and the endpoint pages below for the captured request fields, types, defaults, and limits.

## Authentication and schema source

Use the authenticated client and hosted identity rules in [HTTP and contracts](https://docs.reilabs.org/docs/neuroadapt/request-contracts.md). The value request schemas require a nonempty `session_id`. On the hosted proxy, use `"ignored"` as the compatibility placeholder; the bearer token determines the effective identity.

Read `GET /version` at the API host root to identify the deployment build. The manual value and planning references use request schemas captured from schema-version-5 build `0136121bd2cf9d4cdbcb114565c7e1ffb74c5a63`. Response-field notes also draw on recorded integrations from build `d261adb42eedea7135f3e7b358877e5b33dde1eb`; the later behavior checks are from build `af6670b` on 6 November 2026. Keep these sources distinct when comparing a deployed request or default with a recorded result.

The captured contract defines request fields and success status codes but leaves success response bodies untyped. The guides document observed response fields; validate the fields your application consumes. The `train` success status is `202`; the other value operations declare `200`.

## Routes

| Operation | Endpoint reference | Main request content |
| - | - | - |
| Configure | [Configure](https://docs.reilabs.org/docs/neuroadapt/value-api/configure.md) | `session_id`, `config` |
| Admit observations | [Observe](https://docs.reilabs.org/docs/neuroadapt/value-api/observe.md) | `session_id`, `observations`, optional `application_outcomes` |
| Start a fit | [Train](https://docs.reilabs.org/docs/neuroadapt/value-api/train.md) | `session_id`, `request_id`, `options`, installation and initial-model controls |
| Predict values | [Predict](https://docs.reilabs.org/docs/neuroadapt/value-api/predict.md) | `session_id`, `inputs`, model source and optional expected hash |
| Adopt a candidate | [Promote](https://docs.reilabs.org/docs/neuroadapt/value-api/promote.md) | `session_id`, expected candidate hash, optional incumbent hash and canary |
| Freeze the value model | [Freeze](https://docs.reilabs.org/docs/neuroadapt/value-api/freeze.md) | `session_id`, expected model hash |
| Inspect value state | [State](https://docs.reilabs.org/docs/neuroadapt/value-api/state.md) | `session_id` |
| Reset value state | [Reset](https://docs.reilabs.org/docs/neuroadapt/value-api/reset.md) | `session_id` |

## Configure

`config.relation` and `config.policy` are required nonempty strings. Use the identifiers for your application's value relation and policy. `representation` is `projected` by default or `object_graph`. `max_samples` defaults to `20000` and accepts integers from `4` to `250000`.

```json Configure request theme={null}
{
  "session_id": "ignored",
  "config": {
    "relation": "terminal_utility",
    "policy": "state_value",
    "representation": "object_graph",
    "max_samples": 20000,
    "promotion": {
      "mode": "prediction",
      "minimum_cases": 16,
      "required_improvement": 0.0,
      "maximum_prediction_regression": 0.05
    }
  }
}
```

The identifiers above are application examples. Preserve your chosen value scale and perspective across fitting, prediction, and planning. Inspect the returned configuration and `status: configured` before uploading observations.

## Observe and train

`value/observe` accepts at most 50 observation rows per request and at most 50 application-outcome rows. Each observation requires `record_id`, `episode_id`, and nonnegative `step`. The observed admission rule requires exactly one of `target`, `outcome`, or `continuation`.

See [value observations](https://docs.reilabs.org/docs/neuroadapt/value-observations.md) for complete request construction, continuations, comparison groups, and exact-replay behavior.

`value/train` requires `session_id` and `request_id`. Put `warm_start` inside `options`; put `warm_start_source`, `expected_initial_model_sha256`, `observation_ids`, and `install` at the request level. Both `options.warm_start` and `install` default to `true`. Make these choices explicit in integration code.

Use `install: false` when fitting a candidate for a separate application comparison. HTTP 202 acknowledges the training request; inspect `value/state` and its `training` report for completion and adoption. See [value training](https://docs.reilabs.org/docs/neuroadapt/value-training.md).

## Predict

`value/predict` accepts between 1 and 256 `inputs`. Set `model_source` to `installed` (default) or `candidate`; `expected_model_sha256` can bind the intended model. An input can carry `objects`, `relations`, `conditions`, `context`, and `policy_features`, plus `include_positions` and `include_moments`.

```json Prediction request theme={null}
{
  "session_id": "ignored",
  "model_source": "installed",
  "inputs": [
    {
      "policy_features": {
        "progress": 0.25
      }
    }
  ]
}
```

This input illustrates an application-defined numeric feature. Use the same representation and feature meanings as the fitted model. For a model-bound evaluation, add the actual `expected_model_sha256` from state before submitting the request.

The schema also accepts optional `counterparts` containing 1 to 256 value inputs and `complementary_total`, default `1`. The pairing and transformation semantics are not established by the available integration checks; confirm that contract before enabling this optional path.

## Promote and freeze

`value/promote` requires the expected candidate SHA-256. Supply the incumbent hash as well when performing a paired comparison so the call remains bound to the evaluated model pair. The [promotion guide](https://docs.reilabs.org/docs/neuroadapt/value-promotion.md) covers the canary and observed rejection rules.

`value/freeze` requires `session_id` and a 64-character `expected_model_sha256`. The schema has no Boolean freeze flag or unfreeze field. Bind the model you intend to evaluate, then inspect `frozen` and the model identity in returned state. Plan the resumption of learning against the deployment's supported controls; do not invent an unfreeze parameter.

## Inspect and reset

Both `value/state` and `value/reset` accept the following body:

```json State or reset request body theme={null}
{
  "session_id": "ignored"
}
```

The routes perform different operations despite sharing a request schema. Use `value/state` for inspection and uncertain-write reconciliation. Recorded responses expose `config`, `sample_count`, `dataset_version`, `dataset_sha256`, `model`, `candidate`, `training`, and `frozen`.

Use `value/reset` only for an intended value-state reset. Its request schema does not specify which records or configuration survive; verify those postconditions for the deployment before relying on them. It is a different route from Domain `/clear` or `/policy/reset`.

## Handle refusals and retries

The observed value workflow can reject invalid supervision, missing fitted references, missing evidence or groups in a partition, excessive continuation work, conflicting record IDs, and unsuccessful promotion canaries. Preserve the response reason and the relevant model and dataset identities before changing a request.

Observation `record_id` replay and feedback `ref` replay have different behavior. Follow the [operation-specific retry rules](https://docs.reilabs.org/docs/neuroadapt/operational-behavior-and-retries.md#retry-rules-by-operation); the presence of a `request_id` or SHA guard alone does not establish a general idempotency guarantee.


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