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

# Promote a value candidate

> Request candidate adoption with model identity guards and a paired application canary, then inspect the promotion result and installed model identity.

Promote the candidate identified by `expected_model_sha256`. Include the expected incumbent identity when adopting after a paired comparison. [Value promotion](https://docs.reilabs.org/docs/neuroadapt/value-promotion.md) explains the observed confidence gate, HTTP 409 rejection, and the difference between fitting, checkpoint selection, and installation.

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: `ValuePromoteRequest`.

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

| Field | Required | Type | Declared default | Constraints |
| - | - | - | - | - |
| `canary` | No | [ValueCanary](#valuecanary) or `null` | Not declared | No further constraint declared |
| `expected_current_model_sha256` | No | `string` or `null` | Not declared | 64 characters exactly |
| `expected_model_sha256` | Yes | `string` | Not declared | 64 characters exactly |
| `session_id` | Yes | `string` | Not declared | At least 1 character |

## ValueCanary

Schema: `ValueCanary`.

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

| Field | Required | Type | Declared default | Constraints |
| - | - | - | - | - |
| `cases` | Yes | array of [CanaryCase](#canarycase) | Not declared | 2 to 10000 items |
| `minimum_cases` | No | `integer` | `16` | Minimum `2`; Maximum `10000` |
| `required_improvement` | No | `number` | `0` | Minimum `0`; Maximum `1` |

## CanaryCase

Schema: `CanaryCase`.

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

| Field | Required | Type | Declared default | Constraints |
| - | - | - | - | - |
| `candidate_utility` | Yes | `number` | Not declared | Minimum `0`; Maximum `1` |
| `case_id` | Yes | `string` | Not declared | 1 to 256 characters |
| `incumbent_utility` | Yes | `number` | Not declared | Minimum `0`; Maximum `1` |

## Responses

| HTTP status | Archived contract |
| - | - |
| 200 | Successful JSON response. The archived schema does not type its properties. |
| 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.

Observed promotion can return HTTP `409` when the application canary does not demonstrate sufficient improvement. Preserve its reason and check the installed identity; see [promotion decisions](https://docs.reilabs.org/docs/neuroadapt/value-promotion.md).


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