Skip to content
Open Garphield

Garphield automation API

Use the Automation API to drive the live workbench through its command registry. You can also use the embed driver for a more integrated approach to adding Garphield to your app.

This page covers direct access to the live workbench. Core concepts explains graph data and project state.

Three routes build, style and share Garphield documents without a mounted workbench:

  • The hosted MCP connector at https://mcp.garphield.com/mcp, for chat assistants. Documents are stored for 30 days after their last change.
  • npx -y garphield-mcp, a local stdio MCP server and CLI, for coding agents and scripts. Documents are .gph files on disk.
  • The Python package, for notebooks and scripts.

Connection steps for each route are in Garphield for agents. The two MCP routes can also lay a graph out and render a PNG. The Python package validates a complete project and creates a URL without network I/O:

import garphield as gph
project = gph.Project.load("network.gph")
url = gph.share_url(project)

share_url() returns a URL carrying the complete project in a compressed #p= carrier. It uses zlib/DEFLATE plus unpadded base64url and accepts at most 262,144 encoded characters. Opening the link runs Garphield’s normal layout when the project has no saved positions; link generation itself does not run a layout or renderer. garphield-mcp share writes the same carrier. For a small graph-only payload, use the documented data: URL plus format path.

Surface Capability boundary
HTTP-only agents Read documentation, LLM files, the command schema, and fetch graph files by URL.
Hosted MCP connector Create, inspect, style, lay out, validate, share and export stored documents, including PNG through a server-side browser. Links point at the stored document.
garphield-mcp The same tools on local .gph files, with self-contained #p= links. PNG export drives a local Chrome.
Python Validate, convert, fingerprint, save .gph projects, and perform project-link encoding without mounting a view. No layout.
Mounted browser renderer window.garphield, WebMCP, embeds, and notebook widgets provide analysis, layout, audit, rendering, and PNG export.
Playwright Automates the mounted renderer in a headless browser; it is not browser-free.

A project above the inline limit can be shared through the hosted connector’s stored link or as a .gph file.

Every route lists the fields, algorithms and channels a binding can use:

Route Call
Hosted connector, garphield-mcp, WebMCP garphield_inspect with the document’s doc ("current" in the workbench)
An open workbench window.garphield.fields() (see below)
Python project.sources()

The MCP tools and window.garphield resolve a bare field name against the channel’s target, so edgeWidth with amount_bn binds efield:amount_bn. garphield_style, channel.bind and apply() check every binding with the same rules and refuse one that cannot be drawn; Python raises BindingError. The binding grammar has the rules.

The live automation surfaces in this section all require a mounted browser renderer. Browser-free Python workflows operate on project documents; they do not provide window.garphield or WebMCP.

window.garphield is the stable, canonical automation API for same-frame JavaScript: use it from the browser console, extensions, and Playwright tests that can run code in the workbench frame. The remaining sections document that API.

Compatible browser agents can instead discover page-defined garphield_* tools through the browser-native WebMCP bridge. This is an experimental, progressive enhancement based on the WebMCP W3C Community Group Draft: Garphield feature-detects it, so browsers and agent harnesses without WebMCP continue to use window.garphield unchanged. It is not the third-party webmcp.dev widget and it adds no Garphield UI.

Five of the tools are the shared definitions the hosted connector and garphield-mcp also register, with the same names, inputs and error codes. They take a document reference, doc. The workbench holds one document, the graph that is loaded now, and its reference is always "current". A write through these tools loads the result the same way File > Open does. garphield_create and garphield_layout are not registered here: load a graph with garphield_run and file.load, and the workbench lays it out.

WebMCP tool Operation
garphield_inspect List the fields, algorithms and channels a binding can name, with the view config.
garphield_style Bind fields or algorithms to channels and set the layout mode or theme; strict and atomic.
garphield_validate Check the loaded project, or a .gph document you pass, the way the app loads it.
garphield_share Get a link and an embed snippet: a short #s= view link for a built-in sample or generator, a self-contained #p= link for anything else.
garphield_export Export .gph, node-link JSON, GEXF, GraphML, GML, or a PNG of the drawing.

The remaining tools work on the live session:

WebMCP tool Equivalent operation
garphield_schema List registered commands.
garphield_run Run a command with { id, params? }.
garphield_get_state Read the serializable view state.
garphield_apply Apply a state document or compressed payload; returns { ok, problems }.
garphield_view Inspect the current drawing and projection.
garphield_audit Read accessibility findings.
garphield_quality Read layout-quality findings.

Every tool returns an MCP tool result: a short text summary in content and the data in structuredContent, with isError: true and structured errors when a call fails. Agents should call garphield_schema before garphield_run and use garphield_get_state or garphield_view to inspect the result. WebMCP exposes request/response operations only; for subscriptions and other same-frame capabilities, use window.garphield.

The tool set loads only in browsers that expose WebMCP. garphield_inspect, garphield_style, garphield_validate and garphield_share are new. garphield_get_share_url is gone; use garphield_share. garphield_export now takes { "doc": "current", "format": ... } instead of a bare format, and adds gph and png.

Run the production workbench with Playwright

Section titled “Run the production workbench with Playwright”

Playwright is a headless-browser surface, not a browser-free surface. This script opens the production Garphield workbench, waits for its mounted API, loads a supported sample, awaits the requested layout, frames final coordinates, and reads the resulting state:

import { chromium } from "playwright";
const browser = await chromium.launch({ headless: true });
try {
const page = await browser.newPage();
await page.goto("https://garphield.com/", {
waitUntil: "domcontentloaded",
});
await page.waitForFunction(
() => typeof window.garphield?.run === "function",
undefined,
{ timeout: 30_000 },
);
await page.evaluate(async () => {
await Promise.resolve(
window.garphield.run("sample.load", { id: "petersen" }),
);
});
await page.waitForFunction(
() => window.garphield?.getState?.().dataset?.id === "petersen",
undefined,
{ timeout: 30_000 },
);
await page.evaluate(async () => {
const layout = await Promise.resolve(
window.garphield.run("layout.set", { mode: "force" }),
);
if (layout && !layout.ok) {
throw new Error(layout.error?.message ?? "Layout mode failed");
}
const settled = await Promise.resolve(
window.garphield.run("layout.wait"),
);
if (settled && !settled.ok) {
throw new Error(settled.error?.message ?? "Layout did not settle");
}
});
const id = await page.evaluate(async () => {
const nodeLink = JSON.parse(window.garphield.export("nodeLink"));
const id = nodeLink.nodes?.[0]?.id;
if (typeof id !== "string") throw new Error("The graph has no node ID");
const selected = await Promise.resolve(
window.garphield.run("selection.select", { id }),
);
if (selected && !selected.ok) {
throw new Error(selected.error?.message ?? "Selection failed");
}
return id;
});
await page.evaluate(async (id) => {
const framed = await Promise.resolve(
window.garphield.run("camera.frame", {
nodeIds: [id],
durationMs: 0,
}),
);
if (!framed?.ok) {
throw new Error(framed?.error?.message ?? "Frame failed");
}
const audit = window.garphield.audit();
const quality = window.garphield.quality();
if (!audit.ok) {
throw new Error("Unsafe view");
}
if (quality.verdict !== "good") {
console.warn("View needs review", quality);
if (quality.verdict === "poor") throw new Error("Unsafe view");
}
}, id);
const state = await page.evaluate(() => window.garphield.getState());
console.log({ dataset: state.dataset.id, layout: state.layout, node: id });
} finally {
await browser.close();
}

layout.set reserves the next layout epoch before the renderer effect runs, so an immediately following layout.wait (without an epoch parameter) waits for that request rather than a previous settlement. The same correlation is used after a successful graph file.load and after apply() when it changes the graph or layout. An explicit layout.wait({ epoch }) remains supported.

schema() returns the live command catalogue. Run the ids it returns: Every call may be synchronous or asynchronous, so callers should use await Promise.resolve(run(...)). Read the declared result delivery marker: "envelope" results use the typed { ok, value } or { ok: false, error } shape, while "raw" results are consumed directly. Void commands may return undefined (or null on JSON transports). Unknown ids and invalid parameters can throw synchronously; raw-command transport failures may reject the promise or surface as an outer transport error rather than an envelope.

await Promise.resolve(window.garphield.run("sample.load", { id: "petersen" }));
await Promise.resolve(window.garphield.run("layout.set", { mode: "levels" }));
await Promise.resolve(window.garphield.run("layout.wait"));
await Promise.resolve(window.garphield.run("selection.select", { id: "3" }));
await Promise.resolve(window.garphield.run("camera.frame", { nodeIds: ["3"] }));
await Promise.resolve(window.garphield.run("selection.path", { source: "3", target: "8" }));
await Promise.resolve(window.garphield.run("view.fisheye", {
enabled: true,
magnification: 4,
radiusScale: 0.45,
}));

selection.path respects directed links and returns the exact shortest-path node and edge ids. It returns a validation error when no directed route exists. view.fisheye gives agents parity with the lens controls: it enables or disables the lens and sets its magnification and viewport-relative radius. Pointer focus remains transient; a Playwright driver can move it with a primary click (with a short transition), drag the inner grab ring past its breakaway threshold to release a pinned lens, primary-drag its outer boundary to resize it, or right-drag inside it to change magnification. Escape also releases a pinned lens. Wheel and touchpad gestures continue to zoom the camera, even inside the lens.

The registry groups commands by the job they perform:

Family Examples
Data Load a sample, load a URL, generate a graph.
Layout and view Switch layout, relax around a selection, set graph detail, frame the camera, or configure the fisheye.
Channels and filters Browse sources, bind or unbind a channel, add a filter, add or clear a transformation.
Selection Select, find a directed path, grow, shrink, invert, or clear a selection.
History Pin a state, jump to a point, describe the tree, or diff two points.
Narrative Save a set, capture a scene, play a storyboard, or copy a storyboard link.

Use schema() as the source of truth for current ids and parameter descriptions. The command palette and embed capability grants use the same registry. The Python widget reaches the renderer through its typed bridge.

file.load accepts http:, https:, and data: URLs, plus a blob: URL created in the same browser context. Only cross-origin HTTP(S) sources need CORS. Prefer HTTPS for hosted files because the production HTTPS site normally cannot fetch an HTTP URL. The optional authoritative format is dot, gexf, graphml, gml, nodeLink, compactJson, csv, edgeList, matrixMarket, graph6, sparse6, digraph6, or gph. Garphield otherwise uses the URL suffix and defaults an unknown or absent suffix to JSON content sniffing. MIME type does not select the parser. Compact JSON uses node-array positions as IDs; the graph6 family carries topology only and therefore receives numeric labels. Build a data: URI first and then percent-encode the entire URI as the file query value. See the inline-loading recipes.

A .gph project loaded with file.load (format: "gph" or a .gph URL) restores its saved session exactly as File > Open does: positions, style, bindings, theme, layout mode, filters, history, and the storyboard. Other formats carry only the graph.

file.load is asynchronous and returns the typed FileLoadResultV1 descriptor inside the normal CommandResult envelope. Await it before reading state and branch on both transport failure and flat-table construction:

const result = await Promise.resolve(
window.garphield.run("file.load", { url, format: "gexf" }),
);
if (!result?.ok) throw new Error(result?.error?.message ?? "Load failed");
if (result.value.status === "construction-required") {
throw new Error("This table needs an explicit graph construction recipe");
}
const settled = await Promise.resolve(
window.garphield.run("layout.wait"),
);
if (!settled?.ok) throw new Error(settled?.error?.message ?? "Layout did not settle");

For contrast, artifact.describe is declared with delivery: "raw" and resolves directly to an ArtifactFormatV1[]; consume that array without an ok branch. artifact.create and artifact.download likewise return raw typed objects. Use each command’s generated result descriptor to decide which branching rule applies instead of inferring it from kind or the command id.

status: "loaded" means the graph store has been replaced; it does not mean layout has settled. The replacement reserves the layout epoch, so call layout.wait immediately after the load to await that exact layout before selecting or framing coordinates. Fetch, network, and CORS acquisition failures return LOAD_FAILED with retryable: true. After bytes/string acquisition, decode, parse, schema, and format failures return LOAD_FAILED with retryable: false; the message and URL details are preserved. A request superseded by newer graph activity returns STALE_STATE with retryable: true and no obsolete toast.

fields() returns what channel.bind, filter.add and the bindings in a state document can refer to on the loaded graph:

const { fields, algorithms, channels } = window.garphield.fields();

Each entry in fields has the id to bind (field:<name> for node attributes, efield:<name> for edge attributes), the attribute name, its target (node or edge), its type (num or cat), and the count of items with no value (missing). Numeric fields add min and max; categorical fields add distinct and up to three of the most frequent examples; date fields add temporal: true. A reserved attribute name appears with its escaped id and its original name. algorithms lists each algorithm’s id, target, result type and params with their defaults and ranges. channels lists each channel’s id, target and the result types it accepts. A source fits a channel when the targets match and the source’s type is in accepts.

await Promise.resolve(
window.garphield.run("channel.bind", {
channel: "edgeWidth",
kind: "field",
source: "amount_bn",
}),
);

channel.bind resolves a bare field name to the field on the channel’s target, so the call above binds efield:amount_bn. It throws when the binding cannot be drawn, with a message that suggests the ids to retry with.

const next = structuredClone(window.garphield.getState());
next.layout = "levels";
next.style = {
...(next.style ?? {}),
nodeSurface: "sphere",
};
const applied = window.garphield.apply(next);
if (!applied) throw new Error("StateDoc was rejected");
const settled = await Promise.resolve(
window.garphield.run("layout.wait"),
);
if (!settled?.ok) throw new Error(settled?.error?.message ?? "Layout did not settle");
const nodeLink = JSON.parse(window.garphield.export("nodeLink"));
const id = nodeLink.nodes?.[0]?.id;
if (typeof id !== "string") throw new Error("The graph has no node ID");
const framed = await Promise.resolve(
window.garphield.run("camera.frame", { nodeIds: [id], durationMs: 0 }),
);
if (!framed?.ok) throw new Error(framed?.error?.message ?? "Frame failed");

getState() returns the serializable view document with the current camera. apply() accepts a complete state object or compressed share payload and returns whether validation and dispatch succeeded. A true result acknowledges the request; it does not report completion of asynchronous generator loading. For a generator workflow, await generator.create, confirm through getState() that the requested dataset was adopted, then await layout.wait. A newer edit or dataset request can supersede a generator while its module loads.

For changes dispatched synchronously, apply() reserves a layout epoch when it changes the graph or layout; await layout.wait immediately after dispatch, then select or frame final coordinates. Set style.nodeSurface to "flat", "lumen", "sphere", "prism", or "sketchy"; the value is also retained by generated view-state URLs. The optional top-level nodeSurfaceStyle field remains accepted as a compatibility alias for older state documents.

Validate complete StateDocs against the published StateDoc JSON Schema. apply() takes a complete document, never a patch: a document with only { style: { nodeSize: 1.5 } } is rejected. Clone getState() and edit it; camera may be null but not omitted. A rejection is deterministic for a given document and is reported two ways: apply() logs one path: message line per problem with console.warn, and window.garphield.validateState(doc) returns the same lines without changing or logging anything (an empty array means apply() would accept). Await file.load before apply(), because apply() supersedes any in-flight dataset request.

apply() checks bindings with the same rules as channel.bind and refuses the whole document when any binding fails. A binding fails when its channel is unknown, its field is not on the graph it will draw, its algorithm or set is unknown, its node or edge target does not match the channel, the channel does not accept its result type, or a param is undeclared or out of range. Edge fields need "target": "edge" in their source. Only new or changed bindings are checked: one that matches a binding already live (same channel, source and result type) is left as the app has it, so apply(getState()) always applies, even after loading another graph left a field binding pointing at a field that graph does not have. Each problem line names the binding and suggests the closest ids to use instead:

bindings.0.source.id: Channel "edgeWidth" takes an edge source; "field:amount_bn" is a node field. Did you mean "efield:amount_bn"?

If the document loads a different sample or generator, field bindings are checked only for a field: or efield: id that matches the channel’s target, because the new graph is not built yet. Share links, pins and storyboards opened in the app keep loading when a binding no longer fits: the app skips that binding and logs it with console.warn. false means invalid and inert: the existing state does not change, and a StateDoc’s file reference does not carry or replace file graph bytes. apply() also strips positions; full positions and session restoration belong to .gph project loading. true means validation and dispatch succeeded, not that an asynchronous sample layout has settled. Use layout.wait when settled geometry is required. A successful graph file.load uses the same immediate wait contract.

The canonical layout modes are force, levels, and geo. quality remains only a legacy input normalized to force when decoding older documents; new commands and documents should use the canonical names.

The document’s style block contains node surface, node size, node gap, link width, link opacity, curvature, and the fisheye’s enabled state, magnification, and radius scale. Theme, labels, link direction, and link gradient remain top-level for backward compatibility. The same complete style is carried by share URLs, history pins, .gph projects, apply(), and observe() updates; fisheye pointer focus is deliberately transient.

Subscribe to state changes:

const stop = window.garphield.observe((state) => {
console.log(state.selection, state.camera);
});
// Later
stop();

view() separates the saved project from the current Full or Backbone presentation:

const view = window.garphield.view();
console.log(view.detail); // "full" or "overview"
console.log(view.profile); // graph complexity
console.log(view.rendered); // nodes and edges on canvas
console.log(view.hiddenEdges); // shown and omitted edge counts

Switch the presentation with the matching command:

window.garphield.run("view.detail", { mode: "overview" });

getState() describes the project. view.inspect describes the screen: what a person exploring alongside an agent can actually see after zooming, panning, hovering, and selecting.

const seen = window.garphield.run("view.inspect", { limit: 50 });
console.log(seen.nodes.visible); // drawn nodes on screen
console.log(seen.nodes.ids); // largest on screen first, at most `limit`
console.log(seen.labels); // [{ id, label }] currently painted
console.log(seen.hovered); // node under the pointer, or null
console.log(seen.selection); // { count, visible }
console.log(seen.graphBounds); // graph-space box of the visible region

limit defaults to 100 and caps at 5,000; nodes.truncated says whether more visible nodes exist. edges.touchingView counts drawn edges with an endpoint on screen. The command is read-only and needs a rendered graph. It is not in the default embed capabilities; an embedding host grants it like any other command.

Camera moves and hover do not fire observe(), which follows the state doc. Take a fresh snapshot when the user asks you to look, or poll while you work together.

Graph node IDs come from the node-link export’s nodes[].id values. They are data identifiers used by selection and camera commands:

const nodeLink = JSON.parse(window.garphield.export("nodeLink"));
const graphNodeId = nodeLink.nodes[0].id;
await Promise.resolve(
window.garphield.run("camera.frame", { nodeIds: [graphNodeId] }),
);

History IDs are provenance-operation IDs returned by history.tree(). They are not graph node IDs and are the values expected by history.jump and history.diff:

const tree = await Promise.resolve(window.garphield.run("history.tree"));
const historyId = tree.nodes[0].id;
await Promise.resolve(
window.garphield.run("history.jump", { nodeId: historyId }),
);
const graphml = window.garphield.export("graphml");
const audit = window.garphield.audit();
const quality = window.garphield.quality();
const share = window.garphield.getShareString();
const shareUrl = window.garphield.getShareUrl();
const story = window.garphield.getStoryboardShareString();

Supported export values are gph, gexf, graphml, gml, and nodeLink.

export("gph") returns the whole project as .gph JSON text: the graph with its current positions, view configuration, bindings, filters, history, pins, and storyboard. It is the document File > Save writes, without the file picker. Use artifact.create instead when you need a provenance manifest with the project.

const project = JSON.parse(window.garphield.export("gph"));

Gate an automated result on both reports, surfacing every non-good quality verdict:

const audit = window.garphield.audit();
const quality = window.garphield.quality();
if (!audit.ok) throw new Error("Unsafe view");
if (quality.verdict !== "good") {
console.warn("View needs review", quality);
if (quality.verdict === "poor") throw new Error("Unsafe view");
}

audit.ok is false only when a critical automated accessibility heuristic fails; manual checks remain findings. quality().verdict is good, warn, poor, info, or na. Reject poor, surface warn for judgment, and treat na as ungraded rather than passed. Quality is not a certification.

Method Returns
schema() Serializable command descriptors
fields() Fields, algorithms and channels a binding can name
run(id, params?) A registered command result
getState() Current view state
apply(doc) Whether state, including its bindings, validated and applied
validateState(doc) Problems that would make apply(doc) refuse it; [] if none
view() Current Full or Backbone projection
export(format) Serialized graph text, or the whole project for "gph"
audit() Accessibility findings
quality() Layout-quality report
getShareString() Compressed view payload
getShareUrl() Full share URL for the current view
getStoryboardShareString() Compressed story payload
observe(callback) Unsubscribe function

window.garphield exists while the workbench is mounted. Look it up again after navigation rather than keeping a handle to an unmounted page.