# Change the engine's settings (owner only): checked with the rules the engine loads the settings file with, saved, and journaled as set_engine_settings.

`POST /datanotes/settings/update/` (operation `update_engine_settings`)

`expect_version` is the `settings_version` you read: another change since is refused (409). `changes` maps each setting to its new value; null puts its default back (not `httpServerToken`); `telemetryHeaders` is a patch merged into the current headers (a header set to null is removed). Secrets are write-only: send a new value, never read one; an address sent back as shown (without its credentials) keeps them. All or nothing: one refused value refuses the change, and `refused` lists each. A `live` setting applies from the next request or job, a `restart` one at the next start. `dry_run: true` checks without saving. A named token is refused (403), even with `maintain`.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `X-Datanotes-Actor` | header | `string` | no | JSON: on whose behalf the write is made, recorded in the journal (`harness`, `model`, `session`). |

## Request body

`application/json`, required

| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `expect_version` | `string` | yes |  | The `settings_version` that `/settings/` answered. |
| `changes` | `object` | yes |  | Setting name -> new value; null puts the default back. |
| `dry_run` | `boolean` | no | `false` | Check only: nothing saved, journaled or logged. |

## Responses

| Status | Description | Body |
| --- | --- | --- |
| 200 | Done. | `object` (application/json) |
| 400 | A bad body, or values refused: nothing changed. `refused` lists every refused setting. | `object` (application/json) |
| 401 | Missing or wrong bearer token. | `Error` (application/json) |
| 403 | A named token beyond its permissions (the engine's administration, tables outside its `write` patterns, schema changes without `ddl`). | `Error` (application/json) |
| 409 | The settings changed since you read them (expect_version), or the settings file was edited on disk while the engine runs: nothing changed. | `Error` (application/json) |
| 500 | Unexpected error. | `Error` (application/json) |
| 503 | The settings could not be saved or journaled: nothing changed. | `Error` (application/json) |

The schemas named here are in [openapi.json](https://datanotes.dev/openapi.json) (`components.schemas`).