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.
const url = 'https://example.com/datanotes/settings/update/';const options = { method: 'POST', headers: { 'X-Datanotes-Actor': '{"harness":"my-script","model":"","session":"s-1"}', Authorization: 'Bearer <token>', 'Content-Type': 'application/json' }, body: '{"expect_version":"example","changes":{"additionalProperty":"example"},"dry_run":false}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://example.com/datanotes/settings/update/ \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --header 'X-Datanotes-Actor: {"harness":"my-script","model":"","session":"s-1"}' \ --data '{ "expect_version": "example", "changes": { "additionalProperty": "example" }, "dry_run": false }'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.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Header Parameters
Section titled “Header Parameters”JSON: on whose behalf the write is made, recorded in the journal (harness, model, session).
Example
{"harness":"my-script","model":"","session":"s-1"}Request Bodyrequired
Section titled “Request Bodyrequired”object
The settings_version that /settings/ answered.
Setting name -> new value; null puts the default back.
object
Check only: nothing saved, journaled or logged.
Responses
Section titled “Responses”Done.
object
The new version (unchanged on a dry run or when nothing changed).
The settings whose value changes, in settings order.
Of changed: the ones that apply at once.
Of changed: the ones that apply at the next start.
Every setting waiting for a restart after this change.
What to do next.
object
The journal entry (absent on a dry run or when nothing changed).
Every key of the settings file, in its order.
One key of the engine’s settings file, with its rule. Secrets are never sent: the owner token has no value, header values and the credentials inside an address are hidden.
object
The settings file’s key (camelCase).
The kind of value it takes.
The value saved now. Absent when write_only; telemetryHeaders shows each header’s value as <redacted>; an address shows no user or password.
The value when the file does not set it. Absent for httpServerToken.
The value differs from the default (httpServerToken: it is set).
The allowed values in words, read after “
The allowed values of an enum.
The smallest value of an integer or number, when it has one.
The largest value of an integer or number, when it has one.
live: a change applies from the next request or background job; restart: at the engine’s next start.
False for the settings that change only in the settings file (tableKey, transactionLogFormat).
When not editable: why, and how to change it.
A restart setting whose saved value is not the one the engine runs with.
A start option of datanotes serve that wins over the setting, in words.
Its value is never sent (httpServerToken).
Something was hidden: header values, the credentials of an address, the token.
An address the engine sends data to.
What a change of it does, to show before it is saved.
Example
{ "ok": true, "settings": [ { "type": "boolean", "applies": "live", "write_only": true, "redacted": true, "sends_data": true } ]}A bad body, or values refused: nothing changed. refused lists every refused setting.
object
object
Example generated
{ "error": "example", "refused": [ { "setting": "example", "error": "example", "hint": "example" } ]}Missing or wrong bearer token.
object
What went wrong, for a person or an agent.
Example generated
{ "error": "example"}A named token beyond its permissions (the engine’s administration, tables outside its write patterns, schema changes without ddl).
object
What went wrong, for a person or an agent.
Example generated
{ "error": "example"}The settings changed since you read them (expect_version), or the settings file was edited on disk while the engine runs: nothing changed.
object
What went wrong, for a person or an agent.
Example generated
{ "error": "example"}Unexpected error.
object
What went wrong, for a person or an agent.
Example generated
{ "error": "example"}The settings could not be saved or journaled: nothing changed.
object
What went wrong, for a person or an agent.
Example generated
{ "error": "example"}