Workflows-API-Referenz

Workflows sind die wiederholbare Hälfte von Browserberg: Blöcke, veröffentlicht als unveränderliche Versionen, ausgeführt in einer Session, die du stellst. Die Autorisierung ist das Bearer-Schema des restlichen v1-Umfangs — ein API-Schlüssel nach dem Wort Bearer —, ohne Ausnahme unter diesen Endpunkten.

POST /v1/workflows

Veröffentlicht eine Workflow-Definition und antwortet mit 201 und der neuen Version.

Publish-Body

Name	Typ	Beschreibung
`workflowId`	string	Veröffentlicht eine neue Version eines bestehenden Workflows; ohne Angabe wird einer erstellt.
`title` erforderlich	string	Bis zu 200 Zeichen.
`parameters`	array	Deklarierte Eingaben: `{key, description?, required?, default?}`, wobei `key` ein gültiger Bezeichner ist.
`blocks` erforderlich	array	1 bis 100 Blöcke; ein Block ohne `nextBlockLabel` fällt zum nächsten in Deklarationsreihenfolge durch.
`runSequentially`	boolean	Serialisiert Läufe dieses Workflows.
`sequentialKey`	string	Begrenzt diese Serialisierung auf einen Schlüssel deiner Wahl.
`finallyBlockLabel`	string	Ein Block, der auf jedem Pfad zuletzt läuft — außer nach einem Abbruch.

Validierung, Labels, Versionen

Die Validierung meldet alles auf einmal: Ein abgelehntes Publish trägt details.errors als Array von {code, at, message}-Einträgen, eine Runde behebt also alles. Labels müssen gültige Bezeichner sein — Open_portal, keine Phrase mit Leerzeichen —, denn ein Label wird zur Variablen, über die spätere Blöcke die Ausgabe dieses Blocks referenzieren. Und jedes angenommene Publish ist eine neue unveränderliche Version: Bereits gestartete Läufe führen weiter die Version aus, mit der sie gestempelt wurden.

GET /v1/workflows

Listet deine Workflows in ihren aktuellen Versionen auf.

GET /v1/workflows/:id

Liefert einen Workflow; mit dem Query-Parameter `version` liest du eine ältere unveränderliche Version.

POST /v1/workflows/:id/runs

Startet einen Lauf in einer bestehenden Session und antwortet mit 202.

Run-Body

Name	Typ	Beschreibung
`sessionId` erforderlich	string	Die Session, in der der Lauf ausgeführt wird — Läufe erzeugen nie eine eigene.
`inputs`	object	Werte für die deklarierten Parameter.
`version`	integer	Heftet den Lauf an eine bestimmte Version; Standard ist die aktuelle.

GET /v1/workflow-runs/:id

Liefert den Lauf mit seinen Ergebnissen je Block.

GET /v1/workflow-runs

Läufe der ganzen Organisation, neueste zuerst. `workflowId`, `status` (`running`, `completed`, `failed`, `canceled`) und `limit` (Standard 50, höchstens 200) filtern.

Lauf- und Block-Felder

Name	Typ	Beschreibung
`status`	string	`running`, dann `completed`, `failed` oder `canceled`.
`endedBy`	string	Das `endedBy` des Blocks, der den Lauf beendet hat (`gave_up`, `not_offered`, `budget` … eines Agenten-Blocks), oder `canceled`. Fehlt, wenn der Lauf einfach abgeschlossen wurde: Ein Workflow ohne Agenten-Block wurde von niemandem geprüft. Blöcke tragen ihr eigenes `endedBy` ebenfalls.
`blocks`	array	Ein BlockRun je ausgeführtem Block: `label`, `blockType`, `status` (`completed`, `failed`, `skipped`, `canceled`), `output`, `error`, `attempts` und — in Schleifen — `iteration`.
`outputs`	object	Die gesammelten Ausgaben des Laufs, nach Label.

DELETE /v1/workflow-runs/:id

Bricht den Lauf ab — ein Abbruch wird nie von `continueOnFailure` eines Blocks geschluckt.

GET /v1/workflows/:id/health

Meldet Drift-Score und Episoden des Workflows; Wiederholungen vervielfachen eine Episode nie.

GET /v1/heal-proposals

Listet Heilungsvorschläge, filterbar über die Query-Parameter `workflowId` und `status`.

POST /v1/heal-proposals/:id/adopt

Übernimmt einen Vorschlag als neue Version; er trägt `baseVersion` und einen Inhalts-Hash, und nur eine geschlossene Liste von Feldern auf einer geschlossenen Liste von Blocktypen kann je vorgeschlagen werden — nie ein `code`-Block.

POST /v1/heal-proposals/:id/reject

Verwirft einen Vorschlag; veröffentlichst du selbst eine neue Version, werden offene Vorschläge ohnehin als veraltet markiert.

Veröffentlichen, ausführen, pollen

Veröffentliche einen Workflow aus zwei Blöcken, führe ihn in einer frischen Session aus und polle bis zum Endzustand.

Voraussetzungen: api-key inference

BASE="https://browserberg.com"
AUTH="Authorization: Bearer $BROWSERBERG_API_KEY"
JSON="Content-Type: application/json"

# Publish. Every publish is a new immutable version; labels must be valid
# identifiers because they become template variables.
WFID=$(curl -s -X POST "$BASE/v1/workflows" -H "$AUTH" -H "$JSON" -d '{
  "title": "Read the example heading",
  "blocks": [
    { "blockType": "navigation", "label": "Open_page", "url": "https://example.com" },
    { "blockType": "extraction", "label": "Read_heading",
      "instruction": "the page heading",
      "schema": { "type": "object", "properties": { "heading": { "type": "string" } } } }
  ]
}' | python3 -c 'import json,sys; print(json.load(sys.stdin)["workflow"]["workflowId"])')

SID=$(curl -s -X POST "$BASE/v1/sessions" -H "$AUTH" -H "$JSON" -d '{"ttlSeconds": 300}' \
  | python3 -c 'import json,sys; print(json.load(sys.stdin)["session"]["id"])')

RUNID=$(curl -s -X POST "$BASE/v1/workflows/$WFID/runs" -H "$AUTH" -H "$JSON" \
  -d "{\"sessionId\": \"$SID\"}" \
  | python3 -c 'import json,sys; print(json.load(sys.stdin)["run"]["runId"])')

# Poll until terminal.
for i in $(seq 1 90); do
  STATUS=$(curl -s "$BASE/v1/workflow-runs/$RUNID" -H "$AUTH" \
    | python3 -c 'import json,sys; print(json.load(sys.stdin)["run"]["status"])')
  if [ "$STATUS" != "running" ]; then break; fi
  sleep 2
done

echo "run: $STATUS"
curl -s "$BASE/v1/workflow-runs/$RUNID" -H "$AUTH" \
  | python3 -c 'import json,sys; print(json.dumps(json.load(sys.stdin)["run"]["outputs"], indent=2))'

curl -s -X DELETE "$BASE/v1/sessions/$SID" -H "$AUTH" > /dev/null