Docs
API and MCP
Your own agents can run WitnessQA: audit a site, test one flow, or check its links, SEO or speed, and get back every problem with how to fix it. Add it to Claude Code or Cursor as an MCP server, or call the HTTP API. Every run is paid from your credits.
Get started
-
Make an API key
In the app, open API keys, name the key after where it is used and click Make a key. Copy it: it is shown only once. Anyone with it can spend your credits, so keep it out of code and chats, and revoke it on the same page when you no longer need it.
-
Add it to Claude Code
claude mcp add --transport http witnessqa https://api.witnessqa.com/mcp \ --header "Authorization: Bearer wq_YOUR_KEY" -
Or to Cursor and other MCP clients
In the client's MCP settings, for example
.cursor/mcp.json:{ "mcpServers": { "witnessqa": { "url": "https://api.witnessqa.com/mcp", "headers": { "Authorization": "Bearer wq_YOUR_KEY" } } } } -
Ask your agent
For example: "Audit example.com with WitnessQA and fix what it finds", or "Check that the sign-up form on staging.example.com shows an error for a wrong email".
Tools and what they cost
Each tool runs on any public site, read-only: forms are filled to check them, never sent. A run is charged when it ends with a result; one that could not reach the site costs nothing. Credits are the same as in the app: your plan's month first, then credit packs.
| Tool | What it does | Credits |
|---|---|---|
audit_site | Walks the main flows of a site on a desktop and a phone like a new visitor, then checks every link, measures speed and reads the pages as search engines and AI assistants do. Returns the scores and each problem found with evidence and the fix for the platform the site runs on. Takes about 3 minutes. A page behind a login works too: when the address is in an environment of one of your projects with a test account, the agent signs in with it first. The password never leaves WitnessQA. | 20 |
test_page | The agent opens the page at the address, on a desktop and a phone, and tries what it offers: its buttons, links, tabs, menus and forms. It reports anything broken with evidence and the fix. Read-only: forms are filled to check them, never sent. Takes about a minute. A page behind a login works too: when the address is in an environment of one of your projects with a test account, the agent signs in with it first. The password never leaves WitnessQA. | 5 |
test_flow | The agent opens the site and does what the goal says across its pages, on a desktop and a phone, then reports each step and any problem it hit. Read-only: it fills forms to check them but never sends anything that buys, signs up or deletes. Takes about 2 minutes. A page behind a login works too: when the address is in an environment of one of your projects with a test account, the agent signs in with it first. The password never leaves WitnessQA. | 8 |
check_links | Opens every link on the start page and the pages it leads to, internal and external, and says which ones are broken. No AI agent. Takes under a minute. | 1 |
check_seo | Reads up to 15 pages the way search engines and AI crawlers do: titles, descriptions, headings, canonicals, structured data, robots.txt per crawler, sitemap and content without JavaScript. No AI agent. Takes about a minute. | 2 |
check_speed | Measures the main pages on a throttled phone and a desktop: Largest Contentful Paint, layout shift, blocking time, server response and page weight, with what slows each page down. No AI agent. Takes about 2 minutes. | 3 |
get_run | A run started earlier: its state, then its result. | 0 |
get_skill | A checklist from Learn as SKILL.md, for your agent to follow: seo-agent-readiness. | 0 |
Pages behind a login. When the address is in an environment of one of your projects, the run is that project's: the agent signs in with the environment's test account (set under Login options), goes through its protected staging if it has one, and the run is kept with the project's runs instead of on a public report link. The password never leaves WitnessQA. Runs on a project stay read-only: nothing is sent, bought or deleted, and the one goal of a run does not join the regression suite.
Over MCP a tool waits about a minute for its run. If the run is not done by then, it answers with the run id, and
the agent calls get_run a little later.
The HTTP API
Send the key as a bearer token. Start a run, then read it until its status is no longer queued or running.
curl -X POST https://api.witnessqa.com/v1/runs \
-H "Authorization: Bearer $WITNESSQA_KEY" -H "content-type: application/json" \
-d '{"tool":"test_flow","url":"https://example.com","goal":"Open pricing, switch to yearly, and check the prices change."}'
# 202 {"id":"3f9a1c2b7d4e8f01","status":"queued","credits":8,"reportUrl":"https://app.witnessqa.com/r/3f9a1c2b7d4e8f01"} curl https://api.witnessqa.com/v1/runs/3f9a1c2b7d4e8f01 -H "Authorization: Bearer $WITNESSQA_KEY" A finished run, shortened:
{
"id": "3f9a1c2b7d4e8f01",
"tool": "audit_site",
"status": "bug_found",
"credits": 20,
"scores": { "overall": 74, "works": 80, "speed": 61, "seo": 88 },
"problems": [
{
"title": "Broken link to /old-pricing (404)",
"area": "seo",
"severity": "medium",
"sure": true,
"summary": "A link on /pricing leads to /old-pricing, which does not exist.",
"fix": { "steps": ["Point the link at /pricing", "Or redirect /old-pricing with a 301"], "minutes": 10 }
}
],
"brokenLinks": [{ "url": "https://example.com/old-pricing", "status": 404, "foundOn": "https://example.com/pricing" }],
"reportUrl": "https://app.witnessqa.com/r/3f9a1c2b7d4e8f01"
} GET /v1/toolslists the tools with what each does and costs, without a key.statusends aspassed,bug_found,needs_revieworblocked(the site did not open;errorsays why, and it costs nothing).- Each problem says whether it is
sureor only worth a look, and carries the fix for the platform the site runs on. - Every run is also a report people can open at
reportUrl, kept 7 days.
Limits and errors
- Up to 30 runs an hour per account, across its keys. Past that:
429 rate_limited. - Not enough credits for the tool:
402 no_credits, with how many are left. Add credits under Plan and billing. - A wrong tool, address or goal:
400with acodeand amessagein plain words. A private address is refused. - No key, a wrong one or a revoked one:
401. Up to 10 keys per account.