Skip to content
Vizzly Docs

API Schema and Requests

Use the API schema when you need a cloud request that does not have a dedicated CLI command. It shows which operations Vizzly supports and what each request needs.

List operations

Terminal window
vizzly api schema --json

To inspect one operation, pass its ID:

Terminal window
vizzly api schema sdk.listBuilds --json

The details include the endpoint, HTTP method, API version header, query parameters, request body, and response shape. Use those values when you call the API.

API requests need the Vizzly-API-Version header from the schema. The CLI does not add it for you. These examples use 2026-09-12, the current version shown by the schema.

Make a request

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

Use --query for query parameters, --header for headers, and --data for a JSON request body. The schema tells you which values an operation expects.

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

Save an image response

Build context returns comparison IDs. Use getComparisonContext for a comparison’s review details, then sdk.getComparisonImage to save its current screenshot, baseline, or diff. Pass the image kind as the last path segment. Replace cmp456 with the comparison ID from the build response:

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

Download the full API document

Use the full OpenAPI document when you need to inspect the complete API at once:

Terminal window
vizzly api schema --full --output openapi.json

Check before writing

The schema includes each operation’s HTTP method. Read operations leave Vizzly unchanged. Write operations can change review state or add comments, so use them when the task calls for that change.

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 the API schema for cloud requests. Local TDD results remain available through vizzly context ... --json.