foreman_openbolt exposes a Foreman API under /api/v2/openbolt for external
consumers like scripts, Hammer CLI, and CI jobs.
The full per-endpoint reference is auto-generated by apipie and served at
/apidoc on any Foreman install with the plugin loaded.
This file is the short version: what the surface looks like, how to authenticate, a curl example, and a few things that are not obvious from the per-endpoint reference.
All endpoints use the standard Foreman API authentication (HTTP Basic Auth or
session, depending on your Foreman setup). The caller's Foreman user must
have :execute_openbolt (granted by the "OpenBolt Executor" role shipped
with the plugin) plus the built-in :view_smart_proxies permission for any
endpoint that takes a smart proxy (the proxy-scoped tasks endpoints and
POST /launch/task, which takes smart_proxy_id in the request body). The
job-query endpoints (/jobs, /jobs/:job_id/status,
/jobs/:job_id/result) only need :execute_openbolt.
| Method | Path | Purpose |
|---|---|---|
| GET | /api/v2/openbolt/smart_proxies/:smart_proxy_id/tasks |
List the Bolt tasks available on a smart proxy |
| POST | /api/v2/openbolt/smart_proxies/:smart_proxy_id/tasks/reload |
Reload the proxy's Bolt task cache |
| GET | /api/v2/openbolt/smart_proxies/:smart_proxy_id/tasks/options |
Get OpenBolt options metadata for a smart proxy |
| POST | /api/v2/openbolt/launch/task |
Launch a Bolt task on a smart proxy |
| GET | /api/v2/openbolt/jobs |
List recorded jobs, paginated |
| GET | /api/v2/openbolt/jobs/:job_id/status |
Get the status of a launched job |
| GET | /api/v2/openbolt/jobs/:job_id/result |
Get the full result of a completed job |
The :job_id for the /jobs/:job_id/* endpoints is the proxy-issued job ID
returned by /launch/task.
All job-related responses include a kind discriminator:
{ "kind": "task", ... }Today only "task" is supported. When plan-execution support is added, plan
launches will return kind: "plan" from the same endpoints. New consumers
should switch on kind so they don't break when plans land.
# Launch
curl -sk -u admin:changeme \
-H 'Accept: application/json' -H 'Content-Type: application/json' \
-X POST https://foreman.example.com/api/v2/openbolt/launch/task \
-d '{
"smart_proxy_id": 1,
"task_name": "service",
"targets": "host1.example.com,host2.example.com",
"parameters": { "action": "status", "name": "puppet" },
"options": { "transport": "ssh", "private-key": "/usr/share/foreman-proxy/.ssh/id_rsa-foreman", "host-key-check": false }
}'
# => {"job_id": "abc123...", "kind": "task"}
# Poll status (until status is "success", "failure", "exception", or "invalid")
curl -sk -u admin:changeme \
https://foreman.example.com/api/v2/openbolt/jobs/abc123.../status
# Fetch full result once complete
curl -sk -u admin:changeme \
https://foreman.example.com/api/v2/openbolt/jobs/abc123.../resultExample result of a successful run:
{
"kind": "task",
"status": "success",
"command": "bolt task run service --targets host1.example.com,host2.example.com --no-save-rerun --concurrency=100 --connect-timeout=30 --project /etc/puppetlabs/code/environments/production --format json --no-color --transport=ssh --private-key=/usr/share/foreman-proxy/.ssh/id_rsa-foreman --no-host-key-check action=status name=puppet",
"value": {
"items": [
{
"value": {
"status": "MainPID=789,LoadState=loaded,ActiveState=active",
"enabled": "enabled"
},
"action": "task",
"object": "service",
"status": "success",
"target": "host1.example.com"
},
{
"value": {
"status": "MainPID=806,LoadState=loaded,ActiveState=active",
"enabled": "enabled"
},
"action": "task",
"object": "service",
"status": "success",
"target": "host2.example.com"
}
],
"elapsed_time": 1,
"target_count": 2
},
"log": ""
}A failed run keeps the same envelope, with per-target errors under
value.items[].value._error. This example is from a run over the Choria
transport, with the command and log truncated:
{
"kind": "task",
"status": "failure",
"command": "bolt task run facts --targets host1.example.com,host2.example.com --no-save-rerun ... --transport=choria ...",
"value": {
"items": [
{
"value": {
"_error": {
"msg": "No agent information available for host1.example.com (node did not respond to discovery)",
"kind": "bolt/choria-agent-not-available",
"details": {}
}
},
"action": "task",
"object": null,
"status": "failure",
"target": "host1.example.com"
},
{
"value": {
"_error": {
"msg": "No agent information available for host2.example.com (node did not respond to discovery)",
"kind": "bolt/choria-agent-not-available",
"details": {}
}
},
"action": "task",
"object": null,
"status": "failure",
"target": "host2.example.com"
}
],
"elapsed_time": 30,
"target_count": 2
},
"log": "Started with 100 max thread(s)\n..."
}The value field is the OpenBolt CLI's JSON output passed through
unmodified. Its exact layout depends on the OpenBolt version, the
transport, and the job kind, and is not a stable part of this API. The
per-target items layout shown above is what task runs produce, and plan
results may differ.
GET /api/v2/openbolt/jobs returns the standard Foreman pagination envelope,
minus subtotal. The endpoint has no search filtering, so it would always
equal total.
{
"total": 142,
"page": 1,
"per_page": 20,
"results": [ ... ]
}total is the overall job count.
Accepts page and per_page query params. per_page is clamped to [1, 100],
with the special value all returning every recorded job in a single page.
page values below 1, or non-numeric, are treated as 1.
To use the saved encrypted Foreman default for an option (for example,
password), send the literal string [Use saved encrypted default] as the
option's value. Omitting the key entirely sends nothing for that option and
lets the proxy apply its own default. Sending the placeholder for an option
that has no saved Foreman default returns 400.
OpenBolt scrubs values you pass under options if they correspond to a
Foreman setting marked encrypted (today: password, sudo-password).
Values you pass under parameters are not scrubbed and are stored
verbatim in the recorded job. They show up in the parameters field on the
/jobs and /jobs/:job_id/status responses, and embedded in the proxy-
rendered command string on /jobs/:job_id/result. Any user with
:execute_openbolt can read them. The smart proxy also logs parameters at
INFO level, and its recent log lines are visible in Foreman on the Smart
Proxy page's Logs pane to any user with :view_smart_proxies.
Sensitive task parameter scrubbing will land in a later update.