Skip to content
Vizzly Docs

Agents and the Vizzly API

An agent can use the Vizzly CLI to inspect the same visual test results your team sees. For cloud data, start by asking the CLI which API operations are available.

Find and call an operation

Terminal window
vizzly api schema --json
vizzly api schema sdk.listBuilds --json
vizzly api /api/sdk/builds \
  --header 'Vizzly-API-Version: 2026-09-12' --json

The first command lists supported operations. The second shows the request and response details for one operation. Use the method, API version header, parameters, and body from that schema when you make a request. Pass the version header with --header; the CLI does not add it automatically.

To inspect a build, screenshot, comparison, or review action, find the matching operation in the schema and follow its request shape. The schema is the current reference for what the API accepts.

Build context returns comparison IDs. Use getComparisonContext to read a comparison’s review details, then sdk.getComparisonImage to download its current screenshot, baseline, or diff:

Terminal window
vizzly api /api/sdk/context/comparisons/cmp456/images/diff \
  --header 'Vizzly-API-Version: 2026-09-12' \
  --output diff.png

The schema lists current, baseline, and diff as the supported image kinds. Use the version header shown in the operation details. Replace cmp456 with the comparison ID from build evidence. These examples use 2026-09-12.

Read local TDD results

Local TDD results live in .vizzly. Read them without cloud authentication:

Terminal window
vizzly context build current --source local --json

For build, screenshot, comparison, and review-queue context, the CLI also has dedicated vizzly context commands. Use --json when a script needs structured output.

Keep review decisions with your team

Agents can inspect visual changes and explain what they find. Review actions can change a build’s state. Check the operation’s method and request details, and run a write operation only when the task calls for that change.

Authentication

Schema discovery does not need a token. Cloud API requests use your Vizzly login or a project token in VIZZLY_TOKEN, depending on the operation.

For interactive use:

Terminal window
vizzly login

For unattended jobs, set VIZZLY_TOKEN in the environment.

About the old compact output

The --agent options for context build and context comparison are deprecated in v0.37.x and will be removed in v0.38.0. Use vizzly api schema for cloud requests. For local TDD results, use vizzly context ... --json.

Next steps