Settings & quiet hours

These endpoints read and change Herald's own settings: the general and voice settings as one validated table, and the quiet-hours schedule. Use them to configure Herald from a script, or to build a tool that shows its state. The examples use the $HERALD and $TOKEN variables from Connect.

How settings are organised#

Herald has three kinds of settings, and each has its own endpoints.

The general settings are a flat list of keys. Each key has a type and a range. The reply to a read includes a schema that describes every key, and options that list the allowed choices on this Mac, such as the installed sounds, the connected displays and the available voices. A program can build a settings screen from those two parts without knowing the keys in advance.

Settings > General. Each control here maps to a key of the settings table.

Endpoints#

The global stacking level also has its own short route, /v1/settings/stacking, documented with the Stacks API.

General and voice settings#

Setting keys#

These are the keys of the settings table. A read returns their current values and a write changes them.

What the voice keys do is explained in the voice reference.

GET /v1/settings#

Returns the current value of every key, the schema that describes the keys, and the choices available on this Mac.

Request

No parameters.

curl -s "$HERALD/v1/settings" -H "Authorization: Bearer $TOKEN"

Example response

The schema and options lists are shortened here to one or two entries each.

{
  "settings": {
    "port": 48617,
    "launchAtLogin": true,
    "muteAllSounds": false,
    "stacking": "bySender",
    "historyCapPerApp": 1000,
    "tooltipLevel": "nameAndDescription",
    "voiceEngine": "kokoro",
    "voiceDefault": "af_heart",
    "voiceSpeed": 1,
    "voiceLang": "en-us",
    "voiceSystem": null
  },
  "schema": [
    {
      "key": "port",
      "group": "General",
      "type": "integer",
      "min": 1024,
      "max": 65535,
      "restartsServer": true,
      "description": "The local API port (General > Local API). Changing it restarts the server; the new port is written to the port file."
    },
    {
      "key": "stacking",
      "group": "General",
      "type": "choice",
      "values": ["byApp", "byIssuer", "bySender", "never"],
      "description": "How banners stack by default: byApp, byIssuer, bySender or never. An app can override it."
    }
  ],
  "options": {
    "sounds": ["none", "Basso", "Blow", "Glass"],
    "displays": [{"id": "main", "name": "Main display"}, {"id": "3", "name": "Studio Display"}],
    "corners": ["topRight", "topLeft", "bottomRight", "bottomLeft"],
    "stackingLevels": ["byApp", "byIssuer", "bySender", "never"],
    "voiceEngines": ["kokoro", "system", "off"],
    "voices": [{"id": "af_heart", "name": "af_heart"}, {"id": "bm_george", "name": "bm_george"}],
    "historyCapChoices": [100, 250, 500, 1000, 2500, 5000]
  }
}

Response fields

Each schema entry:

The options object:

PUT /v1/settings#

Changes one or more settings. Send an object with only the keys you want to change.

Request

curl -s -X PUT "$HERALD/v1/settings" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"muteAllSounds": true, "voiceSpeed": 1.15}'

Example response

The reply has the same three parts as GET /v1/settings, with the new values, plus applied. The schema and options parts are left out of this example.

{
  "applied": ["muteAllSounds", "voiceSpeed"],
  "settings": {
    "port": 48617,
    "launchAtLogin": true,
    "muteAllSounds": true,
    "stacking": "bySender",
    "historyCapPerApp": 1000,
    "tooltipLevel": "nameAndDescription",
    "voiceEngine": "kokoro",
    "voiceDefault": "af_heart",
    "voiceSpeed": 1.15,
    "voiceLang": "en-us",
    "voiceSystem": null
  }
}

Response fields

Errors

Notes

• All or nothing. If any key is invalid, nothing is changed. The message names the key, and for an unknown key it lists the known ones.
• When you change port, the reply still arrives on the old port. A moment later the server restarts on the new one and the port file holds the new number. Read the file again before your next request.

Quiet hours#

Quiet hours are times when Herald holds back speech, sounds or banners. There is a weekly schedule of windows, and an ad hoc silence that you can start at any moment for a fixed time. What a window is and what "silenced" means for each kind of output is explained in the quiet-hours reference, which also documents every field of the window object.

GET /v1/settings/quiet-hours#

Returns the schedule, the ad hoc silence if one is running, and what is silenced at this moment.

Request

No parameters.

curl -s "$HERALD/v1/settings/quiet-hours" -H "Authorization: Bearer $TOKEN"

{
  "windows": [
    {
      "id": "night",
      "days": [],
      "start": "22:30",
      "end": "07:30",
      "speech": true,
      "sounds": true,
      "banners": false,
      "speakSummary": false
    }
  ],
  "adHoc": {
    "until": "2026-10-02T14:00:00.000Z",
    "speech": true,
    "sounds": true,
    "banners": false
  },
  "status": {
    "active": true,
    "speech": true,
    "sounds": true,
    "banners": false,
    "until": "2026-10-02T14:00:00.000Z",
    "source": "adhoc"
  }
}

Response fields

PUT /v1/settings/quiet-hours#

Changes quiet hours. The body can do three things, alone or together: replace the schedule, end the current silence, and start an ad hoc silence.

Request

The adHoc object needs until or minutes:

Example request

Silence speech and sounds for one hour:

curl -s -X PUT "$HERALD/v1/settings/quiet-hours" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"adHoc": {"minutes": 60}}'

Example response

The reply has the same shape as GET /v1/settings/quiet-hours, after the change.

{
  "windows": [],
  "adHoc": {"until": "2026-10-02T14:00:00.000Z", "speech": true, "sounds": true, "banners": false},
  "status": {
    "active": true,
    "speech": true,
    "sounds": true,
    "banners": false,
    "until": "2026-10-02T14:00:00.000Z",
    "source": "adhoc"
  }
}

Errors

Notes

• The three parts are applied in this order: windows, then resume, then adHoc. A silence started by a request therefore wins over a resume in the same request.
• windows replaces the schedule. To add one window, read the schedule, add to the list, and send the whole list back.
• resume ends an ad hoc silence and the current occurrence of every active window. The next occurrence of each window still applies.

A weekday schedule, as a second example:

curl -s -X PUT "$HERALD/v1/settings/quiet-hours" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"windows": [{"days": ["mon", "tue", "wed", "thu", "fri"], "start": "22:30", "end": "07:30",
                    "speech": true, "sounds": true}]}'

Related#

• The Herald app: the Settings window, tab by tab.
• Quiet hours reference: windows, what is silenced, and urgent notifications.
• Voice reference: engines, voices and the voice keys.
• Apps API: settings that belong to one app.
• MCP tools for apps and settings: the same operations for an agent.