Developers · Beta
Run UX studies from your pipeline.
Launch a study on every preview deploy, read the ranked problems and the fix prompt, and get a signed webhook when something that was fixed comes back.
Overview
The API is included in the Agency and Enterprise plans. Other plans get 403 plan_required.
Base URL: https://app.uxsurgery.com/v1
Machine-readable reference (OpenAPI 3): https://app.uxsurgery.com/v1/openapi.json
Results come from synthetic participants (AI agents). Treat problems as candidates to confirm, not as evidence from real users.
A command-line tool and a GitHub Action are in beta and not published yet (see below); today, plain HTTP (curl) is all you need.
Authentication
Create a key in the app, under Developers. The full key is shown once: copy it into your CI secrets. We store only a hash. app.uxsurgery.com/developers
Send it on every request:
curl https://app.uxsurgery.com/v1/projects \
-H "Authorization: Bearer $UXS_API_KEY" Scopes: studies:write (launch, cancel, estimate), studies:read (status, results, fix prompt, report, artifacts), projects:read (list projects), projects:write (create website projects). A key can be limited to one project. Revoke a key at any time; it stops working immediately.
Errors
Every error is JSON with a stable code and a human-readable message:
{
"error": "unverified_target",
"message": "target_url must be on the project's verified domain (example.com) or a subdomain."
} | Status | error | When |
|---|---|---|
| 401 | invalid_key | Missing, unknown or revoked key |
| 402 | insufficient_credits | Not enough credits for the study |
| 403 | plan_required | The account is not on Agency or Enterprise |
| 403 | insufficient_scope | The key lacks the scope this endpoint needs |
| 403 | not_included | The fix prompt is not included in what paid for this study |
| 404 | not_found | Unknown id, or outside the key’s account or project |
| 409 | idempotency_conflict | Same Idempotency-Key with a different body |
| 409 | busy | A study of this project is still running (shared runner) |
| 409 | not_cancellable | The study has already finished |
| 409 | not_ready | The study has not finished yet |
| 422 | validation_error | The body does not match the schema |
| 422 | unverified_target | target_url is not on the project’s verified domain |
| 429 | rate_limited | Over 60 requests per minute (see Retry-After) |
| 429 | too_many_running | Too many API studies running at once (see Retry-After) |
Limits and credits
- 60 requests per minute per key. Over the limit you get 429 rate_limited with a Retry-After header in seconds.
- Up to 5 API-launched studies queued or running at the same time per Agency account (Enterprise: 20). Over the limit: 429 too_many_running.
- Credits work exactly as in the app: the study’s credits are reserved at launch, and the credits of sessions that did not run are returned when it finishes or is cancelled. Use POST /v1/estimate first to see the cost.
curl -X POST https://app.uxsurgery.com/v1/estimate \
-H "Authorization: Bearer $UXS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"project_id": "PROJECT_ID", "config": {"preset": "standard", "formats": ["desktop", "mobile"], "profiles": 4}}'
# {"sessions": 20, "credits": 20, "ai_cost_usd": 4.0, "balance": 812} Endpoints
| Method | Path | Scope | What it does |
|---|---|---|---|
GET | /v1/projects | projects:read | Your projects (only the key’s project if it is restricted) |
GET | /v1/projects/{id} | projects:read | One project, with its verified domain |
POST | /v1/projects | projects:write | Create a website project from its URL (201) |
POST | /v1/estimate | studies:read or studies:write | Sessions, credits and your balance for a config |
POST | /v1/studies | studies:write | Launch a study (202) |
GET | /v1/studies/{id} | studies:read | Status and progress |
GET | /v1/studies/{id}/results | studies:read | Findings and comparison with the project history |
GET | /v1/studies/{id}/fix-prompt | studies:read | Markdown fix prompt for your coding agent |
GET | /v1/studies/{id}/report | studies:read | Signed URL of the PDF (?redirect=true for a 302) |
GET | /v1/studies/{id}/artifacts | studies:read | Signed URLs of videos, screenshots, mockups and the report |
POST | /v1/studies/{id}/cancel | studies:write | Cancel a queued or running study (unused credits are returned) |
# Status and progress
curl https://app.uxsurgery.com/v1/studies/STUDY_ID -H "Authorization: Bearer $UXS_API_KEY"
# Findings and comparison with the project history
curl https://app.uxsurgery.com/v1/studies/STUDY_ID/results -H "Authorization: Bearer $UXS_API_KEY"
# Fix prompt (Markdown) for your coding agent
curl https://app.uxsurgery.com/v1/studies/STUDY_ID/fix-prompt -H "Authorization: Bearer $UXS_API_KEY" -o fixes.md
# PDF report: signed URL, or follow the redirect
curl -L "https://app.uxsurgery.com/v1/studies/STUDY_ID/report?redirect=true" -H "Authorization: Bearer $UXS_API_KEY" -o report.pdf
# Videos, screenshots and mockups (signed URLs)
curl https://app.uxsurgery.com/v1/studies/STUDY_ID/artifacts -H "Authorization: Bearer $UXS_API_KEY"
# Cancel a queued or running study (unused credits are returned)
curl -X POST https://app.uxsurgery.com/v1/studies/STUDY_ID/cancel -H "Authorization: Bearer $UXS_API_KEY" Launching a study
The config takes the same fields as the app: preset (standard, krug, extended), mode (public, app), formats (desktop, tablet, mobile), profiles (2–12), naive_profiles (0–3), tasks (up to 10), language (en, es), max_actions (actions per agent session, 6–40 up to the plan’s maximum: 20 on Starter and the Quick study, 40 on Pro, the Full study, Agency and Enterprise; default 15 for public websites and 20 for web apps; sessions over 20 actions use double credits; above the plan the API answers 422 max_actions_above_plan with max_actions_allowed) and exclude_paths.
curl -X POST https://app.uxsurgery.com/v1/studies \
-H "Authorization: Bearer $UXS_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $GITHUB_SHA-$GITHUB_RUN_ID" \
-d '{
"project_id": "PROJECT_ID",
"config": {
"preset": "standard",
"formats": ["desktop", "mobile"],
"profiles": 4,
"tasks": ["You want to know how much the Pro plan costs per year"],
"language": "en"
},
"target_url": "https://pr-42.preview.example.com",
"metadata": {"commit": "9f1c2ab", "branch": "feature/new-checkout", "default_branch": "main", "pr": 42}
}' target_url is optional. Use it to test a preview deploy: it must be https and its host must be the project’s verified domain or a subdomain of it (for example pr-42.preview.example.com for example.com). Anything else is rejected with 422 unverified_target. Verify the domain once in the app.
metadata is yours: up to 20 keys such as commit, branch, default_branch or pr. It is stored with the study and returned in every response and webhook. Send branch and default_branch if you use gates: they pick the baseline.
The answer is 202 Accepted with the study. Poll GET /v1/studies/{id} (every 30–60 s is plenty) or wait for the webhook. status is one of queued, running, cancelling, completed, limited (stopped by a limit, partial results), failed or cancelled.
The study object:
{
"id": "3f9a1c0e2b7d4e6f8a1b2c3d4e5f6a7b",
"object": "study",
"project_id": "PROJECT_ID",
"status": "running",
"progress": {"sessions_done": 8, "sessions_planned": 20, "percent": 40},
"iteration": 4,
"via": "api",
"metadata": {"commit": "9f1c2ab", "branch": "feature/new-checkout", "pr": 42},
"target_url": "https://pr-42.preview.example.com",
"credits_reserved": 20,
"credits_used": 0,
"error": null,
"created_at": "2026-10-01T09:12:03Z",
"started_at": "2026-10-01T09:12:40Z",
"finished_at": null,
"links": {
"self": "https://app.uxsurgery.com/v1/studies/3f9a…",
"results": "https://app.uxsurgery.com/v1/studies/3f9a…/results",
"report": "https://app.uxsurgery.com/v1/studies/3f9a…/report",
"fix_prompt": "https://app.uxsurgery.com/v1/studies/3f9a…/fix-prompt",
"artifacts": "https://app.uxsurgery.com/v1/studies/3f9a…/artifacts",
"app": "https://app.uxsurgery.com/studies/3f9a…"
}
} Idempotency
Send an Idempotency-Key header (any unique string up to 200 characters, e.g. the commit SHA plus the job id). Repeating the same key with the same body within 24 hours returns the same study instead of launching and charging a second one. The same key with a different body returns 409 idempotency_conflict.
Results and history
Results respect what paid for the study (the same entitlements as the app). Each finding has a severity from S1 (blocks the task) to S4 (cosmetic), the number of sessions and their session_ids, and evidence references with signed URLs (valid for about an hour).
comparison places the study in the project’s history: new problems, problems still_open from earlier studies, problems fixed (not seen again in a comparable study), problems that reappeared after being fixed, and unverifiable ones the study did not cover.
Results also carry links (the same as the study object) and a gate block, explained in the next section.
{
"study_id": "3f9a…",
"status": "completed",
"summary": "Visitors understand the offer, but pricing is hard to find on mobile…",
"top_problems": [{"title": "Pricing hidden behind the mobile menu", "severity": "S2", "finding_id": "t1"}],
"findings": [{
"id": "t1",
"title": "Pricing hidden behind the mobile menu",
"severity": "S2",
"cause": "product",
"sessions": 3,
"session_ids": ["s03", "s07", "s11"],
"formats": ["mobile"],
"recommendation": "Show a Pricing link in the mobile header.",
"evidence": [{"key": "studies/3f9a…/run/s03/shot_4.png", "url": "https://storage.googleapis.com/…"}],
"issue_id": "a81c…",
"history": "reappeared"
}],
"comparison": {
"baseline_study_id": "77be…",
"new": [], "still_open": [], "fixed": [],
"reappeared": [{"issue_id": "a81c…", "title": "Pricing hidden behind the mobile menu", "severity": "S2"}],
"unverifiable": []
},
"counts": {"findings": 6, "serious": 2, "new": 1, "still_open": 3, "fixed": 2, "reappeared": 1},
"links": {"self": "https://app.uxsurgery.com/v1/studies/3f9a…", "app": "https://app.uxsurgery.com/studies/3f9a…", "…": "…"},
"gate": {"baseline_study_id": "77be…", "baseline": "default_branch", "…": "see Gates"}
} Gates: failing a build
By default results are reported, not used to block a deploy: AI agents are not deterministic, and a problem found by synthetic participants is a candidate to confirm with real people. Gates are opt-in.
The gate block compares the study with a baseline: the last completed study whose metadata.branch is the default branch (metadata.default_branch sent by your CI, otherwise main or master), or, when no earlier study is on the default branch (for example without branch information), the most recent completed study. baseline says which rule was used (default_branch or latest); without any earlier study it is null and nothing counts as new.
new: product problems of this study that were not seen in the baseline. new_critical: the new ones with severity S1 or S2 seen in 2 or more sessions (one agent stumbling once does not fail a build). reappeared: problems marked fixed in an earlier study that are back.
failed tells you, for each fail-on option, whether the build should fail: failed["new-critical"] is true when new_critical is not empty, failed["reappeared"] when reappeared is not empty, and failed["none"] is always false. The command-line tool and the GitHub Action just read it.
"gate": {
"baseline_study_id": "77be…",
"baseline": "default_branch",
"default_branch": "main",
"new": [
{"issue_id": "c42d…", "finding_id": "t2", "title": "Checkout button below the fold on mobile", "severity": "S1", "sessions": 3},
{"issue_id": "d913…", "finding_id": "t5", "title": "Footer links too small to tap", "severity": "S3", "sessions": 1}
],
"new_critical": [
{"issue_id": "c42d…", "finding_id": "t2", "title": "Checkout button below the fold on mobile", "severity": "S1", "sessions": 3}
],
"reappeared": [
{"issue_id": "a81c…", "finding_id": "t1", "title": "Pricing hidden behind the mobile menu", "severity": "S2", "sessions": 3}
],
"failed": {"new-critical": true, "reappeared": true, "none": false}
} Cancelling a study
POST /v1/studies/{id}/cancel works on queued and running studies. A queued study becomes cancelled at once and every reserved credit is returned.
A running study becomes cancelling: sessions already in progress finish (usually a few minutes), no new session starts, and then it becomes cancelled. Only completed sessions are charged; the rest of the reservation is returned. No study.completed webhook is sent for a cancelled study.
A study that has already finished answers 409 not_cancellable.
curl -X POST https://app.uxsurgery.com/v1/studies/STUDY_ID/cancel -H "Authorization: Bearer $UXS_API_KEY"
# Running study: {"id": "3f9a…", "status": "cancelling", "progress": {"sessions_done": 8, …}, …}
# A few minutes later, GET /v1/studies/STUDY_ID: {"status": "cancelled", "credits_used": 10, …} Webhooks
Add an https endpoint in the app, under Developers. Its signing secret starts with whsec_ and is shown once.
Events: study.completed, study.failed and regression.detected (a problem that had been fixed reappears, or a new S1/S2 problem appears in a project with earlier studies). The “Send test event” button sends webhook.test.
We POST JSON with the headers X-UXS-Signature, X-UXS-Event and X-UXS-Delivery. Any 2xx within 10 seconds counts as delivered; otherwise we retry up to 3 attempts in total, with backoff. Every attempt appears in the delivery log in the app. Deliveries can arrive more than once: use the event id to deduplicate.
Payload:
{
"id": "evt_5c1e…",
"type": "regression.detected",
"created_at": "2026-10-01T09:41:17Z",
"data": {
"study": {"id": "3f9a…", "status": "completed", "iteration": 4, "project_id": "PROJECT_ID",
"metadata": {"commit": "9f1c2ab", "pr": 42}, "target_url": "https://pr-42.preview.example.com",
"sessions_done": 20, "credits_used": 20, "finished_at": "2026-10-01T09:41:15Z"},
"project": {"id": "PROJECT_ID", "name": "Example", "host": "example.com"},
"summary": {"findings": 6, "serious": 2, "new": 1, "still_open": 3, "fixed": 2, "reappeared": 1},
"regressions": [{"issue_id": "a81c…", "title": "Pricing hidden behind the mobile menu", "severity": "S2"}],
"links": {"app": "https://app.uxsurgery.com/studies/3f9a…", "api": "https://app.uxsurgery.com/v1/studies/3f9a…",
"results": "https://app.uxsurgery.com/v1/studies/3f9a…/results", "report": "https://app.uxsurgery.com/v1/studies/3f9a…/report"}
}
} Verifying signatures
X-UXS-Signature looks like t=1759312800,v1=5f2c…. Compute HMAC-SHA256 with your secret over the timestamp, a dot and the raw request body (before any JSON parsing), compare in constant time, and reject timestamps older than 5 minutes.
// Node 18+ (Express): keep the raw body, the signature covers the exact bytes.
import crypto from "node:crypto";
import express from "express";
const SECRET = process.env.UXS_WEBHOOK_SECRET; // whsec_...
const app = express();
function verify(rawBody, header, toleranceSeconds = 300) {
const parts = Object.fromEntries((header || "").split(",").map((p) => p.split("=", 2)));
const t = Number(parts.t);
if (!t || !parts.v1 || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
const expected = crypto.createHmac("sha256", SECRET).update(`${t}.${rawBody}`).digest("hex");
const a = Buffer.from(expected, "hex");
const b = Buffer.from(parts.v1, "hex");
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
app.post("/uxs-webhook", express.raw({ type: "application/json" }), (req, res) => {
if (!verify(req.body.toString("utf8"), req.get("X-UXS-Signature"))) return res.sendStatus(400);
const event = JSON.parse(req.body.toString("utf8"));
// Deduplicate on event.id, then react to event.type
res.sendStatus(204);
});
app.listen(3000); # Python 3 (standard library only)
import hashlib, hmac, os, time
SECRET = os.environ["UXS_WEBHOOK_SECRET"].encode() # whsec_...
def verify(raw_body: bytes, header: str, tolerance: int = 300) -> bool:
parts = dict(p.split("=", 1) for p in (header or "").split(",") if "=" in p)
try:
t = int(parts["t"])
except (KeyError, ValueError):
return False
if abs(time.time() - t) > tolerance:
return False
expected = hmac.new(SECRET, f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts.get("v1", ""))
# Flask: verify(request.get_data(), request.headers.get("X-UXS-Signature")) Command-line tool (beta)
Beta: the uxsurgery command-line tool is not on npm yet. Once it is published you will run it with npx uxsurgery@latest (Node 18 or later); until then use the curl examples on this page, or ask us for early access.
It reads UXS_API_KEY and UXS_API_URL (default https://app.uxsurgery.com). In CI it sends an Idempotency-Key built from GITHUB_SHA and GITHUB_RUN_ID (GitLab: CI_COMMIT_SHA and CI_PIPELINE_ID), so a retried job never starts or charges a second study, and adds commit, branch, default_branch and pr to the metadata automatically.
# Beta: not on npm yet. Once published (Node 18+):
export UXS_API_KEY=uxs_live_... # a CI secret, never in the repository
npx uxsurgery@latest run --project PROJECT_ID \
--url https://pr-42.preview.example.com \
--preset standard --formats desktop,mobile \
--wait --timeout 90m --fail-on new-critical
npx uxsurgery@latest status STUDY_ID
npx uxsurgery@latest results STUDY_ID --markdown
npx uxsurgery@latest fix-prompt STUDY_ID > fix.md
npx uxsurgery@latest cancel STUDY_ID --wait polls until the study finishes (up to --timeout, e.g. 90m); --fail-on reads the gate block; --json prints machine-readable output.
| Exit code | Meaning |
|---|---|
0 | OK (the study finished and the gate, if any, passed) |
1 | The --fail-on gate triggered |
2 | Error: bad usage, authentication or HTTP error, timeout, or the study failed or was cancelled |
GitHub Action (beta)
GitHub Action (beta): it is not published yet (not on the GitHub Marketplace). Agency customers can ask us for early access; we will send the uses: reference to put in place of UXS_ACTION below.
It launches a study for the pull request, waits, posts one comment on the pull request (updated on every run, not a new one each time) with the top problems, highlighting new and reappeared ones, and links to the report and the session videos in the app. It uploads fix-prompt.md as a workflow artifact when your plan includes the fix prompt.
Inputs: api-key, project, url, preset, formats, fail-on (default none), comment (default true), timeout, api-url. Outputs: study-id, status, new-problems. The comment needs permissions: pull-requests: write.
# .github/workflows/ux-study.yml
name: UX study
on: pull_request
permissions:
contents: read
pull-requests: write # one comment per pull request, updated on each run
jobs:
ux:
runs-on: ubuntu-latest
steps:
# GitHub Action (beta): not on the Marketplace yet.
# Agency customers get the uses: reference with early access.
- id: uxs
uses: UXS_ACTION
with:
api-key: ${{ secrets.UXS_API_KEY }}
project: ${{ vars.UXS_PROJECT_ID }}
url: https://pr-${{ github.event.number }}.preview.example.com
preset: standard
formats: desktop,mobile
fail-on: new-critical # none (default), new-critical or reappeared
comment: true
timeout: 90m
- run: echo "Study ${{ steps.uxs.outputs.study-id }} ${{ steps.uxs.outputs.status }}, ${{ steps.uxs.outputs.new-problems }} new problems" GitLab CI
The same flow in GitLab CI with the command-line tool (beta, not on npm yet). Store UXS_API_KEY as a masked CI/CD variable.
# .gitlab-ci.yml (the CLI is in beta and not on npm yet)
ux-study:
stage: test
image: node:22
rules:
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
variables:
UXS_PROJECT: "PROJECT_ID"
# UXS_API_KEY: masked CI/CD variable (Settings > CI/CD > Variables)
script:
- npx uxsurgery@latest run --project $UXS_PROJECT --url $CI_ENVIRONMENT_URL --wait --fail-on new-critical --fix-prompt fix-prompt.md > uxsurgery.md
artifacts:
when: always
paths: [uxsurgery.md, fix-prompt.md] Example: CI with curl
What works today without the command-line tool: launch on each pull request with curl, wait, and fail the job only when the gate says so. Store the key as a secret (UXS_API_KEY).
# .github/workflows/ux-study.yml
name: UX study
on: pull_request
jobs:
ux:
runs-on: ubuntu-latest
steps:
- name: Launch and wait
env:
UXS_API_KEY: ${{ secrets.UXS_API_KEY }}
API: https://app.uxsurgery.com/v1
PROJECT_ID: ${{ vars.UXS_PROJECT_ID }}
TARGET: https://pr-${{ github.event.number }}.preview.example.com
run: |
set -euo pipefail
auth="Authorization: Bearer $UXS_API_KEY"
body=$(jq -n --arg p "$PROJECT_ID" --arg u "$TARGET" --arg c "$GITHUB_SHA" --arg b "$GITHUB_HEAD_REF" \
--arg d "${{ github.event.repository.default_branch }}" --argjson pr ${{ github.event.number }} \
'{project_id: $p, target_url: $u, config: {preset: "standard", formats: ["desktop", "mobile"], profiles: 3},
metadata: {commit: $c, branch: $b, default_branch: $d, pr: $pr}}')
id=$(curl -sf -X POST "$API/studies" -H "$auth" -H "Content-Type: application/json" \
-H "Idempotency-Key: $GITHUB_SHA-$GITHUB_RUN_ID" -d "$body" | jq -r .id)
echo "Study $id"
while :; do
status=$(curl -sf "$API/studies/$id" -H "$auth" | jq -r .status)
case "$status" in completed|limited|failed|cancelled) break ;; esac # cancelling is not final
sleep 60
done
curl -sf "$API/studies/$id/results" -H "$auth" > results.json
jq '.gate | {new: (.new | length), new_critical: (.new_critical | length), reappeared: (.reappeared | length)}' results.json
test "$(jq '.gate.failed["new-critical"]' results.json)" = false Need access or higher limits? info@uxsurgery.com · See the Agency plan · Security & privacy