Welcome to the bugAgent API

Register a new agent account. Accounts created via this endpoint are automatically flagged as is_agent: true. A unique workspace is created for each new account.

Request Body

Response

{
  "userId": "uuid",
  "email": "[email protected]"
}

Sign in and receive a JWT access token. Use the returned token as a Bearer token for subsequent requests, or generate a long-lived API key instead.

Request Body

Response

{
  "userId": "uuid",
  "email": "[email protected]",
  "accessToken": "eyJhbG...",
  "refreshToken": "refresh_...",
  "expiresAt": 1711234567
}

List bug reports for the authenticated user's account and team. Returns reports in reverse chronological order.

Query Parameters

Example

curl "https://app.bugagent.com/api/reports?type=crash&limit=10" \
  -H "Authorization: Bearer ba_live_..."

Create a new report. Supports bugs, feature requests, enhancements, technical debt, and more. If type is omitted, bugAgent auto-classifies based on title and description.

Request Body

Response

{
  "id": "1fb72a2c-87c7-4adf-90e7-9bd81a8f34b7",
  "ticket_number": 545,
  "short_id": "WRKID-545",
  "title": "Login button unresponsive on iOS",
  "type": "ui",
  "severity": "high",
  "classification": { "type": "ui", "confidence": 0.85 },
  "quality_score": 7,
  "quality_breakdown": {
    "reproduction_steps": 0.9,
    "expected_vs_actual": 0.8,
    "environment_details": 0.7,
    "evidence": 0.6,
    "root_cause_analysis": 0.5,
    "impact_assessment": 0.8,
    "context_and_history": 0.6,
    "heuristics_and_oracles": 0.7,
    "clarity_and_structure": 0.9,
    "actionability": 0.8
  },
  "created_at": "2026-03-17T12:00:00Z",
  ...
}

Reformat a bug report description into a structured bug template using AI. Returns the formatted description text without modifying the report. Use this to preview the AI formatting before saving.

Request Body

Response

{ "formatted": "## Summary\nLogin button is unresponsive...\n\n## Steps to Reproduce\n1. Navigate to...\n\n## Expected Behavior\n...\n\n## Actual Behavior\n..." }

Retrieve a single bug report by ID. Returns 404 if the report doesn't exist or you don't have access.

ID formats: :id accepts either the UUID (e.g. 1fb72a2c-87c7-4adf-90e7-9bd81a8f34b7) or the workspace-scoped short ID (e.g. WRKID-545). Short-ID lookups are scoped to your active team — guessing another workspace's short ID returns 404.

Response Fields (includes all standard fields plus)

Update a bug report. Only fields you include in the body are updated.

ID formats: :id accepts either the UUID or the short ID (e.g. WRKID-545). Same rules apply across all /api/reports/:id verbs.

Request Body

Assign a bug report to a team member. A database trigger automatically fires the in-app bell notification AND an email to the new assignee whenever the assignee actually changes (re-saving the same user is silent). Same trigger pipeline is reached by every other update path (PATCH /api/reports/:id, the MCP update_bug_report tool, raw SQL) so notifications are consistent regardless of how the assignment happened.

Request Body

Response

Returns success: true and notified: true if the bell-icon notification was inserted. The email send is fire-and-forget — the response returns before it completes. The assignee can mute the email channel at /dashboard/settings#notifications (in-app bell is always shown).

Upload file attachments (screenshots, screen recordings, audio memos, documents) to a bug report. Uses multipart/form-data.

Form Fields

Bulk delete old bug reports. Requires owner or admin team role.

Request Body

Response

{ "deleted": 42 }

Add a comment to a bug report, or toggle an emoji reaction on a comment.

Create Comment

Toggle Reaction

Edit a comment. Only the author can edit their own comments.

Delete a comment. Only the author can delete their own comments.

List all projects for your team.

Create a new project. The first project is automatically set as default. Subject to plan limits.

Request Body

Update a project's name, description, or default status.

Permanently delete a project and all associated data. Only owners and managers can delete projects. You cannot delete your last project — every workspace must have at least one.

Request Body (JSON)

What Gets Deleted

Important Behavior

Errors

List your active (non-revoked) API keys. Only the key prefix is returned — full keys are shown once at creation.

Generate a new API key. The full key (starting with ba_live_) is returned only once — store it securely.

Request Body

Response

{
  "key": "ba_live_abc123...",
  "id": "uuid",
  "name": "CI Pipeline",
  "key_prefix": "ba_live_abc123",
  "scopes": ["reports:read", "reports:write"],
  "created_at": "2026-03-17T12:00:00Z"
}

Revoke an API key. The key is soft-deleted and can no longer be used for authentication.

Revoke the current key and generate a new one with the same name and scopes. Returns the new full key.

Get the authenticated user's profile.

Response

{
  "id": "uuid",
  "email": "[email protected]",
  "full_name": "Jane Smith",
  "avatar_url": null,
  "plan": "pro",
  "is_agent": false,
  "created_at": "2026-03-10T08:00:00Z"
}

Update your profile. Only full_name can be changed via the API (security: no email, role, or plan changes).

Change your password.

Get your profile info and notification preferences.

Response

{
  "fullName": "Jane Smith",
  "email": "[email protected]",
  "isAgent": false,
  "plan": "pro",
  "notifications": {
    "emailUsageWarning": true,
    "emailBugReportAssignment": true,
    "emailTestCaseAssignment": true
  }
}

Update notification preferences.

Get your current plan usage (reports used, limit, remaining, reset date).

Response

{
  "used": 47,
  "limit": 5000,
  "remaining": 4953,
  "plan": "pro",
  "period": "monthly",
  "resetsAt": "2026-04-01T00:00:00Z"
}

Get report statistics with daily counts, breakdowns by type, severity, and status.

Query Parameters

Response

{
  "period": "30 days",
  "total": 127,
  "daily": [
    { "date": "2026-02-16", "count": 3 },
    { "date": "2026-02-17", "count": 5 },
    ...
  ],
  "byType": { "ui": 42, "crash": 18, "logic": 67, "feature-request": 12, "enhancement": 8 },
  "bySeverity": { "high": 23, "medium": 89, "low": 15 },
  "byStatus": { "open": 95, "resolved": 32 }
}

Create a Stripe checkout session to upgrade your plan. Returns a URL to redirect the user to.

Request Body

Response

{ "url": "https://checkout.stripe.com/..." }

Get a URL to the Stripe billing portal where users can manage subscriptions, payment methods, and invoices.

Response

{ "url": "https://billing.stripe.com/..." }

Invite a user to your team. Sends an email invitation with a 5-day expiry. Invited users join the inviting workspace directly — no separate workspace is created.

Form Data

Edit a team member's display name inline. Owners and admins can edit any non-owner member. Managers can edit contributors and other managers but not owners or admins.

Form Data

Change a team member's role. Managers can assign contributor or manager roles. Only owners/admins can assign admin. Owner role can only be changed via ownership transfer.

Form Data

Remove a team member from the workspace. Only owners and managers can remove members. Owners cannot be removed. All data created by the removed user (bug reports, automations, test cases, mobile apps, geo snaps, schedules, time tracking) is reassigned to the person performing the removal. Notes are deleted. The user's profile is preserved as a ghost stub for foreign-key integrity and re-invite capability.

Form Data

Switch the active workspace context. Users who belong to multiple workspaces use this to change which workspace's data they see.

Request Body (JSON)

Create a new workspace. Available to all plan tiers (Free, Pro, Team, Enterprise) with a 100-workspace cap per user. New workspaces start on the free plan and can be upgraded via billing. If no name is provided, a unique uplifting name is auto-generated (e.g. "Radiant Foxes"). A Default Project is automatically created so the workspace always has at least one project.

Request Body (JSON)

Response

{
  "success": true,
  "team": {
    "id": "uuid",
    "name": "Radiant Foxes",
    "plan": "pro"
  }
}

Errors

Start the Jira OAuth 2.0 flow. Redirects to Atlassian's authorization page. The resulting connection is stored against the user's active team, not the individual user.

Fetch all Jira projects accessible by the team's shared connection. Used to populate the project dropdown when pushing a report to Jira for the first time. Returns the default project key if one is saved.

Response

{
  "projects": [
    { "id": "10001", "key": "BUG", "name": "Bug Tracker", "avatar": "https://..." },
    { "id": "10002", "key": "PROJ", "name": "Main Project", "avatar": "https://..." }
  ],
  "defaultProjectKey": "BUG"
}

Sync a bug report to Jira using the team's shared connection. Creates a Jira issue with mapped fields, labels, and uploads any attachments. Severity is mapped to Jira priority (s1/critical→Highest, s2/high→High, s3/medium→Medium, s4/low→Low). Any authenticated team member can sync.

Request Body

Response

{
  "success": true,
  "jiraKey": "PROJ-1234",
  "jiraUrl": "https://your-site.atlassian.net/browse/PROJ-1234"
}

Force an immediate bi-directional sync between bugAgent and Jira. Triggered by the sync button next to the AUTO SYNC badge on the report detail page. Syncs description, title, severity/priority, comments, and media attachments.

Request Body

Sync Behavior

Response

{
  "success": true,
  "results": [
    "Description synced",
    "Priority pushed to Jira (high — last updated)",
    "2 comment(s) pushed to Jira",
    "1 attachment(s) pulled from Jira"
  ]
}

Check if a synced Jira issue has been modified. Compares title, severity, status, and type between bugAgent and Jira. Severity uses last-updated-wins logic and is auto-applied during polling. Comments and attachments are synced bi-directionally via the auto-sync polling and force-sync endpoints.

Query Parameters

Response

{
  "hasChanges": true,
  "jiraUpdatedAt": "2026-03-18T15:30:00.000Z",
  "changes": {
    "title": { "jira": "Updated title in Jira", "bugagent": "Original title" },
    "severity": { "jira": "high", "bugagent": "medium" }
  }
}

Bi-directional merge between bugAgent and Jira. Updates bugAgent with the chosen values, then pushes them to Jira so both systems are identical. Severity is mapped to Jira priority. For automatic conflict resolution, use /api/jira/force-sync which applies last-updated-wins logic.

Request Body

Update the team's Jira integration settings or disconnect. Only managers and above can modify these settings.

Request Body

Batch-sync report statuses with Jira. Used by the Kanban board to push status changes after drag-and-drop reordering. Fetches the latest Jira status for each report and reconciles any differences.

Request Body

Response

{
  "updates": [
    {
      "id": "uuid",
      "old_status": "new",
      "new_status": "in-progress",
      "jira_status": "In Progress"
    }
  ],
  "synced": 1
}

Create a new automation. Stores the recorded steps, generated Playwright script, and optional schedule. The automation is scoped to the user's active team.

Request Body

Response

{
  "id": "uuid",
  "name": "Login flow smoke test",
  "steps": [ ... ],
  "script": "import { test } from '@playwright/test'; ...",
  "schedule": "0 9 * * 1-5",
  "start_url": "https://app.example.com/login",
  "status": "active",
  "team_id": "uuid",
  "created_by": "uuid",
  "created_at": "2026-03-21T12:00:00Z",
  "updated_at": "2026-03-21T12:00:00Z"
}

Create a new automation with a custom Playwright script. Unlike POST /automations which expects recorded FAB steps, this endpoint lets you supply a script directly — ideal for hand-written tests, AI-generated scripts, or scripts imported from an existing test suite.

Supported languages: Node.js/JavaScript/TypeScript and Python. The runner auto-detects the language from the script's imports (from playwright/import playwright → Python; otherwise Node). Python scripts run under pytest if they define a def test_* function, otherwise under python3. Other languages (C#, Java, etc.) aren't supported yet.

Duplicating an Automation

To duplicate an existing automation, fetch its details via GET /api/automations/:id, then call this endpoint with the original's script, target_url, and project_id. Set name to "[Copy] Original Name". The duplicate starts in "draft" status and does not inherit version history or run history from the original.

Request Body

Authentication

Requires session authentication (dashboard) or an API key with automations:write scope.

Plan

Pro or Team plan required.

Response

{
  "id": "uuid"
}

List all automations for the user's active team. Supports pagination and filtering by status.

Query Parameters

Response

{
  "automations": [
    {
      "id": "uuid",
      "name": "Login flow smoke test",
      "status": "active",
      "project_id": "proj_uuid",
      "created_by": "user_uuid",
      "schedule": "0 9 * * 1-5",
      "last_run_at": "2026-03-21T09:00:00Z",
      "last_run_status": "passed",
      "run_count": 42,
      "created_at": "2026-03-20T12:00:00Z"
    }
  ],
  "total": 5,
  "page": 1,
  "limit": 20
}

Get full details of a single automation, including recorded steps, generated Playwright script, schedule, recent run history, and saved script version history (the stack that version_index on the run endpoints indexes into).

Response

{
  "id": "uuid",
  "name": "Login flow smoke test",
  "steps": [
    { "action": "navigate", "url": "https://app.example.com/login" },
    { "action": "fill", "selector": "#email", "value": "[email protected]" },
    { "action": "fill", "selector": "#password", "value": "********" },
    { "action": "click", "selector": "button[type=submit]" },
    { "action": "assert", "selector": ".dashboard-title", "text": "Welcome" }
  ],
  "script": "import { test, expect } from '@playwright/test'; ...",
  "script_versions": [
    { "script": "// older text of the script", "source": "manual_edit", "timestamp": "2026-03-20T13:42:00Z" },
    { "script": "// the state before an AI-optimize ran", "source": "before_optimize", "timestamp": "2026-03-21T07:50:00Z" }
  ],
  "schedule": "0 9 * * 1-5",
  "start_url": "https://app.example.com/login",
  "status": "active",
  "team_id": "uuid",
  "created_by": "uuid",
  "created_at": "2026-03-20T12:00:00Z",
  "updated_at": "2026-03-21T08:00:00Z",
  "recent_runs": [
    { "id": "uuid", "status": "passed", "duration_ms": 4200, "started_at": "2026-03-21T09:00:00Z", "script_version_label": "current", "script_version_source": "current" }
  ]
}

Notes

• script is always the current live version — the one Run Now executes when version_index is omitted.
• script_versions is a chronological stack (oldest first) of up to 100 prior states of script. An entry is pushed whenever script changes via PATCH, optimize, or the BrowserStack rewrite. Each entry records { script, source, timestamp }; valid source values are manual_edit, before_optimize, bs_compat_rewrite. Callers index into this array with version_index on POST /automations/runs or POST /v1/automations/run to replay a historical version. Omit version_index to run script (current).
• Each entry in recent_runs carries the version it executed as script_version_label ("current" or "vN") and script_version_source. The per-run script text itself is on the run detail (script_snapshot) — omitted from list responses to keep them small.

Update an existing automation. Only provided fields are changed. Use this to rename, update the script, change the schedule, or pause/resume.

Request Body

Response

{
  "id": "uuid",
  "name": "Login flow smoke test (updated)",
  "status": "paused",
  "schedule": null,
  "updated_at": "2026-03-21T14:00:00Z"
}

Notes

• GET responses include auth_has_password: true|false so clients can render a "password set" indicator without ever seeing the ciphertext.
• Pre-auth runs a heuristic login: navigate to auth_signin_url, fill the password field (and username/email if provided) via role/type selectors, submit, wait for networkidle. Supports username+password flows (including two-step email → Next → password) and password-only front-door gates.
• When the heuristic selectors don't match the signin page (e.g. non-standard input names, custom-element wrappers), the runner falls back to a Claude-assisted locator plan. The runner captures the signin form HTML, ships it to Claude (with "USERNAME" / "PASSWORD" placeholders so credentials never hit the model), receives a structured step list (fill / click / wait), and executes it. No additional user configuration required — this happens automatically on every pre-auth miss.
• On BrowserStack (including iOS Playwright), pre-auth runs as a test.beforeEach hook injected into the remote browser's test — a storage-state handoff from a local Chromium would fail because of IP pinning and engine mismatch. The injected prologue uses either the heuristic or the Claude-built plan, whichever the runner's local probe determined would work on this particular signin page.

Permanently delete an automation and all its associated run history. This action cannot be undone.

Response

{ "deleted": true }

Generate a Playwright script from recorded browser steps using AI. The generated script includes assertions, error handling, and is ready to run. Optionally saves the script to an existing automation.

Request Body

Response

{
  "script": "import { test, expect } from '@playwright/test';\n\ntest('Login flow smoke test', async ({ page }) => {\n  await page.goto('https://app.example.com/login');\n  await page.fill('#email', '[email protected]');\n  await page.fill('#password', '********');\n  await page.click('button[type=submit]');\n  await expect(page.locator('.dashboard-title')).toContainText('Welcome');\n});",
  "automation_id": "uuid"
}

Send a Playwright script to Sonnet 4 for AI-powered optimization. Applies a 12-point checklist that automatically fixes selectors, wait strategies, assertions, error handling, auth patterns, mobile compatibility, and strict mode issues. The current script version is saved before optimization so you can undo the change.

URL Parameters

Response

{
  "script": "// optimized Playwright script...",
  "version": 3,
  "changes_summary": "Fixed 4 issues: replaced fragile text selectors with data-testid, added explicit waitForLoadState, improved assertions with toBeVisible, added error recovery for auth flow."
}

Revert the automation script to the most recent entry in script_versions. Pops the top of the stack (newest prior version) and promotes it to script. Up to 100 prior versions are retained. Versions are saved before manual edits, AI optimization, and BrowserStack rewrites. To replay (not revert to) a specific historical version without mutating current, pass version_index to POST /automations/runs instead.

URL Parameters

Response

{
  "script": "// previous version of the script...",
  "version": 2,
  "versions_remaining": 1
}

{ "error": "No previous versions available to undo" }

Rewrite a script-style Python Playwright script (sync_playwright() + browser.new_page() + if __name__ == "__main__":) into pytest-style (def test_<name>(page: Page):), which is what bugAgent Live (BrowserStack) requires for Python runs. Driven by Claude Haiku; behavior is preserved — every page.goto, click, fill, wait, and assertion carries over. The endpoint only performs the rewrite; it doesn't save. The caller sends a subsequent PATCH /api/automations/:id to commit (the dashboard UI does this on Accept, tagged version_source: "bs_compat_rewrite" so the regular Undo flow can roll it back).

Request Body

Response

{
  "rewritten": "from playwright.sync_api import Page, expect\n\ndef test_navigate_and_wait(page: Page):\n    page.goto(\"https://example.com\")\n    ..."
}

Notes

• The dashboard shows an amber "Not compatible with bugAgent Live" banner on the automation detail page when a Python script lacks a def test_*(page): function, with a one-click rewrite button that calls this endpoint.
• Requires ANTHROPIC_API_KEY on the Dashboard service. Returns 500 with a clear error if not configured.
• Markdown code fences in Claude's output are stripped defensively before returning — the response is always raw Python source, never wrapped in ```python … ```.
• Does not modify stored data. To persist the rewrite, follow up with PATCH /api/automations/:id including "script": <rewritten> and (optionally) "version_source": "bs_compat_rewrite" so the entry shows up in version history with that tag.

Trigger an on-demand run of an automation. The run is queued and executed asynchronously. Poll GET /api/automations/runs or use the returned run ID to check status.

Request Body

Response

{
  "run_id": "uuid",
  "automation_id": "uuid",
  "status": "queued",
  "device": "desktop",
  "queued_at": "2026-03-21T14:30:00Z"
}

Notes

• Self-healing locators (automatic). Every Node Playwright run is wrapped so that when a locator action (click, fill, press, hover, etc.) times out, the runner captures the page's interactive DOM, asks Claude for a better CSS selector, and retries the same action once with the replacement. The healing happens in the Node test worker on our runner — no secrets leak to the browser. Applies to both local and BrowserStack runs. Healing events are surfaced in the run's stdout as [bugAgent] self-healed locator: "<original>" → "<replacement>". Assertions (expect().toBeVisible() etc.) are not healed — a failed assertion still fails the test.
• Pre-auth (if configured on the automation) runs before the test. See PATCH /automations/:id for details.

List automation runs for the user's active team. Filter by automation ID or status. Returns run results including duration, pass/fail status, and any error output. For Live (BrowserStack) runs, video_url points at our re-hosted copy of the BS session video (Supabase Storage, no BrowserStack login required) and results.trace_url points at the Playwright trace .zip; open the latter in https://trace.playwright.dev/?trace=<url> for a full DOM-timeline replay.

Query Parameters

Response

{
  "runs": [
    {
      "id": "uuid",
      "automation_id": "uuid",
      "automation_name": "Login flow smoke test",
      "status": "passed",
      "duration_ms": 4200,
      "started_at": "2026-03-21T09:00:00Z",
      "finished_at": "2026-03-21T09:00:04Z",
      "error": null,
      "video_url": "https://storage.bugagent.com/runs/uuid/bs-session.mp4",
      "script_version_label": "current",
      "script_version_source": "current",
      "script_snapshot": "// full Playwright source the runner executed",
      "results": {
        "trace_url": "https://storage.bugagent.com/runs/uuid/trace.zip"
      }
    },
    {
      "id": "uuid",
      "automation_id": "uuid",
      "automation_name": "Checkout flow",
      "status": "failed",
      "duration_ms": 8500,
      "started_at": "2026-03-21T09:00:00Z",
      "finished_at": "2026-03-21T09:00:08Z",
      "error": "Timeout waiting for selector '#confirm-btn'",
      "video_url": "https://storage.bugagent.com/runs/uuid/video.webm",
      "results": {
        "trace_url": "https://storage.bugagent.com/runs/uuid/trace.zip",
        "stdout": "...",
        "stderr": "..."
      }
    }
  ],
  "total": 42,
  "page": 1,
  "limit": 20
}

Trigger an automation run from CI/CD pipelines. Authenticates via API key instead of session token. Designed to be called from GitHub Actions, GitLab CI, or any CI/CD system. Returns immediately with a run ID for polling.

Request Body

Headers

Response

{
  "run_id": "uuid",
  "automation_id": "uuid",
  "status": "queued",
  "device": "desktop",
  "poll_url": "/api/v1/automations/runs/uuid",
  "queued_at": "2026-03-21T14:30:00Z"
}

Poll the status of a CI/CD automation run. Returns the current status, duration, and any error output. Use this to wait for completion in CI/CD scripts.

Headers

Response

{
  "id": "uuid",
  "automation_id": "uuid",
  "automation_name": "Login flow smoke test",
  "status": "passed",
  "duration_ms": 4200,
  "started_at": "2026-03-21T09:00:00Z",
  "finished_at": "2026-03-21T09:00:04Z",
  "error": null,
  "trace_url": "https://bugagent.com/traces/uuid",
  "screenshots": [
    { "step": "login-success", "url": "https://storage.bugagent.com/screenshots/uuid.png" }
  ]
}

Initiate the GitHub OAuth flow. Returns a redirect URL that opens the GitHub authorization page. Once the user authorizes, GitHub redirects back to bugAgent with an installation token. Connect from Settings → Integrations in the dashboard.

Request Body

Response

{
  "authorization_url": "https://github.com/login/oauth/authorize?client_id=...",
  "state": "random-state-token"
}

List all GitHub repositories accessible via the connected GitHub account. Use this to select which repo to map to a bugAgent project.

Response

{
  "repos": [
    {
      "id": 123456,
      "full_name": "acme/web-app",
      "default_branch": "main",
      "private": true
    }
  ]
}

Map a bugAgent project to a GitHub repository. Once mapped, Playwright automation scripts created or updated in that project are automatically pushed to tests/bugagent/{name}.spec.ts in the target repo. Deleting or archiving an automation removes the file from the repo.

Request Body

Response

{
  "mapping_id": "uuid",
  "project_id": "uuid",
  "repo_full_name": "acme/web-app",
  "branch": "main",
  "path_prefix": "tests/bugagent",
  "created_at": "2026-03-22T10:00:00Z"
}

Check the current GitHub connection status and project-to-repo mappings for the authenticated user's workspace. Also returns recent sync history and any SHA conflict errors.

Response

{
  "connected": true,
  "github_username": "acme-dev",
  "mappings": [
    {
      "project_id": "uuid",
      "project_name": "Web App",
      "repo_full_name": "acme/web-app",
      "branch": "main",
      "path_prefix": "tests/bugagent",
      "last_sync_at": "2026-03-22T09:45:00Z",
      "sync_status": "ok"
    }
  ]
}

Notes

• If sync_status is sha_conflict, the remote file was modified outside bugAgent. Use POST /api/github/mapping to re-map and force a fresh push, or resolve the conflict in GitHub first.
• Scripts are pushed to {path_prefix}/{automation-name}.spec.ts using the GitHub Contents API.

Disconnect the GitHub integration. Removes the OAuth token and all project-to-repo mappings. Scripts already pushed to GitHub are not deleted.

Response

{
  "disconnected": true
}

List notes for the authenticated user's team. Returns notes the user owns or notes with shared visibility. Supports keyword search, project filtering, author filtering, and date range filtering.

Query Parameters

Response

{
  "notes": [
    {
      "id": "uuid",
      "title": "Checkout flow observations",
      "format": "markdown",
      "visibility": "shared",
      "project_id": "uuid",
      "author_id": "uuid",
      "author_name": "Jane Smith",
      "time_spent_seconds": 1820,
      "attachments_count": 2,
      "created_at": "2026-03-22T10:00:00Z",
      "updated_at": "2026-03-22T10:30:00Z"
    }
  ],
  "total": 42,
  "page": 1,
  "per_page": 20
}

Create a new note. If no title is provided, the first 30 characters of the content are used as the auto-title. Notes auto-save as you type in the dashboard, but this endpoint creates the initial note record.

Request Body

Response

{
  "id": "uuid",
  "title": "Checkout flow observations",
  "content": "## Session 1\n- Payment form loads slowly...",
  "format": "markdown",
  "visibility": "private",
  "project_id": "uuid",
  "author_id": "uuid",
  "time_spent_seconds": 0,
  "attachments": [],
  "created_at": "2026-03-22T10:00:00Z",
  "updated_at": "2026-03-22T10:00:00Z"
}

Get full details of a single note including content and attachments. Returns the note only if the user is the author or the note has shared visibility within the same team.

Response

{
  "id": "uuid",
  "title": "Checkout flow observations",
  "content": "## Session 1\n- Payment form loads slowly on 3G...",
  "format": "markdown",
  "visibility": "shared",
  "project_id": "uuid",
  "author_id": "uuid",
  "author_name": "Jane Smith",
  "time_spent_seconds": 1820,
  "attachments": [
    {
      "id": "uuid",
      "filename": "screenshot.png",
      "size_bytes": 245000,
      "mime_type": "image/png",
      "url": "https://storage.bugagent.com/notes/uuid/screenshot.png"
    }
  ],
  "created_at": "2026-03-22T10:00:00Z",
  "updated_at": "2026-03-22T10:30:00Z"
}

Update an existing note. Only provided fields are changed. Only the note author can update a note. The dashboard uses this endpoint for auto-save (triggered on content changes) and manual save (Save button or Cmd/Ctrl+S).

Request Body

Response

{
  "id": "uuid",
  "title": "Checkout flow observations (updated)",
  "content": "...",
  "format": "markdown",
  "visibility": "shared",
  "time_spent_seconds": 2400,
  "updated_at": "2026-03-22T11:00:00Z"
}

Permanently delete a note and all its attachments. Only the note author can delete a note. This action cannot be undone.

Response

{ "deleted": true }

Upload a file attachment to a note. Files are stored in Supabase Storage and linked to the note. Accepts any image, video, audio, PDF, or text/JSON file up to 400 MB per file — the same policy as bug report attachments.

Request Body (multipart/form-data)

Response

{
  "id": "uuid",
  "note_id": "uuid",
  "filename": "walkthrough.mp4",
  "size_bytes": 52428800,
  "mime_type": "video/mp4",
  "url": "https://storage.bugagent.com/notes/uuid/walkthrough.mp4"
}

Notes

• Accepted MIME types: any image/* (png, jpeg, gif, webp, heic, avif, svg), any video/* (mp4, webm, quicktime, mpeg), any audio/* (mp3, wav, m4a, ogg, webm), application/pdf, text/plain, text/csv, text/markdown, application/json.
• Maximum file size: 400 MB per file. Large screen recordings and audio memos are supported.
• Files are stored in the team's Supabase Storage bucket and served via signed URLs.

List time tracking entries for the authenticated user's team. Supports filtering by time period, project, and category.

Query Parameters

Response

{
  "entries": [
    {
      "id": "uuid",
      "description": "Regression testing checkout flow",
      "category": "testing",
      "duration_minutes": 45,
      "project_id": "uuid",
      "entry_date": "2026-03-22",
      "user_id": "uuid",
      "created_at": "2026-03-22T10:00:00Z",
      "updated_at": "2026-03-22T10:00:00Z"
    }
  ],
  "count": 1
}

Create a new time tracking entry. Log hours spent on QA tasks with categories for team reporting and analytics.

Request Body

Response

{
  "id": "uuid",
  "description": "Regression testing checkout flow",
  "category": "testing",
  "duration_minutes": 45,
  "project_id": "uuid",
  "entry_date": "2026-03-22",
  "created_at": "2026-03-22T10:00:00Z"
}

Update an existing time tracking entry. Only provided fields are changed.

Request Body

Response

{
  "id": "uuid",
  "description": "Regression testing checkout flow (updated)",
  "category": "testing",
  "duration_minutes": 60,
  "project_id": "uuid",
  "entry_date": "2026-03-22",
  "updated_at": "2026-03-22T11:00:00Z"
}

Delete a time tracking entry. This action cannot be undone.

Response

{ "deleted": true }

Notes

• Time Tracking is a Team plan feature. Free and Pro plan users receive a 403 Forbidden response.
• Entries are scoped to the authenticated user's team. All team members can view entries; only the entry creator or team admins can update or delete.

List the caller's CoPilot resources (recording action logs + generated Playwright scripts) in the requested workspace, optionally narrowed to a project. Returns full resource bodies so a client can mirror them locally without a follow-up request.

Query Parameters

Response

{
  "resources": [
    {
      "id": "uuid",
      "owner_id": "uuid",
      "team_id": "uuid",
      "project_id": "uuid",
      "kind": "recording",
      "name": "Recording · Apr 22, 3:45pm",
      "duration_ms": 42300,
      "options": { "actions": true, "playwright": true, "video": false },
      "actions": [ { "type": "click", "target": { ... }, "timestamp": 1200 } ],
      "playwright": "import { test, expect } from '@playwright/test';\n\ntest('...')",
      "stats": { "actionCount": 18, "pageCount": 3 },
      "pages": ["https://example.com/login", "https://example.com/dashboard"],
      "file_path": null,
      "file_size_bytes": null,
      "file_mime_type": null,
      "client_id": "7",
      "created_at": "2026-04-22T19:45:00Z",
      "updated_at": "2026-04-22T19:47:22Z"
    }
  ],
  "server_time": "2026-04-22T19:50:10Z"
}

Create a new resource for the caller. If client_id is provided and a row with the same (owner_id, client_id) already exists, the existing row is updated instead of a duplicate being inserted — this makes retries idempotent for the Chrome extension's push pipeline.

Request Body

Response

{
  "resource": { /* same shape as GET /api/resources */ },
  "deduped": true   // only present when matched on client_id and updated
}

Fetch a single resource by id. Returns 404 if the resource does not exist or belongs to a different user.

Update whitelisted fields of a resource. Owner-only. Immutable: owner_id, team_id, created_at, client_id.

Request Body (any subset)

Delete a resource. Owner-only. Also removes any associated file in the user-resources storage bucket.

Send a message to the AI Assistant. The assistant is context-aware — it has access to your workspace's bug data, projects, Jira connection status, custom AI instructions, and uploaded knowledge documents (product specs, testing playbooks, etc.). It can answer questions about your bugs, suggest testing strategies, and guide you through creating bug reports via text or voice.

Request Body

Response

The endpoint content-negotiates the response transport on the Accept header.

{"response": "You have 12 open critical bugs. The most recent is..."}

Send Accept: text/event-stream to receive a Server-Sent Events stream of Anthropic content_block_delta events as Claude generates the response. Useful for live token-by-token rendering. The buffered JSON form remains the default for any caller that doesn't request streaming.

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"You "}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"have 12 "}}

... message_stop event ends the stream

Notes

• Powered by Claude Sonnet. Responses are professional, concise, and emoji-free.
• The assistant is scoped to your current workspace's data only.
• Context-aware: automatically includes custom AI instructions and uploaded knowledge documents (product specs, testing playbooks, etc.) configured in Settings.
• Supports voice-to-text input via Whisper transcription for long recording sessions (up to 20+ minutes).
• History role values are validated server-side. Only user and assistant roles are accepted.
• Off-topic questions (politics, opinions, etc.) are politely redirected.

Create a report via the AI Assistant. Supports all 19 report types including bugs, feature requests, enhancements, technical debt, and more. This endpoint is typically called automatically when the assistant completes a guided report creation flow. It verifies team membership and project ownership before creating the report.

Request Body

Response

{
  "success": true,
  "id": "uuid",
  "title": "Login button unresponsive on mobile",
  "type": "ui",
  "severity": "high",
  "attachments_count": 2,
  "jira_key": "PROJ-42"
}

Security

• Verifies the authenticated user is a member of the current workspace before creating the report.
• Project ID is validated against the workspace. Cross-workspace report creation is blocked.
• Attachment MIME types are restricted to any image, video, audio, PDF, or text/JSON file. Max 400 MB per file.

Generate (or regenerate) the Developer Notes for a bug report. Returns a structured analysis including probable cause, affected areas, suggested fix, verification steps, and risk assessment. Stored on the bug report and auto-regenerates on creation — this endpoint exists for manual regenerate (retry, or after the user edits the description or attachments). Uses the platform Anthropic key, so no per-team Claude connection is required.

Internally runs a multi-step chain that adapts to severity. Medium/low bugs get the three-step chain: Sonnet drafts, a powerful OpenAI model (default gpt-5) critiques the draft as a skeptical peer reviewer, and Sonnet synthesizes the final notes. Critical/high bugs escalate to the five-step debate chain: after the critique, Sonnet writes a point-by-point rebuttal, then a different-model adjudicator (default claude-opus-4-5) reads the full transcript and writes the final notes with independent judgment. Each round is persisted for audit — see the Response + bug_reports column notes below.

Graceful degradation at every step: if OPENAI_API_KEY is missing or the challenger call fails the draft is used as the final answer and critique is null. If the adjudicator call fails the chain falls back to the simple synthesis path. You always get useful notes, never a hard error.

Request Body

Response

{
  "analysis": "## Probable Root Cause\n...",
  "pushed_at": "2026-03-22T14:30:00Z"
}

Response (additional fields)

Notes

• No per-team Claude connection required. The platform ANTHROPIC_API_KEY and OPENAI_API_KEY are used directly.
• Auto-fires on bug creation (via POST /ai/create-report and the failed-automation auto-bug-creation path). You only need this endpoint for manual regenerate.
• Stored on the bug record (see GET /reports/:id) as claude_analysis (final), claude_draft_analysis (pre-challenger), claude_challenger_critique (peer review), claude_challenger_model, claude_pushed_at, and claude_status (analyzing / done / failed).
• Regenerating clears dev_notes_stale (the flag that lights up the "Regenerate?" banner in the dashboard when the description or attachments have changed since the last run).
• Cost: ~3x a single-shot call (draft + critique + synthesis). Latency: ~10-15s on a fresh report. Auto-fire is fire-and-forget so this doesn't block the UI.
• Available on Pro, Team, and Enterprise plans.

Generate (or regenerate) the Likely Fix Area for a bug report — a narrow Sonnet output that points at the part of the codebase where the fix most likely belongs. Auto-fires on bug creation; this endpoint exists for the in-UI retry button and for external callers that want to regenerate. Uses the platform Anthropic key, so it does not require a per-team Claude connection. When the team has a github_connections row and the project has github_repo mapped, the output is grounded in the top keyword-matched files from that repo; otherwise it falls back to general guidance with a nudge to connect a repo. Writes the result back onto bug_reports asynchronously — the response returns 202 immediately, clients poll GET /reports/:id.

Request Body

Response

{
  "status": "analyzing"
}

Resulting fields on bug_reports

Notes

• No claude_connections row is required. The endpoint uses ANTHROPIC_API_KEY on the platform side.
• Auto-fires from POST /ai/create-report and from the failed-automation auto-bug-creation path. You only need to call this endpoint for manual retry / regenerate.
• Repo-grounded output requires (a) github_connections.access_token on the team and (b) github_repo on the bug's project. Without either, the output is a general-speculation fallback with a "connect a repo" suggestion in the first bullet.
• The Dashboard uses Sonnet 4 (claude-sonnet-4-20250514). Costs are on the platform, not the caller's team.
• Available on Pro, Team, and Enterprise plans (matches the Developer Notes card gating).

Submit a session recording captured by the bugAgent SDK. The SDK records the last 60 seconds of user activity — clicks, navigation, errors, and network failures — and sends the data to this endpoint. The AI then analyzes the session to help auto-draft bug reports. Available on Pro, Team, and Enterprise plans.

Request Body

Response

{
  "id": "uuid",
  "duration_ms": 58200,
  "event_count": 34,
  "created_at": "2026-03-19T14:30:00Z"
}

Notes

• Requires Pro, Team, or Enterprise plan. Free plan users receive a 403 error.
• Maximum payload size: 5 MB per session capture.
• Sessions are retained for 30 days (Pro/Team) or configurable on Enterprise.

List SDK sessions for the current workspace. Supports pagination and filtering.

Query Parameters

Response

{
  "sessions": [
    {
      "id": "uuid",
      "duration_ms": 58200,
      "event_count": 34,
      "url": "https://app.example.com/checkout",
      "report_id": null,
      "created_at": "2026-03-19T14:30:00Z"
    }
  ],
  "total": 42
}

Get full detail of a SDK session, including all recorded events. Use this to render the session timeline or feed the events into the AI for analysis.

Response

{
  "id": "uuid",
  "duration_ms": 58200,
  "event_count": 34,
  "url": "https://app.example.com/checkout",
  "environment": {"browser": "Chrome 120", "os": "macOS 15"},
  "report_id": null,
  "events": [
    {"type": "click", "timestamp": "2026-03-19T14:29:02Z", "data": {"selector": "#checkout-btn"}},
    {"type": "error", "timestamp": "2026-03-19T14:29:03Z", "data": {"message": "TypeError: Cannot read property..."}}
  ],
  "created_at": "2026-03-19T14:30:00Z"
}

Attach a SDK session to an existing bug report. This links the session data to the report so reviewers can see what the user did in the 60 seconds before the bug was filed.

Request Body

Response

{
  "success": true,
  "session_id": "uuid",
  "report_id": "uuid"
}

Notes

• Both the session and the report must belong to the same workspace.
• A session can only be attached to one report. Re-attaching overwrites the previous link.

Instantly scale your QA team with booster testers. Accounts are provisioned automatically with tester access. Pro and Team plans only. Free plan returns 403. You will not be charged until approval has been given.

Request Body

Response

{ "success": true, "created": 5 }

Error Responses

{ "error": "Team Booster is available on Pro and Team plans only." }

List all changelog entries, most recent first. Also available as an RSS feed.

Response

{
  "entries": [
    {
      "id": "uuid",
      "title": "REST API parity with MCP tools",
      "summary": "Added 12 new REST API endpoints...",
      "content": "Detailed markdown content...",
      "tags": ["api", "new-feature"],
      "published_at": "2026-03-17T12:46:28Z"
    },
    ...
  ]
}

List test cases for the authenticated user's team. Supports search, filtering by priority, type, and status, sorting, and pagination.

Query Parameters

Response

{
  "cases": [
    {
      "id": "uuid",
      "name": "Verify checkout with discount code",
      "description": "Ensure discount codes apply correctly",
      "priority": "high",
      "type": "functional",
      "status": "active",
      "tags": ["checkout", "discounts"],
      "estimated_time": 300,
      "steps_count": 5,
      "project_id": "uuid",
      "created_at": "2026-03-25T10:00:00Z",
      "updated_at": "2026-03-25T10:00:00Z"
    }
  ],
  "total": 42,
  "page": 1,
  "per_page": 20
}

Create a new test case. Two template variants: steps (default) — per-step Action + Expected Result grid (pass steps); text — single free-form description of the steps (pass text_content). Both columns can be sent in the same call; the row stores them independently so a tester switching templates later doesn't lose either side's data.

Request Body

Response

{
  "id": "uuid",
  "name": "Verify checkout with discount code",
  "description": "Ensure discount codes apply correctly",
  "preconditions": "User is logged in with items in cart",
  "steps": [
    { "order": 1, "action": "Navigate to cart", "expected": "Cart page loads with items" },
    { "order": 2, "action": "Enter code SAVE20", "expected": "20% discount applied" },
    { "order": 3, "action": "Click checkout", "expected": "Order total reflects discount" }
  ],
  "priority": "high",
  "type": "functional",
  "status": "active",
  "tags": ["checkout", "discounts"],
  "estimated_time": 300,
  "project_id": "uuid",
  "created_at": "2026-03-25T10:00:00Z",
  "updated_at": "2026-03-25T10:00:00Z"
}

Upload an attachment file to a test case. Multipart/form-data with a single file field per request. Stored in the test-case-attachments Supabase Storage bucket; metadata appended to the case's attachments jsonb column.

Constraints

• Max 10 attachments per case (per-case cap, enforced server-side).
• Max 256 MB per file (per-file cap, enforced both by the API and the storage bucket).
• Allowed MIME types: image (png/jpeg/gif/webp/svg/heic/avif), application/pdf, doc/docx, xls/xlsx/csv, OpenDocument text/spreadsheet, text/plain, text/markdown, video (mp4/webm/quicktime/avi), audio (mp3/wav/ogg/webm/m4a/mp4).

Response

{ "attachment": { "id": "uuid", "filename": "shot.png", "mime_type": "image/png", "size": 12345, "storage_path": "team_id/case_id/file_id_shot.png", "public_url": "https://.../storage/v1/object/public/test-case-attachments/...", "uploaded_at": "...", "uploaded_by": "user_id" }, "attachments_count": 1 }

Remove an attachment from a test case. Deletes the file from storage AND strips the row out of the attachments jsonb. Storage delete runs first; if it fails (other than "not found"), metadata is left in place so the user can retry.

Response

{ "removed": "attachment_id", "attachments_count": 0 }

Get a test case by ID with its full steps and execution history.

Response

{
  "id": "uuid",
  "name": "Verify checkout with discount code",
  "description": "Ensure discount codes apply correctly",
  "preconditions": "User is logged in with items in cart",
  "steps": [
    { "order": 1, "action": "Navigate to cart", "expected": "Cart page loads with items" },
    { "order": 2, "action": "Enter code SAVE20", "expected": "20% discount applied" }
  ],
  "priority": "high",
  "type": "functional",
  "status": "active",
  "tags": ["checkout", "discounts"],
  "estimated_time": 300,
  "project_id": "uuid",
  "history": [
    { "run_id": "uuid", "run_name": "Sprint 12 Regression", "status": "passed", "executed_at": "2026-03-24T14:00:00Z" }
  ],
  "created_at": "2026-03-25T10:00:00Z",
  "updated_at": "2026-03-25T10:00:00Z"
}

Update any field of a test case. Only provided fields are changed.

Request Body

Response

{ "id": "uuid", "name": "Updated name", ... }

Permanently delete a test case. Removes it from all suites.

Response

{ "success": true }

Duplicate an existing test case including all steps, tags, and metadata. The copy is created with the name prefix "[Copy]".

Request Body

Response

{ "id": "uuid", "name": "[Copy] Verify checkout with discount code", ... }

Apply one action to up to 500 test cases at once. IDs not in the caller's team are silently skipped (counted in the skipped response field). Used by the bulk toolbar on the Cases tab and the bulk_update_test_cases MCP tool.

Request Body

Response

{ "applied": 47, "skipped": 3, "errors": [] }

List traceability links on a single test case — bug reports the case verifies, covers, or relates to. Established via link_test_case_to_bug (MCP) or the Links tab on the case detail page.

Response

{
  "links": [
    {
      "id": "uuid",
      "linked_type": "bug_report",
      "linked_id": "uuid",
      "relation": "verified_by",   // "verified_by" | "covers" | "relates"
      "created_at": "..."
    }
  ],
  "total": 1
}

Informational list of test cases the system flags as archive candidates. Computed by the find_dead_test_cases RPC; the same flags are persisted onto test_cases.review_flag every Monday at 09:00 UTC by pg_cron. Drives the "Archive candidates" section on the Reports tab.

Response

{
  "never_run":      [ { "id": "uuid", "name": "...", "reason": "no runs in 90+ days since creation" } ],
  "always_passes":  [ { "id": "uuid", "name": "...", "reason": "5+ runs in last 90d, all passed" } ],
  "always_skipped": [ { "id": "uuid", "name": "...", "reason": "3+ runs in last 90d, all skipped" } ],
  "total": 12
}

Step 1 of the Figma zip import flow. Validates inputs, (optionally) creates a new folder, inserts a figma_import_jobs row with status uploading, and returns a signed upload URL the client PUTs the zip to directly. Max 100 MB. Uses the platform Anthropic key server-side — no per-team Claude connection is required.

Request Body

{
  "project_id": "uuid | null",
  "folder_id": "uuid | null",          // pick existing
  "new_folder_name": "string | null",  // or create one
  "project_context": "string",         // up to 2000 chars
  "depth": "quick | thorough",
  "file_name": "designs.zip",
  "file_size_bytes": 11345678
}

Response

{
  "job_id": "uuid",
  "folder_id": "uuid | null",
  "upload": { "path": "...", "token": "...", "signed_url": "https://..." }
}

Step 2 of the Figma zip import flow. Call after the zip has finished uploading to the signed URL from /request. Verifies the object landed in Storage, flips the job to processing, and signals the MCP worker to begin analysis. Returns 202 Accepted immediately — processing runs asynchronously; poll GET /api/test-cases/import/figma/:id for progress.

Request Body

{ "job_id": "uuid" }

Response

{ "ok": true, "job_id": "uuid" }

Poll the status of a Figma import job. Clients call this every 2 s while the modal progress bar is open. Scoped to the caller's team; returns 403 for other teams' jobs.

Response

{
  "job": {
    "id": "uuid",
    "status": "queued | uploading | processing | completed | failed | cancelled",
    "progress_phase": "classifying",
    "progress_current": 7,
    "progress_total": 12,
    "progress_message": "Classifying 12 unique frames",
    "total_frames": 34,
    "unique_frames": 12,
    "test_cases_created": 0,
    "cost_cents": 0,
    "error": null,
    "file_name": "designs.zip",
    "started_at": "2026-04-20T20:15:00Z",
    "completed_at": null,
    "created_at": "2026-04-20T20:14:48Z"
  }
}

List test suites for the authenticated user's team. Returns each suite with its case count and last run status.

Query Parameters

Response

{
  "suites": [
    {
      "id": "uuid",
      "name": "Checkout Regression Suite",
      "description": "All checkout-related test cases",
      "case_count": 12,
      "last_run_status": "passed",
      "project_id": "uuid",
      "created_at": "2026-03-25T10:00:00Z"
    }
  ],
  "total": 8
}

Create a new test suite to group related test cases.

Request Body

Response

{
  "id": "uuid",
  "name": "Checkout Regression Suite",
  "description": "All checkout-related test cases",
  "case_count": 0,
  "project_id": "uuid",
  "project_slug": "checkout-team",
  "created_at": "2026-03-25T10:00:00Z"
}

Get a test suite by ID with its full list of cases in order.

Query Parameters

Response

{
  "id": "uuid",
  "name": "Checkout Regression Suite",
  "description": "All checkout-related test cases",
  "cases": [
    { "id": "uuid", "name": "Verify checkout with discount code", "priority": "high", "type": "functional", "order": 1 }
  ],
  "project_id": "uuid",
  "created_at": "2026-03-25T10:00:00Z"
}

Update a test suite's name or description.

Request Body

Response

{ "id": "uuid", "name": "Updated Suite Name", ... }

Delete a test suite. Test cases within the suite are not deleted.

Response

{ "success": true }

Add one or more test cases to a suite.

Request Body

Response

{ "added": 3, "case_count": 15 }

Remove a test case from a suite.

Request Body

Response

{ "success": true, "case_count": 14 }

Reorder the test cases within a suite. Provide the full ordered list of case IDs.

Request Body

Response

{ "success": true }

Reorder sibling test suites under a shared parent (or root-level suites). Used by the drag-and-drop reorder in the Suites tab tree. All suites in the request must belong to the same parent — cross-parent reorders are rejected with HTTP 400.

Request Body

Response

{ "success": true, "count": 5 }

List folders for the authenticated team. Folders organize test cases hierarchically (one folder per case via folder_id) and are distinct from suites, which are many-to-many test plan groupings. Returns the full set (capped at 500) since folder trees are usually small and the entire tree is needed to render correctly.

Query Parameters

Response

{
  "test_case_folders": [
    {
      "id": "uuid",
      "name": "Smoke Tests",
      "description": "",
      "parent_folder_id": null,
      "depth": 0,
      "sort_order": 0,
      "project_id": "uuid",
      "case_count": 12,
      "created_at": "2026-04-19T...",
      "updated_at": "2026-04-19T..."
    }
  ],
  "total": 1
}

Create a new folder. Pass parent_folder_id to nest it; folders can nest up to 3 levels deep.

Request Body

Reorder sibling folders under a shared parent (or root-level folders). Used by the drag-and-drop reorder in the Cases-tab folder sidebar. Mirrors /api/test-suites/reorder — same validation, same shape, against the folder table instead.

Request Body

Response

{ "success": true, "count": 5 }

List test runs for the authenticated user's team. Returns each run with suite name, assignee, and pass/fail summary.

Query Parameters

Response

{
  "runs": [
    {
      "id": "uuid",
      "name": "Sprint 12 Regression",
      "suite_id": "uuid",
      "suite_name": "Checkout Regression Suite",
      "status": "in_progress",
      "assigned_to": "uuid",
      "assignee_name": "Jane Smith",
      "summary": { "total": 12, "passed": 8, "failed": 2, "blocked": 1, "skipped": 0, "untested": 1 },
      "created_at": "2026-03-25T10:00:00Z"
    }
  ],
  "total": 5
}

Create a new test run from a test suite. Snapshots all cases at creation time. If the suite has sub-suites, every descendant sub-suite's cases are included too — running a parent suite executes its whole subtree. Each case is added exactly once (parent suite wins if a case is linked to both a parent and a sub-suite) and each row in the resulting test_run_results records which sub-suite it came from.

If any cases have a per-case assignee, an in-app bell notification AND a digest email are sent to each assignee. Emails respect the per-user opt-out at notification_preferences.email_test_case_assignment (default on); the in-app bell is always shown.

Request Body

Response

{
  "id": "uuid",
  "name": "Sprint 12 Regression",
  "suite_id": "uuid",
  "status": "in_progress",
  "assigned_to": "uuid",
  "results": [
    { "case_id": "uuid", "case_name": "Verify checkout with discount code", "status": "untested" }
  ],
  "created_at": "2026-03-25T10:00:00Z"
}

Get a test run by ID with all case results. Each entry in results[] includes suite_id and case_suite_name identifying the sub-suite the case was pulled from at run-creation time — useful for grouping results by origin on a run-detail page.

Response

{
  "id": "uuid",
  "name": "Sprint 12 Regression",
  "suite_id": "uuid",
  "suite_name": "Checkout Regression Suite",
  "status": "in_progress",
  "assigned_to": "uuid",
  "assignee_name": "Jane Smith",
  "results": [
    {
      "case_id": "uuid",
      "case_name": "Verify checkout with discount code",
      "status": "passed",
      "actual_result": "Discount applied correctly",
      "notes": "",
      "executed_at": "2026-03-25T11:00:00Z"
    }
  ],
  "summary": { "total": 12, "passed": 8, "failed": 2, "blocked": 1, "skipped": 0, "untested": 1 },
  "created_at": "2026-03-25T10:00:00Z"
}

Update a test run's name, assignee, or status.

Request Body

Response

{ "id": "uuid", "name": "Updated Run Name", ... }

Save the execution result for a specific test case in a run. Mark each case as passed, failed, blocked, or skipped.

Request Body

Response

{ "success": true, "status": "failed", "case_id": "uuid", "notes": "..." }

Reassign a single test case inside an active run. Updates test_run_results.assigned_to for the matching case_id. When the new assignee is a real user and differs from the previous one, the recipient gets a bell-icon message and an email notification. Re-saving the same assignee or unassigning (null) is silent.

Request Body

Response

{ "success": true, "case_id": "uuid", "assigned_to": "uuid-or-null" }

Attach screenshots, screen recordings, or other evidence files to a single test case during run execution. Files are stored in the team's bug-attachments bucket and the metadata is appended to test_run_results.attachments (jsonb). The result row must already exist (the case has been marked passed/failed/blocked/skipped) — the endpoint returns 409 if it doesn't.

Request

Multipart form data:

Response

{
  "success": true,
  "attachments": [
    {
      "id": "uuid",
      "storage_path": "team-id/test-runs/run-id/case-id/uuid_screenshot.png",
      "filename": "screenshot.png",
      "url": "https://....supabase.co/storage/v1/.../screenshot.png",
      "type": "image",
      "mimeType": "image/png",
      "size": 86552,
      "uploaded_at": "2026-05-09T14:00:00Z",
      "uploaded_by": "user-uuid"
    }
  ],
  "added": [ /* just the new attachments from this request */ ]
}

Remove a single attachment from a test case result. Deletes both the file in storage and the metadata entry. Returns the updated attachments list.

Request Body

Response

{ "success": true, "attachments": [ /* remaining attachments */ ] }

Mark a test run as completed. Calculates and stores the final pass rate.

Response

{
  "id": "uuid",
  "status": "completed",
  "summary": { "total": 12, "passed": 10, "failed": 2, "blocked": 0, "skipped": 0, "untested": 0 },
  "pass_rate": 83.3,
  "completed_at": "2026-03-25T15:00:00Z"
}

Create a new test run containing only the failed cases from a completed run. Useful for re-testing after fixes.

Response

{
  "id": "uuid",
  "name": "Re-run: Sprint 12 Regression (failed)",
  "suite_id": "uuid",
  "status": "in_progress",
  "results": [
    { "case_id": "uuid", "case_name": "Apply expired discount code", "status": "untested" }
  ],
  "created_at": "2026-03-25T16:00:00Z"
}

Get completed test run reports with pass rate and date range filtering. Returns aggregated test execution data.

Query Parameters

Response

{
  "reports": [
    {
      "run_id": "uuid",
      "run_name": "Sprint 12 Regression",
      "suite_name": "Checkout Regression Suite",
      "status": "completed",
      "pass_rate": 83.3,
      "summary": { "total": 12, "passed": 10, "failed": 2, "blocked": 0, "skipped": 0 },
      "completed_at": "2026-03-25T15:00:00Z"
    }
  ],
  "total": 15,
  "average_pass_rate": 87.5
}

Aggregated quality KPIs + a weekly pass-rate trend for the Reports tab. Returns the current-period totals AND the prior equivalent-length period so the UI can render delta arrows.

Query Parameters

Response

{
  "range": { "from": "...", "to": "...", "previous_from": "...", "previous_to": "..." },
  "kpis": {
    "pass_rate":                { "current": 82, "previous": 78, "delta": 4 },
    "runs_completed":           { "current": 12, "previous": 8,  "delta": 4 },
    "avg_run_duration_seconds": { "current": 1840, "previous": 2100, "delta": -260 },
    "cases_executed":           { "current": 245, "previous": 198, "delta": 47 }
  },
  "trend": {
    "buckets": ["2026-04-06", "2026-04-13", "2026-04-20"],
    "pass_rate":      [78, 80, 82],
    "runs":           [3, 4, 5],
    "cases_executed": [50, 65, 70]
  },
  "capped": false
}

Failure analysis for the Reports tab — four parallel "what to fix this week?" lists.

• flaky_cases — cases that flip between pass/fail in the period (sorted by flip count)
• failing_cases — pass rate < 50% with at least 3 runs (noise filter)
• failing_suites — same logic at suite level via test_run_results.suite_id
• regressed_cases — most-recent execution failed but the period contained an earlier pass

Query Parameters

Response

{
  "flaky_cases": [
    { "id": "uuid", "name": "Login redirects to dashboard",
      "suite_name": "Auth", "flips": 4,
      "pass_count": 3, "fail_count": 5, "total_runs": 8 }
  ],
  "failing_cases": [
    { "id": "uuid", "name": "Coupon stacks past expiry",
      "suite_name": "Billing/Checkout", "fail_rate": 67,
      "fail_count": 4, "total_runs": 6, "last_failed_at": "..." }
  ],
  "failing_suites": [
    { "id": "uuid", "name": "Billing", "fail_rate": 32,
      "fail_count": 11, "total_runs": 34 }
  ],
  "regressed_cases": [
    { "id": "uuid", "name": "...", "suite_name": "...",
      "last_failed_at": "...",
      "pass_count": 2, "fail_count": 1, "total_runs": 3 }
  ]
}

One row per suite that had activity in the period, with the metrics needed to spot "where's the rot?" at a glance: pass rate (current + previous), trend ▲▼→, runs completed, cases executed, last run, and open bug count. Suites are sorted worst-pass-rate first so the most-broken suite is at the top. Idle suites (no runs in the current period) are excluded.

Query Parameters

Response

{
  "suites": [
    {
      "id": "uuid",
      "name": "Billing",
      "depth": 0,
      "parent_suite_id": null,
      "pass_rate": 71,
      "pass_rate_previous": 84,
      "trend": "down",                  // up | down | flat | new
      "runs_completed": 8,
      "cases_executed": 96,
      "fail_count": 28,
      "last_run_at": "2026-04-20T...",
      "open_bugs": 4
    }
  ]
}

Notes

• Suite attribution uses test_run_results.suite_id (added in migration 106), which records the originating sub-suite per result — exact, not a lossy join through test_suite_cases.
• Trend compares the current pass rate to the same metric over the prior equivalent-length window. up / down require a ±3% change; smaller deltas are flat. new means the suite had no runs in the prior window.
• Open bugs are bug_reports linked from any result in the period whose status is not closed or resolved.

Catalog hygiene report. Answers "what have I NOT been testing?" via three coordinated views: workspace-level KPIs, a staleness distribution across six time buckets, and a per-suite coverage rollup. Idle suites and deprecated cases are excluded.

Query Parameters

Response

{
  "range": { "from": "...", "to": "..." },
  "kpis": {
    "total_active_cases": 250,
    "covered_cases": 195,           // ≥1 execution in [from,to]
    "coverage_pct": 78,
    "untouched_in_period": 55,
    "never_run": 12                 // no execution EVER, not just in period
  },
  "buckets": [
    { "label": "Never run",            "key": "never", "count": 12 },
    { "label": "Last 7 days",          "key": "lt7",   "count": 120 },
    { "label": "8–30 days ago",        "key": "lt30",  "count": 75 },
    { "label": "31–90 days ago",       "key": "lt90",  "count": 27 },
    { "label": "91–180 days ago",      "key": "lt180", "count": 10 },
    { "label": "Older than 180 days",  "key": "gt180", "count": 6 }
  ],
  "suite_coverage": [
    {
      "id": "uuid",
      "name": "Billing/Checkout",
      "depth": 1,
      "total_cases": 18,
      "covered_cases": 4,
      "coverage_pct": 22,
      "stale_count": 14,
      "last_activity_at": "..."
    }
  ]
}

Definitions

• Active = test_cases.status = 'active'. Drafts (work in progress) and deprecated (intentionally retired) cases are excluded.
• Covered in period = at least one test_run_results row with executed_at in [from, to] and status not untested.
• Never run = no test_run_results row in the entire history (catalog hygiene metric, not period-scoped).
• Bucket order: rows are evaluated in array order, first match wins — so the never bucket is checked before any numeric range.
• suite_coverage uses cases linked to the suite via test_suite_cases (the test-plan relationship), not test_cases.folder_id (the organizational hierarchy). A case can appear under multiple suites; it counts once per suite. Sorted by coverage_pct ascending; capped at 25 entries.

Per-tester rollup useful for capacity planning, bottleneck detection, and bug-finding effectiveness. Sorted by cases_executed descending. A user shows up if either they appear as test_run_results.tester_id in the period or they were assigned a run created in the period (so a tester with zero executions but assigned work still surfaces — that's the bottleneck signal).

Query Parameters

Response

{
  "range": { "from": "...", "to": "..." },
  "totals": {
    "active_testers": 5,            // testers with ≥1 execution
    "cases_executed": 450,
    "bugs_filed": 12                // distinct bugs linked from results
  },
  "testers": [
    {
      "id": "uuid",
      "name": "Jason H.",
      "email": "jason@...",
      "cases_executed": 145,
      "passed": 120, "failed": 18, "blocked": 4, "skipped": 3,
      "pass_rate": 83,                  // INFORMATIONAL — see notes
      "avg_duration_seconds": 240,
      "runs_assigned": 8,
      "runs_assigned_completed": 6,
      "bugs_filed": 4,
      "last_active_at": "..."
    }
  ]
}

Definitions & caveats

• cases_executed = test_run_results with this tester_id, executed in [from, to], status not untested.
• avg_duration_seconds excludes any per-case duration above 24h to defend against forgotten timers skewing the average. Result rows with no recorded duration are omitted from the average entirely (not counted as zero).
• runs_assigned = test_runs with assigned_to = this user AND created_at in the period. runs_assigned_completed = those whose status is completed.
• bugs_filed counts only bug reports linked from results this tester executed (test_run_results.bug_report_id). Standalone bug reports filed outside test runs (Bugs tab, MCP, browser extension) are NOT counted — this metric is about testing output, not bug filing in general.
• pass_rate per tester is informational only. It mostly reflects which cases that tester was assigned. Treat it as a secondary signal, not a quality leaderboard.
• Capped at 50 testers; results with no tester_id attribution are excluded.

One-click PDF export of the QA Reports dashboard, suitable for stakeholder distribution. Renders a 3-page brand-styled report covering the most important sections: at-a-glance KPIs & trend, what-to-fix (failing / flaky / regressed cases), and per-suite + per-tester rollups.

Query Parameters

Response

A PDF binary with Content-Type: application/pdf and a Content-Disposition: attachment header. The filename includes the date range so saved files stay self-describing: bugagent-qa-report-2026-03-21_2026-04-20.pdf.

Page contents

• Page 1 — At a glance: 4 KPI tiles (pass rate / runs / avg duration / cases executed) with deltas vs the prior equivalent-length window, a pass-rate trend line chart, and a coverage summary (KPIs + staleness distribution bar).
• Page 2 — What to fix: top 5 failing cases (≥50% fail rate), top 5 flaky cases (most pass↔fail flips), top 5 recently regressed cases.
• Page 3 — By suite + by tester: top 12 suites by health (worst pass rate first), top 10 testers by cases run.

List saved Geo-Snap screenshots. Filter by country, search by URL, and paginate results.

Query Parameters

Response

{
  "snaps": [
    {
      "id": "uuid",
      "url": "https://example.com",
      "country": "US",
      "screenshot_url": "https://storage.bugagent.com/geo-snaps/uuid-us.png",
      "status": "completed",
      "created_at": "2026-03-25T10:00:00Z"
    }
  ],
  "total": 15,
  "page": 1,
  "per_page": 20
}

Capture screenshots of a URL from one or more countries. Free plan: 1 country per request, 10 saved screenshots. Pro/Team: up to 5 countries per request, unlimited saved screenshots.

Request Body

Response

{
  "snaps": [
    {
      "id": "uuid",
      "url": "https://example.com",
      "country": "US",
      "screenshot_url": "https://storage.bugagent.com/geo-snaps/uuid-us.png",
      "status": "completed",
      "created_at": "2026-03-25T10:00:00Z"
    },
    {
      "id": "uuid",
      "url": "https://example.com",
      "country": "DE",
      "screenshot_url": "https://storage.bugagent.com/geo-snaps/uuid-de.png",
      "status": "completed",
      "created_at": "2026-03-25T10:00:00Z"
    }
  ]
}

Delete a saved Geo-Snap screenshot by ID.

Path Parameters

Response

{ "deleted": true }

List uploaded mobile apps. Filter by platform, search by name, and paginate results.

Query Parameters

Response

{
  "apps": [
    {
      "id": "uuid",
      "name": "MyApp",
      "platform": "android",
      "package_name": "com.example.myapp",
      "version": "2.1.0",
      "file_url": "https://storage.bugagent.com/apps/uuid.apk",
      "file_size": 48500000,
      "automation_count": 3,
      "created_at": "2026-03-20T10:00:00Z"
    }
  ],
  "total": 1
}

Upload an APK (Android) or IPA (iOS) app binary. Uses multipart/form-data. Max file size: 500 MB.

Request Body (multipart/form-data)

Response

{
  "id": "uuid",
  "name": "MyApp",
  "platform": "android",
  "package_name": "com.example.myapp",
  "version": "2.1.0",
  "file_url": "https://storage.bugagent.com/apps/uuid.apk",
  "file_size": 48500000,
  "created_at": "2026-03-20T10:00:00Z"
}

Get full details for a mobile app, including automation count.

Path Parameters

Response

{
  "id": "uuid",
  "name": "MyApp",
  "platform": "android",
  "package_name": "com.example.myapp",
  "version": "2.1.0",
  "file_url": "https://storage.bugagent.com/apps/uuid.apk",
  "file_size": 48500000,
  "automation_count": 3,
  "created_at": "2026-03-20T10:00:00Z",
  "updated_at": "2026-03-20T10:00:00Z"
}

Update an uploaded mobile app's metadata.

Path Parameters

Request Body

Response

{
  "id": "uuid",
  "name": "MyApp",
  "platform": "android",
  "package_name": "com.example.myapp",
  "version": "2.1.0",
  "file_url": "https://storage.bugagent.com/apps/uuid.apk",
  "file_size": 48500000,
  "automation_count": 3,
  "created_at": "2026-03-20T10:00:00Z",
  "updated_at": "2026-03-20T10:00:00Z"
}

Replace an app's binary with a new version. Deletes the old file from storage, clears cached platform URLs (forcing re-upload on next run), and updates the team's storage quota. All linked automations and schedules will automatically use the new version. For iOS apps, the simulator build is also removed — re-upload it to continue recording.

Path Parameters

Request Body

Response

{ "id": "uuid", "name": "My App", "platform": "android", "version": "2.0.0", "file_size": 15728640, "updated_at": "2026-03-29T..." }

Delete an uploaded mobile app and its storage file. Automations referencing this app will be orphaned.

Path Parameters

Response

{ "success": true }

List mobile automation scripts. Filter by app, script type, and status.

Query Parameters

Response

{
  "automations": [
    {
      "id": "uuid",
      "name": "Login Flow Test",
      "app_id": "uuid",
      "script_type": "maestro",
      "status": "active",
      "target_devices": [
        "Pixel 7",
        "Samsung Galaxy S23"
      ],
      "created_at": "2026-03-21T09:00:00Z"
    }
  ],
  "total": 1
}

Create a mobile automation script. Use Appium for complex cross-platform interactions or Maestro YAML for simple flows.

Request Body

Response

{
  "id": "uuid",
  "name": "Login Flow Test",
  "app_id": "uuid",
  "script_type": "maestro",
  "script": "appId: com.example.myapp\n---\n- launchApp\n- tapOn: \"Login\"\n- inputText: \"[email protected]\"",
  "status": "draft",
  "target_devices": [
    "Pixel 7",
    "Samsung Galaxy S23"
  ],
  "created_at": "2026-03-21T09:00:00Z"
}

Get full details for a mobile automation, including app info and recent runs.

Path Parameters

Response

{
  "id": "uuid",
  "name": "Login Flow Test",
  "app_id": "uuid",
  "app_name": "MyApp",
  "script_type": "maestro",
  "script": "appId: com.example.myapp\n---\n- launchApp\n- tapOn: \"Login\"",
  "status": "active",
  "target_devices": [
    "Pixel 7",
    "Samsung Galaxy S23"
  ],
  "recent_runs": [
    {
      "id": "uuid",
      "status": "passed",
      "device": "Pixel 7",
      "duration_ms": 45000,
      "created_at": "2026-03-22T08:00:00Z"
    }
  ],
  "created_at": "2026-03-21T09:00:00Z"
}

Update a mobile automation script or its metadata.

Path Parameters

Request Body

Response

{
  "id": "uuid",
  "name": "Login Flow Test",
  "app_id": "uuid",
  "app_name": "MyApp",
  "script_type": "maestro",
  "script": "appId: com.example.myapp\n---\n- launchApp\n- tapOn: \"Login\"",
  "status": "active",
  "target_devices": [
    "Pixel 7",
    "Samsung Galaxy S23"
  ],
  "recent_runs": [
    {
      "id": "uuid",
      "status": "passed",
      "device": "Pixel 7",
      "duration_ms": 45000,
      "created_at": "2026-03-22T08:00:00Z"
    }
  ],
  "created_at": "2026-03-21T09:00:00Z"
}

Delete a mobile automation. Fails if the automation has active schedules — delete schedules first.

Path Parameters

Response

{ "success": true }

List mobile test runs. Filter by automation and status.

Query Parameters

Response

{
  "runs": [
    {
      "id": "uuid",
      "automation_id": "uuid",
      "status": "passed",
      "device": "Pixel 7",
      "os_version": "14",
      "duration_ms": 45000,
      "created_at": "2026-03-22T08:00:00Z"
    }
  ],
  "total": 1
}

Trigger a mobile test run. Appium scripts are routed to BrowserStack; Maestro scripts are routed to Maestro Cloud.

Request Body

Response

{
  "id": "uuid",
  "automation_id": "uuid",
  "status": "queued",
  "device": "Pixel 7",
  "os_version": "14",
  "provider": "browserstack",
  "created_at": "2026-03-22T08:00:00Z"
}

Get full results for a mobile test run, including video recording, Appium logs, device logs, network logs, and duration.

Path Parameters

Response

{
  "id": "uuid",
  "automation_id": "uuid",
  "status": "passed",
  "device": "Pixel 7",
  "os_version": "14",
  "provider": "browserstack",
  "duration_ms": 45000,
  "video_url": "https://storage.bugagent.com/runs/uuid/video.mp4",
  "screenshots": [
    "https://storage.bugagent.com/runs/uuid/screen_001.png"
  ],
  "logs": "https://storage.bugagent.com/runs/uuid/device.log",
  "performance": {
    "cpu_avg": 23.5,
    "memory_peak_mb": 256,
    "battery_drain": 2.1,
    "fps_avg": 58.3
  },
  "created_at": "2026-03-22T08:00:00Z",
  "completed_at": "2026-03-22T08:00:45Z"
}

Archive a completed mobile test run. Archived runs are hidden from the default listing but can be viewed with the status=archived filter.

Request Body

List available BrowserStack real devices for mobile testing. Optionally filter by platform.

Query Parameters

List all web automation schedules for the team. Returns cron expression, timezone, device, notification settings, and next run time.

Create a web automation schedule. Requires automation_id and cron_expression. Optional: timezone, device (desktop, iphone-15, galaxy-s23, etc. — Virtual mode viewport emulation), notify_on_fail (none/email/slack/both), notify_email, slack_channel_id. Supports BrowserStack Live via browserstack: true + bs_browser, bs_os, bs_os_version — same matrix as POST /automations/runs: Node scripts get desktop + real Android + real iPhone; Python scripts get desktop only. See the Live-browser device list on that endpoint for device names.

List scheduled mobile test runs with cron expression, timezone, and notification settings.

Response

{
  "schedules": [
    {
      "id": "uuid",
      "automation_id": "uuid",
      "automation_name": "Login Flow Test",
      "cron_expression": "0 9 * * 1-5",
      "timezone": "America/New_York",
      "devices": [
        "Pixel 7",
        "iPhone 15 Pro"
      ],
      "notify_on_fail": "slack",
      "enabled": true,
      "next_run_at": "2026-03-23T09:00:00Z"
    }
  ],
  "total": 1
}

Create a scheduled mobile test run. Runs are dispatched to the configured devices on the cron schedule.

Request Body

Response

{
  "id": "uuid",
  "automation_id": "uuid",
  "cron_expression": "0 9 * * 1-5",
  "timezone": "America/New_York",
  "devices": [
    "Pixel 7",
    "iPhone 15 Pro"
  ],
  "notify_on_fail": "slack",
  "enabled": true,
  "next_run_at": "2026-03-23T09:00:00Z",
  "created_at": "2026-03-22T10:00:00Z"
}

Update a mobile test schedule.

Path Parameters

Request Body

Response

{
  "id": "uuid",
  "automation_id": "uuid",
  "cron_expression": "0 9 * * 1-5",
  "timezone": "America/New_York",
  "devices": [
    "Pixel 7",
    "iPhone 15 Pro"
  ],
  "notify_on_fail": "slack",
  "enabled": true,
  "next_run_at": "2026-03-23T09:00:00Z",
  "created_at": "2026-03-22T10:00:00Z"
}

Delete a mobile test schedule.

Path Parameters

Response

{ "success": true }

List all performance test configurations for the current team.

Response

{ "tests": [{ "id": "uuid", "name": "Homepage Perf", "url": "https://example.com", "device": "desktop", "virtual_users": 10, "duration": 30, "perf_threshold": 50, "auto_create_bug": true, "created_at": "..." }] }

Create a new performance test configuration. Combines page quality audits with distributed load testing. Supports mobile app profiling on real Android/iOS devices via BrowserStack. Pro/Team/Enterprise plans only.

Body Parameters

Response

{ "test": { "id": "uuid", "name": "Homepage Perf", "url": "https://example.com", ... } }

Get a single performance test configuration by ID.

Path Parameters

Update a performance test configuration. Only include fields you want to change.

Path Parameters

Body Parameters

Delete a performance test configuration and all its associated runs.

Path Parameters

Response

{ "success": true }

Trigger a performance test run (page audit + load test). The run executes asynchronously; poll GET /performance/runs/:id for results. Auto-creates a bug report when the performance score drops below the configured threshold.

Body Parameters

Response

{ "run": { "id": "uuid", "status": "running", "test_id": "uuid", "created_at": "..." } }

Get full results for a performance test run. Includes Lighthouse scores (Performance, Accessibility, Best Practices, SEO), Core Web Vitals (LCP, FID, CLS, FCP, TTFB, INP, TBT, SI), and load test metrics (VUs, total requests, RPS, p50/p90/p95/p99 latencies).

Path Parameters

Download a CSV report for a performance run. Includes Lighthouse scores, Core Web Vitals, load test summary with latency percentiles, and test metadata.

Path Parameters

Response

Returns text/csv with Content-Disposition: attachment; filename="performance-report-{id}.csv"

Archive a completed performance test run. Archived runs are hidden from the default listing but can be viewed with the status=archived filter on GET /performance/runs.

Path Parameters

Response

{ "success": true, "status": "archived" }

Unarchive a previously archived performance test run, restoring it to the default listing.

Path Parameters

Response

{ "success": true, "status": "completed" }

Check monthly performance test usage against plan limits. Limits: Free=0, Pro=1/mo, Team=2/mo, Enterprise=10/mo, Admin=unlimited.

Response

{ "used": 1, "limit": 2, "remaining": 1, "plan": "team", "period_start": "2026-03-01", "period_end": "2026-03-31" }

Create a security scan configuration. Requires Pro, Team, or Enterprise plan.

Request Body

Trigger a security scan. Web scans require a verified domain. Mobile scans require an uploaded app with a valid file URL. Counts against monthly quota.

Request Body

Response

{ "id": "run-uuid", "status": "queued" }

Get scan run status and results. Poll this endpoint while status is queued or running.

Response (completed)

{
  "id": "run-uuid",
  "status": "completed",
  "security_score": 72,
  "total_findings": 15,
  "critical_count": 0,
  "high_count": 2,
  "medium_count": 5,
  "low_count": 4,
  "info_count": 4,
  "authenticated": true,
  "duration_seconds": 185
}

List verified domains for the team. Use POST to add a domain and receive a DNS TXT verification token.

List scheduled security scans for the team. Filter by scan_id query param to get schedules for a specific scan config. Each schedule has one and only one parent scan config.

Query Parameters

Create a scheduled security scan. One schedule per scan config. When the schedule fires, the scan uses the scan_depth configured on the scan itself. Every run counts against your monthly security scan cap (Pro 2/mo, Team 5/mo, Enterprise 20/mo). Security+ and admin users bypass the cap.

Request Body

Response

{
  "id": "schedule-uuid",
  "scan_id": "scan-uuid",
  "cron_expression": "0 9 * * 1-5",
  "timezone": "America/New_York",
  "enabled": true,
  "next_run_at": "2026-04-06T13:00:00.000Z"
}

Update a security scan schedule. Updating cron_expression, timezone, or re-enabling automatically recomputes next_run_at.

Request Body

Delete a security scan schedule. Does not affect the parent scan config or any completed runs.

List open pull requests for a GitHub repository. Returns PR number, title, author, head branch, and existing review status if previously reviewed. Requires a GitHub integration configured in Settings.

Trigger an AI code review on a pull request. Fetches the PR diff from GitHub and sends it to Claude for analysis. Returns the review ID with quality score and findings. Team/Enterprise only.

List past code reviews for the team. Returns review ID, repo, PR number/title, quality score, severity counts, and timestamps. Ordered by most recent.

Get a single code review with all findings. Each finding includes severity (critical/high/medium/low), category (bug/security/performance/style/logic/maintainability), title, description, suggestion, file path, line numbers, and code snippet.

Get code review settings for the team. Returns custom instructions, auto-review toggle, post-comments toggle, auto-bug creation config, and enabled status.

Update code review settings. All fields optional — only provided fields are updated.

Check code review usage. Returns reviews used and plan info. Unlimited reviews on Pro, Team, and Enterprise plans.

Get code review analytics for the team. Returns trends (daily review counts + avg scores), finding category and source breakdowns, severity distribution, velocity metrics (reviews/week, avg time, avg findings), top repos, top PR authors, and recent quality score sparkline data. Query param: days (7, 30, or 90, default 30).

List all GitHub webhooks registered for the team. Returns webhook ID, repo, active status, and creation date.

Register a GitHub webhook on a repository for auto-review. Requires repo (e.g. owner/name). Creates a webhook on GitHub that sends pull_request events to bugAgent. The webhook secret is auto-generated and stored securely.

Remove a GitHub webhook from a repository. Requires repo. Deletes the webhook from both GitHub and the bugAgent database.

GitHub webhook receiver endpoint. Handles pull_request events. Verifies HMAC-SHA256 signature, checks auto-review settings, and triggers a Claude-powered code review. Only processes opened and synchronize actions. Deduplicates by commit SHA.

List all Exploratory AI configs for the team. Returns name, target URL, status, agent count, selected strategies, last run info, and run count.

Create a new exploration config. Requires name and target_url. Optional: exploration_context (JSONB with focus_areas, instructions, auth_config, exclude_paths, max_depth, test_data), project_id, auto_create_bug, min_severity_for_bug, agent_count (1–10, clamped to plan limit; Pro: max 3, Team: max 10), agent_strategies (array of strategy IDs: happy_path, edge_case, security, accessibility, error_path, performance, mobile, data_integrity, navigation, custom).

Trigger an exploration run. Requires exploration_id. Dispatches to the runner for 5-phase execution (Recon, Plan, Execute, Analyze, Report). When agent_count > 1, multiple agents run Plan/Execute/Analyze in parallel after a shared Recon phase. Returns the run ID. Poll GET /api/explorations/runs/:id for status and per-agent progress via agent_progress.

Get exploration run details including phase data (recon, plan, execute, analyze), findings with agent attribution (agent_index, agent_strategy), per-agent progress (agent_progress), and linked bug reports. Use for polling during execution or viewing results.

Check monthly Exploratory AI usage. Pro: 3/mo, Team: 50/mo, Enterprise: 50/mo.

Get exploration history and trends. Returns run history, finding trends by type and severity over time, screenshot comparisons between consecutive runs, and delta vs previous run. Query params: exploration_id (optional filter), days (7/30/90, default 30).

Manage exploration schedules. GET lists schedules. POST creates a new one (requires exploration_id and cron_expression). PATCH updates schedule (enable/disable, change cron). DELETE removes a schedule. Supports notifications via email or Slack on failure.