Browse the docs

GET /macros

Returns every macro in the Library as a JSON array of macro files.

Details #

The engine serves its API in two places.

  • The Unix socket engine.sock, in Switchboard's support folder (~/Library/Application Support/Switchboard/). Only your user can open it, so it needs no token. The switchboard command and the MCP server use it.

  • Loopback HTTP at 127.0.0.1:48080. Any program on your Mac can reach this port, so every request needs the header Authorization: Bearer <token>. A request without it, or with a wrong token, gets 401 and {"error":"unauthorized"}.

The token is the 64 characters in the file api-token in the same support folder. The engine creates the file the first time it starts, readable only by you. If port 48080 is taken, the engine runs on the socket alone and GET /state reports the HTTP listener as busy.

Every response is JSON. Errors look like {"error":"..."}. Dates are ISO 8601.

TOKEN=$(cat ~/Library/Application\ Support/Switchboard/api-token)
curl -s -H "Authorization: Bearer $TOKEN" http://127.0.0.1:48080/macros

The same call over the socket:

curl -s --unix-socket ~/Library/Application\ Support/Switchboard/engine.sock http://localhost/macros
[
  {
    "id": "m_4f2a9c",
    "name": "Paste ticket as title",
    "group": "g_work",
    "enabled": true,
    "icon": "bolt",
    "inputs": [{ "name": "key", "type": "string", "prompt": "Ticket key" }],
    "when": [{ "type": "hotkey", "params": { "keys": "t", "modifiers": ["cmd", "shift"] } }],
    "onlyIf": [],
    "do": [{ "id": "s1", "type": "hud", "params": { "text": "{{key}}" } }],
    "run": { "timeout": 60, "concurrent": "queue", "retry": 0 },
    "agent": { "exposed": false, "approve": "never", "destructive": false },
    "origin": { "kind": "you" },
    "version": 3,
    "created": "2026-10-01T08:00:00Z",
    "modified": "2026-10-20T17:42:10Z"
  }
]

Parameters #

curl --unix-socket "$SWITCHBOARD_HOME/engine.sock" -X GET http://localhost/macros

List the macros in the library. The Unix socket needs no token; loopback 127.0.0.1:48080 needs Authorization: Bearer <api-token>.

Examples #

curl -s -H "Authorization: Bearer $TOKEN" http://127.0.0.1:48080/macros | jq -r '.[].name'

Gotchas #

  • When SWITCHBOARD_HOME is set, the socket and token are in that folder instead.

  • Paths with a trailing segment that no route knows answer 404 with no route GET /....

See also #