Editing click paths through the API

This article describes the endpoints through which your own scripts draft and try click paths and the steps of a multi-step sign-in. An AI assistant uses the same rules through the MCP server (Describing sign-in and click paths). The step language itself is described in Describing sign-in and click paths.

Token and rights

You need a token bound to the website that carries the right “Edit click paths”. How to create it is described in Describing sign-in and click paths. With this right the token gets two abilities: journeys:read for reading and checking, journeys:write for saving drafts and starting test runs.

Every request carries the token as a header; the base address is https://barrierepruefung.de/api/v1:

Authorization: Bearer YOUR_TOKEN
Accept: application/json
Accept-Language: en

{site} in the paths is the “Site ID” from the “Embedding” tab. For any other website the API answers 404. Texts in responses follow Accept-Language (de or en). Writing calls optionally take actor_name: the name under which your system knows the acting person. It is recorded on the draft as evidence; the responsible person remains whoever granted the right.

Endpoints

The schema of the step language is available without a token at https://barrierepruefung.de/api/v1/schema/klickpfad.json and https://barrierepruefung.de/api/v1/schema/anmeldeablauf.json (JSON Schema 2020-12).

Approving and deleting are not available through the API. Neither are credentials: no user name, password or one-time code secret, no sign-in services and no confirmation for them are set or returned.

Checking steps

POST /sites/{site}/journeys/pruefen with steps and optionally stop_before saves nothing and always answers 200. An invalid path is the result here:

{
  "gueltig": false,
  "fehler": [
    {
      "code": "selektor_nicht_erlaubt",
      "schritt": 2,
      "feld": "selector",
      "text": "Schritt 2: Der Selektor enthält unerlaubte Zeichen. Erlaubt sind CSS-Selektoren, role=… und text=…."
    }
  ],
  "bereinigt": [
    {"action": "goto", "url": "/warenkorb"},
    {"action": "click", "selector": "xpath=//button"}
  ]
}

The sentence in text is currently German only; use code, schritt and feld to react.

Saving a draft

POST /sites/{site}/journeys creates a new click path with name, steps and optionally stop_before. It then has no running steps, only a draft. PUT /sites/{site}/journeys/{id}/entwurf sets the draft of an existing path; its name stays, and so do its running steps.

{
  "name": "Checkout",
  "steps": [
    {"action": "goto", "url": "/warenkorb"},
    {"action": "click", "selector": "role=button[name=\"Zur Kasse\"]"}
  ],
  "stop_before": "role=button[name=\"Zahlungspflichtig bestellen\"]",
  "actor_name": "Build script"
}

The response (201 on creation, otherwise 200) describes the path:

{
  "data": {
    "id": 42,
    "name": "Checkout",
    "status": "entwurf",
    "schritte": [],
    "stop_before": null,
    "entwurf": {
      "schritte": [
        {"action": "goto", "url": "/warenkorb"},
        {"action": "click", "selector": "role=button[name=\"Zur Kasse\"]"}
      ],
      "stop_before": "role=button[name=\"Zahlungspflichtig bestellen\"]",
      "von": {"weg": "api", "name": "Build script", "token_name": "Build"},
      "am": "2026-10-30T09:15:00+00:00"
    },
    "freigegeben": null,
    "letzter_lauf": {
      "status": "gescheitert",
      "am": "2026-10-30T03:12:44+00:00",
      "lauf_id": "01JBX0A2C4E6G8H1J3K5M7N9P0",
      "seitdem_geaendert": false,
      "grund": null,
      "befund": {
        "code": "element_versteckt",
        "schritt": 2,
        "schritte": 2,
        "aktion": "click",
        "selektor": "role=button[name=\"Zur Kasse\"]",
        "viewport": "mobile",
        "befund": {"treffer": 1, "sichtbar": 0},
        "ueberschrift": "Schritt 2 von 2 gescheitert (click, Mobil, 390 px)",
        "erklaerung": "Der Selektor trifft ein Element, es ist aber nicht sichtbar.",
        "hinweis": "Wählen Sie ein Element, das in dieser Breite sichtbar ist, …"
      }
    },
    "freigabe_url": "…/websites/…/pruefung"
  }
}

status is entwurf (draft), freigegeben (approved) or freigegeben_mit_entwurf (approved, with a draft). letzter_lauf is null as long as the path has not appeared in a completed scan. Otherwise it holds the state in the last scan: status is erfolgreich (succeeded), gescheitert (failed) or nicht_geprueft (not checked; this is not a failure of the path: sign-in, throttling, deadline, budget or proxy prevented the check, the reason is in grund), am and lauf_id name the scan, seitdem_geaendert is true if the path was approved after it. Only for gescheitert is befund set: code is one of the codes in Describing sign-in and click paths, schritt, schritte, aktion, selektor and viewport say where, befund holds the measured values (treffer, sichtbar, erster_sichtbar, erster_bedienbar, abgeloest, navigiert, adresse; not all of them for every code), and ueberschrift, erklaerung and hinweis are texts in the language of the request. Branch on code, not on the texts.

At freigabe_url a person approves the draft (Describing sign-in and click paths).

For a multi-step sign-in, PUT /sites/{site}/anmeldung/entwurf with schritte proposes the steps, with placeholders instead of credentials (Describing sign-in and click paths). This works only if a credential of that kind already exists in the “Testing” tab; otherwise the API answers 404, and for a simple sign-in form kein_ablauf.

Test runs

POST /sites/{site}/probelaeufe starts a test run and answers 202 straight away. It needs exactly one source:

• {"journey_id": 42, "quelle": "entwurf"} or "quelle": "freigegeben": a saved click path. If a credential is active, the test run signs in first, like a scan.
• {"anmeldung": "entwurf"}: only the draft of the sign-in.
• {"schritte": [...], "stop_before": "…"}: unsaved steps, without sign-in.

Poll the state with GET /sites/{site}/probelaeufe/{id} until status is no longer wartet or laeuft:

{
  "data": {
    "id": "01JBX3K7Q8M4V2N6P0R5S9T1W3",
    "status": "fertig",
    "quelle": "entwurf",
    "journey_id": 42,
    "mit_anmeldung": false,
    "erfolgreich": false,
    "grund": null,
    "schritte": [
      {"nr": 1, "viewport": "desktop", "action": "goto", "ok": true, "grund": null, "adresse": "https://www.example.org/warenkorb", "aria": "- main: …", "befund": null, "bild_url": "…"},
      {"nr": 2, "viewport": "desktop", "action": "click", "ok": false, "grund": "klick_abgelehnt:nicht_gefunden", "adresse": "https://www.example.org/warenkorb", "aria": "- main: …", "befund": {"code": "klick_abgelehnt:nicht_gefunden", "schritt": 2, "schritte": 2, "aktion": "click", "selektor": "role=button[name=\"Zur Kasse\"]", "viewport": "desktop", "befund": {"treffer": 0, "sichtbar": 0}, "ueberschrift": "…", "erklaerung": "…", "hinweis": "…"}, "bild_url": "…"}
    ],
    "anmeldung": null,
    "dauer_ms": 5120,
    "angelegt_am": "2026-10-30T09:16:00+00:00",
    "fertig_am": "2026-10-30T09:16:07+00:00",
    "loeschen_ab": "2026-10-31T09:16:00+00:00",
    "freigabe_hinweis": "Before this path runs in scans, a person has to approve it in the ‘Testing’ tab: …"
  }
}

• status: wartet (waiting), laeuft (running), fertig (done), gescheitert (the test run failed as a whole, reason in grund, for example start_fremder_host, a proxy error page proxy_fehler:…, budget_ueberschritten, abgelaufen or scanner_veraltet during an update) or abgelehnt (refused).
• erfolgreich: true only if the test run is done, no step failed and something actually succeeded (a step with ok: true or, for a sign-in-only test run, a successful sign-in); null while it runs. Branch on this, not on status: a fertig test run can still have failed at a step.
• A test run checks every width of the scan profile in turn and ends at the first failure. schritte holds one entry per step and width; viewport is desktop, mobile or reflow-320 (older results without it count as desktop). For a failed step befund has the same shape as in letzter_lauf, including selektor; otherwise it is null. The image belongs to step and width.
• Per step ok: true, false or null for “not executed”. The test run ends at the first failure. The reasons are the same as in a scan (Describing sign-in and click paths); stop_before means the path stopped before the stop target.
• bild_url is a signed address valid for 10 minutes. Query the test run again to get a new one.
• If a step lies outside your domain, adresse holds only its origin, and aria and bild_url are empty.
• After loeschen_ab the result and images are deleted.

The limits of test runs are described in Describing sign-in and click paths.

Errors

Errors come as application/problem+json with status, detail (a sentence in the language of the request) and, where there is one, a stable key reason. Branch on reason, not on the sentence.

The codes in fehler[].code form a closed list: