Skip to content
    OpafraDocs

    API

    A REST API under /api, authenticated with a bearer token. Start runs, read results, and manage inventory from CI or a script.

    View as MarkdownOpen in ClaudeOpen in ChatGPT

    Everything the interface does is an API call. The common reasons to use it directly are starting a run from CI, pulling run results into another system, and registering hosts from whatever already knows about them.

    All endpoints are under /api.

    Authentication#

    Create a token in Settings, then API tokens. Send it as a bearer token:

    curl -H "Authorization: Bearer opf_..." \
  https://your-opafra-host/api/plans

    Tokens start with opf_ and are shown once, at creation. Only a hash is stored, so Opafra cannot show you the token again, and a lost token is replaced rather than recovered.

    A token can carry an expiry, and can be revoked at any time. The interface shows its prefix and when it was last used, which is enough to identify one without exposing it.

    Token creation and revocation are both recorded in the audit log.

    Starting a run#

    start a run
    curl -X POST https://your-opafra-host/api/executions \
  -H "Authorization: Bearer opf_..." \
  -H "Content-Type: application/json" \
  -d '{
    "planId": "…",
    "execution_mode": "dry_run",
    "variables": { "app_version": "1.4.2" }
  }'

    execution_mode is one of auto, semi_assisted, interactive or dry_run. The response carries the execution id.

    Reading a run#

    curl -H "Authorization: Bearer opf_..." \
  https://your-opafra-host/api/executions/{id}

    Returns the status, per-step and per-host results, and the approval record. Poll it, or listen to the live stream where you want output as it happens.

    GET /api/executions lists runs, and supports filtering for the usual questions: this plan, this environment, this status.

    The main resources#

    PathHolds
    /api/plansPlans and their steps
    /api/executionsRuns, live and historical
    /api/inventory/serversRegistered hosts
    /api/environmentsEnvironments, their variables and grants
    /api/ssh-keysManaged SSH keys
    /api/templatesConfig templates
    /api/scriptsScripts a plan can run
    /api/git-sourcesSynced repositories
    /api/collectionsPlan folders
    /api/audit-logsThe audit trail, Admin only

    Rules that apply everywhere#

    Tenancy. Every response is scoped to the token owner's tenant. Something you may not see returns 404, not 403, so an id cannot be probed.

    Roles. The same role requirements as the interface. Most write endpoints need Operator; membership, grants and the audit log need Admin.

    Unknown fields are rejected. The request body is validated strictly, and an unrecognised field is a 400 rather than being ignored. A typo fails loudly instead of silently doing the wrong thing.

    Secrets are never returned. No endpoint returns a private key, a password, or a resolved secret value. A generated SSH private key appears in exactly one response, when it is created.

    Using it from CI#

    The typical shape is: start a run in dry_run, read the result, and start a real run only if the preview is what you expected.

    Remember the gate. If the target environment requires approval, the real run will pause and your job should treat PAUSED as a normal outcome rather than a timeout, or target an environment that does not require approval.

    Next steps#