canonical: https://jentic.com/apis/percy.io/percy

# Percy API

Percy (by BrowserStack) is a visual testing and review platform that automates visual regression testing for web applications. The Percy API allows you to manage projects, builds, and snapshots programmatically, enabling integration with CI/CD pipelines, custom testing workflows, and monitoring dashboards. Percy captures screenshots across browsers and viewports, compares them against baselines, and highlights visual differences, making it essential for teams that need to catch visual bugs before production.

## For AI agents

Manage Percy visual testing projects, builds, and snapshots for automated visual regression testing.

## Scope

Provides access to percy.io resources and operations as documented in the OpenAPI specification.

## Capabilities

- Create and manage visual testing projects
- Trigger and monitor visual testing builds
- Review and approve snapshot comparisons
- Integrate visual testing into CI/CD pipelines
- Query build status and visual diff results
- Manage project settings and baseline images

## Use cases

### CI/CD Visual Testing Integration

Integrate Percy into CI/CD pipelines to automatically catch visual regressions on every pull request. The API enables custom build triggers, status checks, and approval workflows that fit your team's processes. Query build results and block deployments when visual changes are detected.

Example prompt: Use Percy API to trigger builds on PR creation, monitor build status, and query visual diffs to determine whether to approve or block the deployment.

### Visual Testing Dashboard

Build custom dashboards that aggregate Percy build results across multiple projects and teams. Use the API to query snapshot comparisons, track visual change trends, and report on testing coverage. Ideal for engineering managers and QA teams monitoring visual quality.

Example prompt: Query Percy projects and builds via the API to extract visual diff metrics, then display trends and alerts in a custom dashboard.

### AI Agent for Visual Testing

Let AI agents handle Percy visual testing tasks - triggering builds, checking results, and approving snapshots based on predefined criteria. Through Jentic, agents can discover Percy operations dynamically and integrate visual testing into their decision-making workflows.

Example prompt: Search Jentic for 'percy build status' to find the relevant endpoints, load their schemas, and execute to determine whether visual changes are acceptable.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/projects` | List all Percy projects |
| GET | `/builds/{id}` | Get build details and status |
| POST | `/builds` | Create a new visual testing build |

## Key resources

- **Projects** — Visual testing projects containing builds and snapshots
- **Builds** — Test runs with snapshot comparisons and visual diff results
- **Snapshots** — Individual screenshot captures with baseline comparisons

## Why Jentic

- **Setup:** Wiring Percy by hand means setting up its bearer token auth against percy.io and threading project slugs and build and snapshot ids through your calls yourself. Through Jentic you install once, import the Percy API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Percy puts the resource id in the URL path (`/projects/{project_slug}`, `/builds/{build_id}`, `/snapshots/{snapshot_id}`), so a rule can pin your agent to one project or build. You choose the operations it may call, so approve and reject actions on builds and snapshots are included only if you add them.
- **Credential handling:** Your Percy bearer token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'check the status of a visual test build', and Jentic returns the matching Percy operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## FAQ

### What authentication does the Percy API use?

The Percy API uses bearer authentication. Through Jentic, credentials are stored encrypted and injected at execution time so they never enter the agent's context.

### How many endpoints does the Percy API have?

The Percy API exposes 9 endpoints across its surface area.

### Can I limit what my agent is allowed to do with the Percy API?

Yes. Jentic One is self-hosted, so your own rules decide which Percy operations and credentials the agent may use. Because Percy puts the resource id in the URL path (`/projects/{project_slug}`, `/builds/{build_id}`, `/snapshots/{snapshot_id}`), you can pin the agent to a single project or build, and you choose exactly which operations it may call. State-changing actions like approving or rejecting builds and snapshots are available only if you explicitly add them to that agent's rules.