HTTP API

Every endpoint the server exposes. The API is served under the /v1 base path. The web UI at /ui/, along with /healthz, /readyz, /metrics, /.well-known/loomseal.json, the OpenID Connect and SAML sign-in routes, the webhook /hooks path, and the /relay worker path, is unversioned. The root redirects to the UI.

/.well-known/loomseal.json is deliberately public and unauthenticated: it publishes this install's signing key and identifiers so a relying party can pin the key from a channel independent of any bundle it is handed.

Licensed endpoints

Almost every endpoint below runs on Community, which needs no license. Three answer 403 without one, with a message naming the feature rather than failing in some subtler way:

Two more are enforced somewhere other than the request:

• /relay is served whatever the license. The gate is on the other end: switchtender worker --server refuses to start without Team, and so does a worker sharing the database: every worker process is gated.
• The directory sign-in routes need Pro, enforced at startup rather than per request. Configuring any of OIDC, SAML, LDAP, or JWT without a license refuses the server at startup, so those routes are either licensed or absent.

A streamed export whose status line has already been sent cannot report a later failure with a status code. The run event NDJSON download and the run log download therefore end with a {"export_incomplete":true,"reason":"..."} line when they stop early, so a short file is never mistaken for a whole one.

When the chain itself refuses a bundle

GET /v1/audit/bundle recomputes the whole chain and holds it against every anchor recorded over it before any window is applied. A chain this server checked and rejected is a finding, not a fault, so it answers 409 rather than 500, and a caller can tell the two apart without reading prose. A 500 is left to a real fault here, such as a store that will not read, and a limit that is not a count stays a 400.

{
  "error":  "entry 3 does not recompute (sequence 3)",
  "reason": "chain_break",
  "broke_at": 3,
  "broke_seq": 3,
  "count": 9
}

The coordinates are the same ones GET /v1/audit/verify reports, so the two answers agree. A windowed request is refused for a break anywhere in the chain, not only inside the window: a bundle signed over a window sitting past a break would attest to entries this install cannot stand behind.

Opening a live stream

EventSource cannot set a header, so GET /v1/runs/{id}/stream takes a short-lived ticket in the query string instead of a bearer token. Mint one over the ordinary authenticated route and open the stream with it:

curl -X POST -H "Authorization: Bearer $ST_TOKEN" \
  localhost:8080/v1/runs/run_abc/stream-ticket
# {"ticket":"...","expires_in":30}

A ticket opens that one run, works once, and expires in thirty seconds. The reason is that a URL is not private: a reverse proxy logs the full request line by default, so a session token in the query string reaches every access log downstream. A ticket in the same place is worth almost nothing.

An install running open, with no tokens, needs no ticket and the plain path works.

Account profiles

An account carries an optional profile alongside its role: full_name, email, phone, title, links, and notes. All of them are optional, so an account created by the CLI or provisioned over single sign-on stays valid with none of them set. title is descriptive and grants nothing; role alone decides what an account may do.

curl -X PUT https://switchtender.example.com/v1/users/user_9f2c \
  -H "Authorization: Bearer $ST_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "username": "ada",
    "role": "operator",
    "full_name": "Ada Lovelace",
    "email": "ada@example.com",
    "phone": "+1 555 0100",
    "title": "Platform Engineer",
    "links": ["https://wiki.example.com/people/ada"],
    "notes": "review each quarter"
  }'

The profile is replaced wholesale on update, so send the profile you want to end up with rather than only the parts that changed. An omitted field clears.

A profile is personal data and is treated as such. Only an admin may read it. /v1/users requires the admin role and is not delegable by a manage grant. The values are never written to the logs, and a rejection names the offending field without echoing it. Each single-line field is capped at 320 characters, notes at 2000, and an account may carry at most eight links. A link must be an http or https address; any other scheme is refused, because the admin page renders links as anchors.

Template run timeout

A template may cap how long its launches are allowed to execute with timeout, a whole number of seconds. It is accepted on create and update, and every launch of the template carries it onto the run, whether the launch came from the API, a schedule, or a webhook trigger.

curl -X POST https://switchtender.example.com/v1/templates \
  -H "Authorization: Bearer $ST_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "nightly database backup",
    "playbook": "plays/backup.yml",
    "timeout": 5400
  }'

Zero, or the field omitted, leaves launches on the server default set by --run-timeout, so a template saved before this field existed is unchanged. A run that exceeds its timeout is canceled and finalized as failed. A launch cannot raise the cap; the template's value is what applies.

Naming what a run targets

Two fields name a target and they are not interchangeable.

inventory_id names a stored inventory, the kind the UI creates and the one almost every caller wants. inventory is a path to an inventory file already on the server, for a run whose inventory is managed outside this product.

Sending a stored inventory's name in inventory is read as a path. Ansible exits zero when a host pattern matches nothing, so a run aimed at a path that does not exist is recorded as succeeded having touched no host at all.

Ansible run controls

A run submission and a template both accept the Ansible controls that used to require a hand-built command. They ride onto a run the same way from the API, a schedule, or a webhook trigger, and a retry keeps them.

curl -X POST https://switchtender.example.com/v1/runs \
  -H "Authorization: Bearer $ST_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "playbook": "plays/deploy.yml",
    "inventory_id": "inv_3f9c1b7a2e04",
    "limit": "canary01",
    "tags": ["web", "config"],
    "skip_tags": ["reboot"],
    "forks": 25,
    "verbosity": 2,
    "diff_mode": true
  }'

These apply to the Ansible tool. The other tools ignore them, so a Bash or Terraform template that carries one is unaffected.

A run submission also accepts extra_vars, an object of variables injected into the run. Ansible receives them the way --extra-vars supplies them, and a plugin tool reads them as its input. A template carries its own extra_vars and a launch may merge more over them.

Saved workflows

A template may carry steps, a pipeline graph, instead of a single tool. Such a template is a saved workflow: every path that fires a template, a launch, a schedule, or a webhook trigger, runs the graph as a pipeline, and the template's survey answers and extra vars reach every step. A workflow template sets no top-level playbook, command, tool, shards, or Ansible controls, since each step names its own; the graph is validated when the template is saved, so a cycle or an unknown dependency is refused then rather than on every launch.

curl -X POST https://switchtender.example.com/v1/templates   -H "Authorization: Bearer $ST_TOKEN"   -H 'Content-Type: application/json'   -d '{
    "name": "build and ship",
    "inventory_id": "inv_3f9c1b7a2e04",
    "steps": [
      {"name": "build", "tool": "bash", "command": "make release"},
      {"name": "deploy", "playbook": "deploy.yml", "depends_on": ["build"]}
    ]
  }'

List responses

Every list response is an envelope: the rows under a name, count for how many were returned, and total for how many exist. They agree on any ordinary install.

The run list pages, because run history grows without bound: limit (default 200, maximum 1000) and offset, with has_more and next_offset to continue. The configuration lists, users, tokens, templates, schedules, triggers and organizations, return at most 1000 rows in one response. Past that, total exceeds count and the response is the first 1000. An install with more configuration than that should read it through the object endpoints rather than the list.

Survey field constraints

A template survey field accepts bounds beyond its type, checked at launch before any answer becomes an extra var. A field also takes an optional help string shown beneath its prompt, and a multiline type for a block of text such as a set of variables or a note.

A launch that violates a constraint is refused with the field it failed, and no run is submitted.

The shape itself, which strict decoding refuses to guess at:

{
  "survey": [
    {"var": "release", "label": "Release tag", "type": "text",
     "required": true, "pattern": "^v[0-9]+\\.[0-9]+\\.[0-9]+$",
     "help": "The tag to deploy, such as v2.1.0"},
    {"var": "batch", "label": "Hosts per batch", "type": "int",
     "default": 5, "min": 1, "max": 50},
    {"var": "environment", "label": "Environment", "type": "choice",
     "required": true, "choices": ["staging", "production"]},
    {"var": "notes", "label": "Change notes", "type": "multiline",
     "max_length": 2000}
  ]
}

type is one of text, multiline, int, choice, or bool. var names the extra var the answer becomes, and it is the only field besides type that every entry must carry. An unknown key is refused rather than ignored, so a survey that almost parses is reported instead of silently losing a field.

Per-template notifications

A template or a run submission may carry notifications, a list of targets that receive its terminal state in addition to the server-wide channels. Each target names a kind and the field that kind is addressed by, plus an optional on_failure that limits the target to failed runs.

curl -X POST https://switchtender.example.com/v1/templates \
  -H "Authorization: Bearer $ST_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "prod deploy",
    "playbook": "plays/deploy.yml",
    "notifications": [
      {"kind": "slack", "url": "https://hooks.slack.com/services/T0/B1/x"},
      {"kind": "pagerduty", "key": "R0UTINGKEY", "on_failure": true},
      {"kind": "email", "to": "oncall@example.com, lead@example.com"}
    ]
  }'

A malformed target is refused at create or update with the field it lacks, not dropped at delivery. A Twilio or email target names only a recipient. The account credentials stay in server flags, so a template never carries them. On read, webhook URLs, PagerDuty routing keys, and Grafana tokens come back masked; an edit that echoes the mask back keeps the stored value.

Schedule timezone

A schedule reads its cron expression in the server's local time unless it carries a timezone, an IANA name such as America/New_York or Europe/Berlin. With one set, 0 2 * * * fires at 02:00 in that zone and follows its daylight-saving shifts, so a nightly window stays put across the year. The field is accepted on create and update and applies to the same expression the preview endpoint renders.

curl -X POST https://switchtender.example.com/v1/schedules \
  -H "Authorization: Bearer $ST_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"cron":"0 2 * * *","timezone":"America/New_York","template_id":"tpl_abc123"}'

Fleet view windows

/v1/fleet and /v1/tasks take a window, the number of recent runs per host or per task the view considers, and /v1/hosts/{host}/runs takes a limit. All three default to 10. The window is capped at 100 and the host history limit at 500; a larger value is answered with the cap, and the response echoes the window it actually used. The caps exist because the per-host and per-task summaries are kept when their runs are deleted, so on a long-lived fleet the tables hold a row for every host of every run, and every row a window admits becomes an element of the answer.

The same tables are bounded by count rather than by age. --retain-history keeps the newest N summaries for each host and each task and drops the rest, so a host's outcome history still outlives its runs without the tables growing forever. N is never allowed below 500, the deepest window these endpoints will answer, so trimmed history is history no request could have reached.

curl -s "https://switchtender.example.com/v1/fleet?window=30" \
  -H "Authorization: Bearer $ST_TOKEN"

Relay endpoints

With --worker-token set, the server also serves the mesh relay under /relay: the execution path an outbound worker started with --server uses instead of a database connection. Every call presents the worker bearer token.

Each report call is bounded twice. It presents the per-claim capability the claim response issued, so it can only write to the run this worker holds, and one call carries at most a few thousand items, so a worker cannot force an unbounded decode on the control node; the worker sends a wide run's evidence in several calls rather than losing it to that cap. Host facts are bounded further: a worker may write facts only for hosts its run has already reported results for, so nothing can be recorded about a machine no run claims to have touched.

What that does and does not give you: a worker authors its own results, so a worker you do not trust can still describe its own run untruthfully. What it cannot do is reach past that run into the recorded state of the rest of the fleet. Give a queue only to workers you would let touch the hosts that queue targets.