POST /macros/{id}/run

Details #

Queues a run and returns at once. The run itself happens in the engine; read it with GET /runs/{id}. The id must be the macro's id, not its name.

Over loopback every request needs Authorization: Bearer <token>. See GET /macros for where the token lives and how to use the socket instead.

The body is optional JSON. All keys are optional.

{ "inputs": { "key": "DAY-412" }, "dryRun": true, "byAgent": "my-script" }

curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -d '{"inputs":{"key":"DAY-412"},"dryRun":true}' \
  http://127.0.0.1:48080/macros/m_4f2a9c/run

{ "runId": "r_91c0d2" }

The status is 202 Accepted.

When byAgent is set and the Mac can't do the run now (it is locked, an app the macro needs isn't running), the run is held and the answer says so: {"runId": "h_3f9a1c", "held": "true", "reason": "Mac locked", "blocker": "locked"}. The runId is the held run's, which starts by itself later; see GET /held. A macro set to skip answers {"skipped": "true", …} with an empty runId.

Parameters #

curl --unix-socket "$SWITCHBOARD_HOME/engine.sock" -X POST http://localhost/macros/{id}/run

Start a run of a macro. The Unix socket needs no token; loopback 127.0.0.1:48080 needs Authorization: Bearer <api-token>.

Gotchas #

• 404 with no macro <id> when the id does not exist.

• 400 with body must be JSON {inputs, dryRun} when the body is not valid JSON of that shape.

• A disabled macro still runs this way; only triggers respect enabled.

• A macro whose inputs are missing fails the run, not the request. Poll the run to see why.

See also #

• GET /runs/{id}

• switchboard run