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."
}
StatuserrorWhen
401invalid_keyMissing, unknown or revoked key
402insufficient_creditsNot enough credits for the study
403plan_requiredThe account is not on Agency or Enterprise
403insufficient_scopeThe key lacks the scope this endpoint needs
403not_includedThe fix prompt is not included in what paid for this study
404not_foundUnknown id, or outside the key’s account or project
409idempotency_conflictSame Idempotency-Key with a different body
409busyA study of this project is still running (shared runner)
409not_cancellableThe study has already finished
409not_readyThe study has not finished yet
422validation_errorThe body does not match the schema
422unverified_targettarget_url is not on the project’s verified domain
429rate_limitedOver 60 requests per minute (see Retry-After)
429too_many_runningToo 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

MethodPathScopeWhat it does
GET/v1/projectsprojects:readYour projects (only the key’s project if it is restricted)
GET/v1/projects/{id}projects:readOne project, with its verified domain
POST/v1/projectsprojects:writeCreate a website project from its URL (201)
POST/v1/estimatestudies:read or studies:writeSessions, credits and your balance for a config
POST/v1/studiesstudies:writeLaunch a study (202)
GET/v1/studies/{id}studies:readStatus and progress
GET/v1/studies/{id}/resultsstudies:readFindings and comparison with the project history
GET/v1/studies/{id}/fix-promptstudies:readMarkdown fix prompt for your coding agent
GET/v1/studies/{id}/reportstudies:readSigned URL of the PDF (?redirect=true for a 302)
GET/v1/studies/{id}/artifactsstudies:readSigned URLs of videos, screenshots, mockups and the report
POST/v1/studies/{id}/cancelstudies:writeCancel 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 codeMeaning
0OK (the study finished and the gate, if any, passed)
1The --fail-on gate triggered
2Error: 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