Skip to content
OriginChats

config_update

Change one or more server settings. The server merges your changes into config.json, checks the result, and saves it. Use it from an admin panel instead of editing the file by hand.

Request

Section titled “Request”
{
  "cmd": "config_update",
  "updates": {
    "server": {
      "name": "My community"
    },
    "limits": {
      "post_content": 4000
    }
  }
}
Field Type Required Description
updates object Yes The settings to change, shaped like config.json. Must have at least one key.

How the merge works:

  • Nested objects merge key by key, so keys you leave out keep their saved values.
  • Arrays and other values replace the saved value entirely. To add one blocked word, send the whole blocked_words list.
  • null is saved as null.

The server validates the merged configuration before saving. For example, server.name, server.owner.name, and server.url must stay non-empty, and websocket.port must be between 1 and 65535. See configuration for every setting.

Response

Section titled “Response”
{
  "cmd": "config_update",
  "config": {
    "server": {
      "name": "My community",
      "owner": { "name": "alice" },
      "url": "https://chat.example.com"
    },
    "limits": {
      "post_content": 4000,
      "search_results": 30,
      "max_reactions_per_message": 20,
      "max_members": 0
    }
  }
}

The example is trimmed. config is the full saved configuration, masked the same way as config_get. Nobody else receives a broadcast. The change takes effect at once, and the audit log records the top-level keys you changed, not their values.

Credentials

Section titled “Credentials”

Only the owner can change credentials. A credential is any key named secret_access_key, access_key_id, password, token, secret, validator, or password_hash. Even the owner can change only these ones:

  • attachments.s3.access_key_id
  • attachments.s3.secret_access_key
  • Any credential nested under plugins
{
  "cmd": "config_update",
  "updates": {
    "attachments": {
      "s3": {
        "secret_access_key": "new-secret-value"
      }
    }
  }
}

Send only the keys you’re replacing. If an S3 key is "" or "***", the server drops it and keeps the saved value, so you can send back a form that still shows masked values. Plugin credentials don’t get this treatment: "***" under plugins is saved as the literal text ***.

Permissions

Section titled “Permissions”

Requires manage_config. On top of that:

  • Only the owner can change the top-level DB, websocket, auth_mode, or cracked settings.
  • Only the owner can change credentials, as described above.
  • Nobody can change hosted or any path listed in hosted.locked_paths. Hosting providers use these to lock settings.

It is blocked while you are timed out.

Errors

Section titled “Errors”
val When
updates: Expected length at least 1 updates is an empty object. Other validation messages cover a missing or non-object updates.
Only the owner can change credentials A non-owner sent a credential key.
Cannot modify protected credential: <path> The owner sent a credential other than the S3 keys or a plugin credential.
These settings are managed by your hosting plan: <paths> The update touches hosted or a locked path.
Only the owner can modify: <keys> A non-owner changed DB, websocket, auth_mode, or cracked.
Config value '<path>' must be a non-empty string server.name, server.owner.name, or server.url would be empty.
Config value 'server.url' must be a complete http:// or https:// URL server.url isn’t a full HTTP(S) URL.
Config value 'websocket.host' must be a non-empty string websocket.host would be empty.
Config value 'websocket.port' must be a port number between 1 and 65535 websocket.port is out of range or not a whole number.
Invalid notifications config: <detail> A notifications setting has the wrong type or value.
Invalid automod config: <detail> An automod setting has the wrong type or value.
Invalid attachment compression config: <detail> An attachments.compression setting is out of range.
Invalid authentication config: <detail> auth_mode isn’t rotur, cracked, or cracked-only, or cracked.allow_registration isn’t a boolean.
Failed to write config to disk The server couldn’t save config.json. Nothing changed.

Automod rules can fail with their own messages, such as Unable to read automod blocked_words_file or Invalid automod blocked_words entry <n>. See automod.

See also

Section titled “See also”