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.
No browser available?
Section titled “No browser available?”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.gphfiles 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.
Find the ids a binding can name
Section titled “Find the ids a binding can name”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.
Choose an automation surface
Section titled “Choose an automation surface”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.
Discover and run commands
Section titled “Discover and run commands”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.
Command families
Section titled “Command families”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.
List the ids a binding can name
Section titled “List the ids a binding can name”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.
Read and apply state
Section titled “Read and apply state”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);});
// Laterstop();Inspect the current drawing
Section titled “Inspect the current drawing”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 complexityconsole.log(view.rendered); // nodes and edges on canvasconsole.log(view.hiddenEdges); // shown and omitted edge countsSwitch the presentation with the matching command:
window.garphield.run("view.detail", { mode: "overview" });See what the user is looking at
Section titled “See what the user is looking at”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 screenconsole.log(seen.nodes.ids); // largest on screen first, at most `limit`console.log(seen.labels); // [{ id, label }] currently paintedconsole.log(seen.hovered); // node under the pointer, or nullconsole.log(seen.selection); // { count, visible }console.log(seen.graphBounds); // graph-space box of the visible regionlimit 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.
Node IDs and history IDs
Section titled “Node IDs and history IDs”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 }),);Export and inspect
Section titled “Export and inspect”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.
API summary
Section titled “API summary”| 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.