Skip to content

API: Settings

This section covers server and plugin settings management via the API.

Info

Writing settings requires the MANAGE_USERS authority.

Get All Settings

Retrieve the current values of all server and plugin settings.

1
2
GET /api/v1/settings HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

Response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{
  "server": {
    "some.setting.key": {
      "key": "some.setting.key",
      "name": "Some Setting",
      "description": "Human-readable description.",
      "type": "TEXT",
      "editAllowed": true,
      "editDisallowedReason": null,
      "defaultValue": "default",
      "currentValue": "current",
      "options": []
    }
  },
  "plugin": {
    "shelldot.some.plugin": {
      "plugin.setting.key": {
        "key": "plugin.setting.key",
        "name": "Plugin Setting",
        "description": null,
        "type": "INTEGER",
        "editAllowed": false,
        "editDisallowedReason": "Requires restart",
        "defaultValue": 0,
        "currentValue": 5,
        "options": []
      }
    }
  }
}

The response has two top-level maps:

  • server — map of key → setting for server-level settings.
  • plugin — map of pluginId → (key → setting) for plugin-specific settings.

Each setting object contains:

Field Type Description
key string Unique setting identifier
name string Human-readable name
description string | null Optional description
type string Setting type: TEXT, INTEGER, DECIMAL, BOOLEAN, DATETIME, ENUM, MULTI_ENUM
editAllowed boolean Whether the value can currently be changed
editDisallowedReason string | null Reason editing is blocked, if applicable
defaultValue any Default value as JSON
currentValue any Current active value as JSON
options array For enum types — list of { name, description, value, disabled, disabledReason }

Get a Single Setting

Retrieve one setting by its key.

1
2
GET /api/v1/setting/{KEY} HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

Response: same structure as a single entry from GET /api/v1/settings.

Update Multiple Settings

Update server and/or plugin settings in a single request. Only the keys you include are changed.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
PATCH /api/v1/settings HTTP/1.1
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

{
  "server": {
    "some.setting.key": "new-value"
  },
  "plugin": {
    "shelldot.some.plugin": {
      "plugin.setting.key": 42
    }
  }
}

Set a key's value to null to reset it to its default.

Response: the full updated settings object (same shape as GET /api/v1/settings).

Update a Single Setting

Update one setting by its key.

1
2
3
4
5
6
7
PUT /api/v1/setting/{KEY} HTTP/1.1
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

{
  "value": "new-value"
}

Set value to null to reset to the default.

Response: the updated single setting object.