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": "agent@example.com"
}

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": "agent@example.com",
  "accessToken": "eyJhbG...",
  "refreshToken": "refresh_...",
  "expiresAt": 1711234567
}

List bug reports for the authenticated user's account and team. Project and workspace filters are applied before pagination. Each report includes project_id, project, short_id, legacy_short_id, and project_short_id so API clients can link the report without guessing project context.

Query Parameters

Example

curl "https://app.bugagent.com/api/reports?project=bugagent&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. The response returns both the workspace-scoped legacy ID and the project-scoped short ID, along with project_id and project metadata.

Request Body

Response

{
  "id": "1fb72a2c-87c7-4adf-90e7-9bd81a8f34b7",
  "ticket_number": 545,
  "project_ticket_number": 42,
  "short_id": "WRKID-APP-042",
  "legacy_short_id": "WRKID-545",
  "project_short_id": "WRKID-APP-042",
  "project_id": "7b12c88b-4af5-4a21-9ef4-e74d98cb1337",
  "team_ticket_prefix": "WRKID",
  "project_ticket_prefix": "APP",
  "project": {
    "id": "7b12c88b-4af5-4a21-9ef4-e74d98cb1337",
    "name": "App",
    "slug": "app",
    "ticket_prefix": "APP"
  },
  "title": "Login button unresponsive on iOS",
  "is_epic": false,
  "parent_epic_id": null,
  "parent_epic": null,
  "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.

Hierarchy fields are returned in snake case: is_epic, parent_epic_id, parent_epic, and epic_progress. Epic detail responses include only the first bounded epic_children page plus epic_children_page metadata. Use the children endpoint below for subsequent pages.

Response Fields (includes all standard fields plus)

List one page of child reports for an Epic. The Epic must belong to a project the caller can access. Aggregate progress is calculated in PostgreSQL and does not require loading every child report.

Query Parameters

The response contains children, total, limit, offset, has_more, and epic_progress. Progress counts resolved and closed children as complete.

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

Permanently delete one report and its stored attachments. The identifier may be the canonical UUID or a short ID accepted by the report resolver. The caller must be able to access the report's workspace and project. Treat 404 as missing or unauthorized.

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).

Create a directional semantic link between two bug reports in the same workspace — the user-curated counterpart to the auto-detected similar_reports field. Both reports must belong to the same team; cross-team links are rejected (the database trigger enforces this as well as the API check). The inverse perspectives (duplicated-by / subtask-of / blocks / blocks-testing) are not stored separately — they're derived at read time from the same row.

Request Body

Response

Returns a JSON body with a link object containing id, from_report_id, to_report_id, link_type, created_at, and created_by. 409 Conflict if a link of this type between these two reports already exists.

Remove a previously-created bug-report link by its UUID. The caller must be an active member of the workspace that owns the link.

Request Body

Response

Returns success: true on a clean delete. 404 if the link does not exist (or the caller cannot see it).

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

Form Fields

Upload a single image before a report ID exists, so it can be embedded inline in the bug description as a markdown image reference. Used by the "Report a Bug" composer when pasting a screenshot — the returned URL is inserted at the cursor position as ![filename](url). Files land at a preflight storage path and are not linked to any bug report row; orphaned files are cleaned up by a periodic storage sweep. Max 25 MB.

Form Fields

Response

{ "url": "https://...supabase.co/storage/v1/object/public/bug-attachments/.../preflight/...", "filename": "screenshot-1234567890.png" }

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 accessible projects in the key-bound or active workspace. Each project includes id, team_id (the workspace UUID), name, slug, ticket_prefix, description, is_default, and created_at. Use the exact workspace and project UUIDs with GET /api/reports, POST /api/reports, and MCP project filters.

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 active, non-revoked workspace API keys. Requires an authenticated dashboard session and an owner, administrator, or manager role. API keys cannot manage other keys. Only the key prefix is returned — full keys are shown once at creation.

Generate a new API key. Requires an authenticated dashboard session and an owner, administrator, or manager role. API keys cannot create other keys. The full key (starting with ba_live_) is returned only once — store it securely. Free workspaces may keep at most two active workspace API keys.

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. Requires an authenticated dashboard session and an owner, administrator, or manager role. 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. Requires an authenticated dashboard session and an owner, administrator, or manager role. Returns the new full key and immediately invalidates the previous secret.

Get the authenticated user's profile.

Response

{
  "id": "uuid",
  "email": "user@example.com",
  "full_name": "Jane Smith",
  "avatar_url": null,
  "plan": "enterprise",
  "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": "user@example.com",
  "isAgent": false,
  "plan": "enterprise",
  "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": "enterprise",
  "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 }
}

Deprecated compatibility endpoint. Enterprise enrollment is sales-assisted, so this endpoint never creates a checkout session or changes a workspace plan.

Response

{
  "error": "Enterprise enrollment is sales-assisted. Contact Sales to change plans.",
  "action": "contact_sales",
  "url": "https://bugagent.com/#pricing"
}

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. A user may own up to five workspaces; invited memberships do not count toward this limit. Every additional workspace starts on Free, regardless of the creator’s other workspace plans. Use Feedback or Talk to Sales to request Enterprise enrollment or additional workspaces. If no name is provided, an 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": "free"
  }
}

Errors

Start the Jira OAuth 2.0 flow on either bugAgent plan. Redirects to Atlassian's authorization page. The resulting connection is stored against the initiating active workspace, not the individual user, and the callback fails if the active workspace changes during authorization.

Fetch all Jira projects accessible by the team's shared connection. Restricted to workspace owners, admins, and managers — this browses the connected Jira site, which ordinary members should not see. 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

List the workspace's project mappings — which Jira project each bugAgent project syncs to. Sync resolution order: explicit key on the push, then the report's project mapping, then the default project key.

Response

{
  "mappings": [
    { "project_id": "…", "jira_project_key": "ENCDEV", "jira_project_name": "enCappture Dev" }
  ]
}

Create, update, or remove a project mapping. Sending an empty jira_project_key removes the mapping and the project falls back to the default. Mappings are removed automatically when the Jira connection is disconnected or reconnected to a different site.

Request Body

{
  "project_id": "8f2c…",
  "jira_project_key": "BA",
  "sync_mode": "auto_all",
  "field_map": {
    "status": { "to do": "new", "in progress": "in-progress", "qa review": "retesting", "done": "resolved" },
    "status_push": { "awaiting-triage": "To Do", "confirmed": "To Do", "closed": "Done" },
    "severity": { "p0 - showstopper": "s1", "p1": "s2", "p2": "s3" },
    "severity_push": { "s1": "P0 - Showstopper", "s2": "P1", "s3": "P2", "s4": "P2" }
  }
}

The live value-spaces of one Jira project — its workflow statuses and the site's priorities. Feeds the field-mapping modal. Query: projectKey.

The explicit "Sync everything now" action. Requires at least one mapped project whose effective mode is auto_all (per-project override, else the workspace default); only those projects join the merge. It never runs on its own. Actions: preview (dry-run counts, nothing written), start (creates the job and kicks a server-side run — one running job per workspace, and it is safe to close the page: the server drives it to completion, and a watchdog revives runs interrupted by a deploy), status (live progress — the dashboard polls this to show a run in flight, and stamps when the last full sync finished), cancel, tick (processes one batch under the same lease; kept for compatibility, no longer required). Jira issues already linked to a report are updated, never duplicated; unlinked issues become reports translated through the project's field map; unlinked reports push to Jira. Nothing is deleted on either side.

AI-assisted field mapping: send the Jira project's status and priority names (never ticket content) and receive a proposed mapping, validated server-side against both value sets. The proposal prefills the modal for review — it is never applied automatically.

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
}

Deprecated compatibility endpoint. Browser recording now runs in the authenticated Automate Web workspace. Use POST /api/automations/create to create an automation from a Playwright script.

Response

{ "error": "Browser automation recording has moved to the authenticated Automate Web workspace." }

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

Available on both plans within workspace limits. Live-browser execution requires Enterprise.

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. Use each entry's durable version value as version_label: "vN" when replaying it.

Response

{
  "id": "uuid",
  "name": "Login flow smoke test",
  "steps": [
    { "action": "navigate", "url": "https://app.example.com/login" },
    { "action": "fill", "selector": "#email", "value": "test@example.com" },
    { "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", "version": 12 },
    { "script": "// the state before an AI-optimize ran", "source": "before_optimize", "timestamp": "2026-03-21T07:50:00Z", "version": 13 }
  ],
  "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": "v14", "script_version_source": "current" }
  ]
}

Notes

• script is always the current live version — the one Run Now executes when both version selectors are 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, version }; version remains stable when older entries rotate out. Prefer version_label: "vN" on POST /automations/runs or POST /v1/automations/run. Legacy version_index remains supported, but must not be sent with version_label.
• Each entry in recent_runs carries the durable version it executed as script_version_label ("vN") and whether it was live or historical in script_version_source. Legacy runs may still report "current". 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.
• With auth_session_mode=reuse, bugAgent stores Playwright cookies, local storage, and supported IndexedDB state as encrypted server-side ciphertext. State is isolated by workspace, project, login profile, normalized target origin, provider, browser, and OS family. BrowserStack receives the run-scoped state through its Playwright storageState configuration; the runner deletes the temporary file after execution.
• Session state is never returned by dashboard, REST, or MCP reads. Profile rotation, visibility changes, deletion, expiry, or a manual Reset session invalidates it. Concurrent refreshes use a bounded lease, and stale parallel callbacks cannot overwrite newer state.
• Playwright sessionStorage is not reusable. Native APK/IPA automation remains separate. MFA, CAPTCHA, and interactive SSO may require a fresh user-assisted profile/session rather than automatic refresh.

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', 'test@example.com');\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 its durable version_label 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. The endpoint stores a short-lived CSRF state cookie and redirects the browser to GitHub. Once the user authorizes, GitHub returns to the fixed bugAgent callback. Connect from Settings → Integrations in the dashboard.

Response

Location: https://github.com/login/oauth/authorize?client_id=...

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
    }
  ]
}

List the branches of a repository via the connected GitHub account. Used to populate the branch dropdown when configuring OKF/OQA knowledge sync for a project.

Query Parameters

Response

{ "branches": ["main", "develop", "oqa-knowledge"] }

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

{
  "success": true,
  "github_repo": "acme/web-app"
}

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. Resolve the conflict in GitHub, then retry the script save or push. To change the project’s repository association, use POST /api/github/map-repo.
• Scripts are pushed to tests/bugagent/{automation-name-slug}.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.

Request Body

{ "action": "disconnect" }

Response

{
  "success": true
}

List notes for the authenticated user's active team and project. Returns notes the user owns, project-team notes, and restricted notes that include the user. Supports full-text search, project filtering, author filtering, folder filtering, wiki filtering, tag filtering, archive filtering, sorting, and date range filtering.

Query Parameters

Response

{
  "notes": [
    {
      "id": "uuid",
      "title": "Checkout flow observations",
      "format": "markdown",
      "visibility": "shared",
      "project_id": "uuid",
      "folder_id": "uuid",
      "author_id": "uuid",
      "author_name": "Jane Smith",
      "last_editor_name": "Jane Smith",
      "time_spent_seconds": 1820,
      "wiki_page": true,
      "pinned": false,
      "archived_at": null,
      "tags": ["regression", "checkout"],
      "attachments_count": 2,
      "content_preview": "Observed checkout behavior...",
      "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.

Request Body

{ "id": "uuid" }

Response

{ "deleted": true }

Notes

• Time Tracking is an Enterprise plan feature. Free 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-8) 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 Enterprise.

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.6 (claude-sonnet-4-6). Costs are on the platform, not the caller's team.
• Available on Enterprise (matches the Developer Notes card gating).

Submit session evidence from the browser SDK. Send a project-bound ba_pub_ key in X-BugAgent-Key; the request Origin must exactly match one configured for that key. The workspace and project are derived from the key and cannot be selected in the body. Capture does not require a user login, but replay review and report creation do. Available on Enterprise.

Headers

Request Body

Response

{
  "session_id": "uuid",
  "team_id": "uuid",
  "project_slug": "storefront",
  "dashboard_url": "/dashboard/reports?session=uuid&team=uuid&project=storefront",
  "status": "analyzing"
}

Notes

• Requires an Enterprise plan. Free plan users receive a 403 error.
• JSON is capped at 16 MiB, non-screenshot metadata at 2 MiB, and screenshots at 10 MiB decoded.
• Upload an optional recording afterward as multipart form data to POST /api/sessions/capture-video with the same browser key and returned session_id. Video is capped at 50 MiB and may be attached once.
• Per-minute and daily request/byte quotas are enforced across application replicas. A limit returns 429 with Retry-After.
• Session retention is configurable on Enterprise.

Attach one browser recording to a session previously created by the same project-bound ba_pub_ key. Send multipart form data with the same exact allowed Origin. The key, workspace, project, and originating capture must all match.

Headers and form fields

Response

{
  "video_url": "https://storage.example/session-videos/..."
}

Controls and errors

• A session accepts one recording. A second attachment returns 409.
• The endpoint allows 6 requests per key and 60 per workspace per minute, plus the browser key's configured daily byte quota.
• 429 includes Retry-After. Distributed rate-limit infrastructure fails closed with 503.
• 403 covers disallowed origins or browser-key policy; 404 hides missing and unauthorized sessions.

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. Enterprise plan 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 Enterprise." }

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

{
  "test_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. Free cases may contain at most 128 KB of structured content.

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. Enterprise is required. Free workspaces can store URL references in the case's urls field instead. Multipart/form-data uses a single file field per request. Files are stored in the test-case-attachments Supabase Storage bucket; metadata is 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. The resulting structured content of a Free case may not exceed 128 KB.

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 Enterprise-only 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

{
  "test_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 }

Assign or unassign a case within a suite. The assignee must be an active member of the suite's workspace and have access to its project.

Request Body

Returns success, case_id, and the resulting assigned_to value.

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 }

Get one project-bound folder by UUID. Resources outside the authorized workspace or project are returned as 404.

Rename, describe, or move a folder within its existing project. Supply one or more of name, description, and parent_folder_id. Folder depth is limited to three levels.

Delete a folder hierarchy. The default mode=unfile_cases preserves its cases and moves them to Unfiled. mode=delete_cases also deletes descendant cases and requires owner, admin, or manager access.

Preview a recursive folder bulk action. Returns the source folder and total_case_count across its descendants.

Apply one bounded recursive action to cases in a folder tree: set_folder_color, set_case_color, add_tags, set_priority, or move_cases. The target folder, when used, must be in the same authorized project.

Returns ok: true and the number of affected cases.

Start a new immutable suite execution or resume the matching run after a safe retry. A parent suite includes cases from every descendant suite, deduplicated into a stable order. Returns the first plan page.

Request Body

Example

curl -X POST https://app.bugagent.com/api/v1/test-executions \
  -H "Authorization: Bearer ba_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "suite_id": "8b52d61e-0a5a-4e41-b138-2e462f9e4781",
    "external_run_id": "hermes:checkout-smoke:2026-07-14T09:00Z",
    "name": "Checkout smoke - Hermes",
    "agent": "hermes"
  }'

Response

Returns 201 Created for a new run and 200 OK when the same external_run_id resumes its matching suite. Reusing the ID for another suite returns 409 Conflict.

{
  "created": true,
  "schema_version": "1.0",
  "execution": {
    "id": "3f59dd97-cb2b-4f30-98c7-5209a8e9d348",
    "external_run_id": "hermes:checkout-smoke:2026-07-14T09:00Z",
    "execution_source": "hermes",
    "project_id": "2d404ddb-d7ea-439d-95ea-7bf907936398",
    "suite_id": "8b52d61e-0a5a-4e41-b138-2e462f9e4781",
    "status": "pending",
    "results_summary": {
      "total": 10, "passed": 0, "failed": 0,
      "blocked": 0, "skipped": 0, "untested": 10
    }
  },
  "plan": {
    "snapshot": {
      "schema_version": "1.0",
      "suite": { "id": "8b52d61e-0a5a-4e41-b138-2e462f9e4781", "name": "Checkout smoke" },
      "project": { "id": "2d404ddb-d7ea-439d-95ea-7bf907936398", "name": "Storefront" },
      "case_count": 10
    },
    "cases": [
      {
        "case_id": "9b975f52-9105-46fb-82a4-cbcb05904939",
        "origin_suite_id": "8b52d61e-0a5a-4e41-b138-2e462f9e4781",
        "plan_order": 0,
        "status": "untested",
        "case": { "schema_version": "1.0", "name": "Guest checkout succeeds", "steps": [] }
      }
    ],
    "next_cursor": null,
    "has_more": false
  }
}

Read canonical run state and one page of the immutable plan. The response uses the same schema_version, execution, and plan shape returned by the start endpoint.

Path and Query Parameters

curl "https://app.bugagent.com/api/v1/test-executions/3f59dd97-cb2b-4f30-98c7-5209a8e9d348?cursor=99&limit=100" \
  -H "Authorization: Bearer ba_live_your_key_here"

If has_more is true, pass next_cursor unchanged to retrieve the next page. A run outside the key's workspace returns 404.

Submit 1–200 results atomically. Every case_id must already belong to this run snapshot. Parallel batches serialize on the run, and the canonical summary is recalculated in the same database transaction.

Request Body

curl -X POST https://app.bugagent.com/api/v1/test-executions/3f59dd97-cb2b-4f30-98c7-5209a8e9d348/results \
  -H "Authorization: Bearer ba_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "results": [{
      "case_id": "9b975f52-9105-46fb-82a4-cbcb05904939",
      "status": "failed",
      "actual_result": "Checkout returned HTTP 500 after submitting payment.",
      "notes": "Synthetic card; no purchase was created.",
      "duration_seconds": 18
    }]
  }'

Response

{
  "schema_version": "1.0",
  "run_id": "3f59dd97-cb2b-4f30-98c7-5209a8e9d348",
  "accepted": 1,
  "status": "in_progress",
  "results_summary": {
    "total": 10, "passed": 0, "failed": 1,
    "blocked": 0, "skipped": 0, "untested": 9
  }
}

Retrying a case with the same status is safe and preserves the first accepted evidence. Submitting a different status for an already tested case returns 409 Conflict. When untested reaches zero, the run status becomes completed automatically.

Stop an interrupted execution while preserving accepted results and the current summary. The request has no body and is idempotent for an already aborted run. A completed run cannot be aborted.

curl -X POST https://app.bugagent.com/api/v1/test-executions/3f59dd97-cb2b-4f30-98c7-5209a8e9d348/abort \
  -H "Authorization: Bearer ba_live_your_key_here"

Response

{
  "schema_version": "1.0",
  "run_id": "3f59dd97-cb2b-4f30-98c7-5209a8e9d348",
  "status": "aborted",
  "results_summary": {
    "total": 10, "passed": 7, "failed": 1,
    "blocked": 0, "skipped": 0, "untested": 2
  },
  "already_stopped": false
}

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.

Export a project’s QA knowledge — bug reports, test cases, automations, and performance, security, and exploratory tests — as an OKF/OQA markdown bundle (the Open Query Agent format used by oqa.ai).

Query Parameters

Response

A zip archive with Content-Type: application/zip and a Content-Disposition: attachment header. The filename includes the project slug so saved files stay self-describing: bugagent-okf-acme-app.zip.

Save the per-project GitHub knowledge-sync target — the repo, branch, and path that a project’s OKF/OQA bundle is committed to — and, unless run is false, immediately commit the project’s current OKF/OQA bundle (bug reports, test cases, automations, and performance, security, and exploratory tests, in the oqa.ai format) to that repo via the GitHub Contents API.

Request Body

Response

{
  "synced": 12,
  "failed": 0,
  "repo": "acme/web-app",
  "branch": "main",
  "path": "oqa"
}

synced and failed are the counts of bundle files committed and skipped on error; when run is false both are 0. repo, branch, and path echo the resolved target that was saved for the project.

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. Enterprise: 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",
      "project_id": "uuid",
      "name": "MyApp",
      "platform": "android",
      "package_name": "com.acme.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,
  "page": 1,
  "per_page": 20
}

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",
  "project_id": "uuid",
  "name": "MyApp",
  "platform": "android",
  "package_name": "com.acme.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",
  "project_id": "uuid",
  "name": "MyApp",
  "platform": "android",
  "package_name": "com.acme.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. Changing its package or simulator target requires authority over every login profile used by linked automations, or an active workspace owner/admin role. The same authorization applies when replacing the app binary through the dashboard.

Path Parameters

Request Body

Response

{
  "id": "uuid",
  "project_id": "uuid",
  "name": "MyApp",
  "platform": "android",
  "package_name": "com.acme.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 uploaded app binary after the dashboard has completed its signed upload. Supply storage_path, and optionally file_size and version. This storage workflow requires an interactive dashboard session and is not an API-key upload contract.

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",
      "project_id": "uuid",
      "name": "Login Flow Test",
      "app_id": "uuid",
      "script_type": "maestro",
      "execution_mode": "browserstack_maestro",
      "status": "active",
      "target_devices": [
        "Pixel 7",
        "Samsung Galaxy S23"
      ],
      "created_at": "2026-03-21T09:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20
}

Create a mobile automation. Existing action recordings and imported scripts use appium_actions. Recorder-produced action lists are capped at 500 events and must include a resolved, versioned selector decision for every tap; ambiguous taps and obfuscated Android resource-ID placeholders return 422 until the user selects a stable locator or explicitly confirms the recorded coordinate. To run one known-working Maestro YAML flow directly on BrowserStack against an APK or IPA, set script_type to maestro and execution_mode to browserstack_maestro. Its appId must exactly match the linked app’s package or bundle ID; the first validated native flow establishes that ID when the app record does not have one yet.

Request Body

Response

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

Create a runnable mobile automation from a pasted test script, preserving the developer's real locators. Parses Appium (Python or JS), WebdriverIO, Maestro, and Playwright (mobile-web) and stores the parsed steps as recorded_actions that run verbatim (no agent loop). Obfuscated Android resource-ID placeholders are skipped and returned as selector-mapping warnings. Android only. Enterprise plan.

Request Body

Response

{
  "id": "uuid", "name": "Login flow", "app_id": "uuid",
  "script_type": "appium", "status": "active", "created_at": "…",
  "action_count": 7, "dialect": "appium-python", "warnings": []
}

Errors: 400 missing field or an iOS app, 404 app not in your workspace, 409 name already exists in the project, 422 no runnable actions parsed (see warnings).

List reusable login profiles for Mobile, Web Automation, and Exploratory AI — non-secret fields only. Stored username/password values are AES-encrypted and never returned. Private profiles owned by another user and profiles in inaccessible projects are omitted; shared profiles are available only to active members with access to the same project.

Query Parameters

Response

{
  "credentials": [
    { "id": "uuid", "project_id": "uuid", "name": "Admin", "visibility": "shared", "created_at": "2026-07-10T...", "created_by": "uuid", "can_manage": true, "managed_by_workspace": true }
  ]
}

Create a reusable login profile. The username and password are AES-encrypted at rest immediately and can never be read back. Private profiles are creator-only. Shared profiles may be selected by active members with access to the same project; the creator or an active workspace owner/admin may rename, rotate, or delete them. Only the creator can change visibility. Enterprise plan only. Profile names are unique per project.

Request Body

Response

{
  "credential": { "id": "uuid", "name": "Admin", "project_id": "uuid", "visibility": "private", "created_by": "uuid", "created_at": "2026-07-10T..." }
}

Errors: 400 missing/invalid name or username, 404 project not in your team, 409 a profile with that name already exists in the project, 503 credential storage is not configured on the server.

Rotate, rename, or change the visibility of a login profile. Include only the fields you want to change. Supplied secrets are re-encrypted immediately. The active creator may update any profile field. An active workspace owner/admin may rename or rotate a shared profile but cannot change its visibility; private profiles remain creator-only. Enterprise plan only.

Path Parameters

Request Body

Response

{
  "credential": { "id": "uuid", "name": "Admin", "project_id": "uuid", "visibility": "shared", "created_by": "uuid", "created_at": "2026-07-10T..." }
}

Errors: 400 nothing to update or invalid field, 403 caller cannot manage the profile or a non-creator attempted to change visibility, 404 profile not found in your team, 409 name already taken in the project.

Soft-delete a login profile. The active creator may delete any profile they created; an active workspace owner/admin may delete a shared profile. Private profiles remain creator-only. The profile row and historical run references remain for audit; future-use defaults are cleared so scheduled runs cannot silently use a deleted secret. Enterprise plan only.

Path Parameters

Response

{ "success": true }

Errors: 403 caller cannot manage the profile, 404 profile not found in your team (or already deleted).

List readable non-secret variable profiles for one authorized project. Requires mobile:read. Values are reusable synthetic Maestro inputs, not credentials: authorized project members receive the complete values and private visual evidence may display values rendered by the app.

Query Parameters

Response

{
  "profiles": [{
    "id": "uuid",
    "project_id": "uuid",
    "name": "Canadian checkout",
    "variables": { "DATA_EMAIL": "qa@example.test", "DATA_REGION": "ca" },
    "created_by": "uuid",
    "created_at": "2026-07-27T...",
    "updated_at": "2026-07-27T..."
  }]
}

Create a project-scoped non-secret data profile. Requires mobile:write. Keys must match DATA_[A-Z][A-Z0-9_]* within the documented 64-character format. Credential and Maestro-runtime names are reserved. Profiles contain 1–100 string values, each at most 4096 UTF-8 bytes, and at most 65536 bytes total.

Request Body

Response

{ "profile": { "id": "uuid", "project_id": "uuid", "name": "Canadian checkout", "variables": { "DATA_EMAIL": "qa@example.test", "DATA_REGION": "ca" } } }

Errors: 400 invalid name, key, value, count, or size; 404 inaccessible project; 409 name already used in the project.

Read one non-secret variable profile and its values. Requires mobile:read, active workspace membership, and project access. Inaccessible and cross-tenant IDs return 404.

Response

{ "profile": { "id": "uuid", "project_id": "uuid", "name": "Canadian checkout", "variables": { "DATA_EMAIL": "qa@example.test", "DATA_REGION": "ca" } } }

Rename a profile or replace its complete values object. Requires mobile:write. Only the active profile creator or an active workspace owner/admin may update it; project managers do not receive profile-use authority automatically.

Request Body

At least one field is required. The response returns the updated profile and its non-secret values.

Soft-delete a profile. Requires mobile:write and active creator or workspace owner/admin authority. Historical run references remain for audit; automation defaults are cleared, so future immediate runs and schedules no longer inherit the deleted profile.

Response

{ "success": true }

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

Path Parameters

Response

{
  "id": "uuid",
  "project_id": "uuid",
  "name": "Login Flow Test",
  "app_id": "uuid",
  "app_name": "MyApp",
  "script_type": "maestro",
  "execution_mode": "browserstack_maestro",
  "script": "appId: com.acme.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. The execution mode is immutable. Updates to native Maestro scripts are revalidated as a single YAML flow; recorded actions remain rejected for native Maestro mode. Action-replay updates are capped at 500 events and reject unresolved recorder taps with 422. Same-project credential_id and non-secret variable_profile_id defaults may be set or cleared when the YAML references their supported placeholders.

Path Parameters

Request Body

Response

{
  "id": "uuid",
  "project_id": "uuid",
  "name": "Login Flow Test",
  "app_id": "uuid",
  "app_name": "MyApp",
  "script_type": "maestro",
  "execution_mode": "browserstack_maestro",
  "script": "appId: com.acme.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 up to 100 retained script versions for an authorized mobile automation. Sensitive input values are not returned.

Restore a retained version while atomically preserving the current script as a new history entry.

Request Body

Read baseline metadata. Add ?item=N to receive a short-lived redirect to one authorized baseline image.

Create a visual baseline from a passed run using JSON { "run_id": "uuid" }, or upload one image as multipart form data in file. Uploads are limited to 10 MB. This evidence-management write currently requires an interactive dashboard session.

Remove the saved baseline and disable visual comparison for the automation.

List mobile test runs. Filter by automation and status.

Query Parameters

Response

{
  "runs": [
    {
      "id": "uuid",
      "automation_id": "uuid",
      "execution_mode": "browserstack_maestro",
      "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 on BrowserStack. appium_actions automations use the existing Appium replay executor. browserstack_maestro automations upload and execute the stored YAML through BrowserStack’s native Maestro API for both Android and iOS.

Request Body

Response

{
  "run_id": "uuid",
  "status": "queued"
}

Get results for an authorized mobile test run. Uncredentialed Appium runs include Appium/device/network logs; uncredentialed native Maestro runs include BrowserStack video, a representative end-of-run frame, any YAML takeScreenshot output, the flow result, Maestro command logs, device/network logs, and duration. Credentialed native BrowserStack Maestro runs retain private visual evidence, filtered logs, real step names, detailed failures, status, duration, counts, and BrowserStack identifiers for 30 days. Exact known credential values and recognized generic secret patterns are removed before text is persisted. Because this filtering cannot guarantee identification of every possible secret displayed by the tested app, detailed text is withheld whenever credential decryption or redaction context is unavailable or sanitization cannot be proven safe; status and available visual evidence remain. Workspace membership and project access are enforced for diagnostics. Private media is delivered with five-minute signed links. Auto-created bugs and Slack/email notifications remain generic and do not copy credentialed diagnostics. Credentialed Appium action runs return structural metadata and BrowserStack identifiers only.

Path Parameters

Response

{
  "id": "uuid",
  "project_id": "uuid",
  "automation_id": "uuid",
  "execution_mode": "browserstack_maestro",
  "status": "passed",
  "device": "Pixel 7",
  "os_version": "14",
  "duration_seconds": 45,
  "results": {
    "source": "browserstack_maestro",
    "framework": "maestro",
    "steps": [
      {
        "name": "Open dashboard",
        "status": "passed",
        "duration": 1400
      }
    ],
    "passed": 1,
    "failed": 0,
    "total": 1
  },
  "video_url": "https://app.bugagent.com/api/mobile/runs/uuid/artifact?name=video.mp4",
  "screenshots": [
    "https://app.bugagent.com/api/mobile/runs/uuid/artifact?name=screenshot-1.jpg"
  ],
  "logs_text": "=== MAESTRO LOG ===\nFlow completed",
  "credential_text_retained_at": "2026-03-22T08:00:45Z",
  "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

Create or link a bug report for an authorized mobile run whose status is failed or error. This idempotent operation requires mobile:write. Repeated requests return the report already linked to the run. Credentialed runs produce a generic report without private logs, screenshots, or video; authorized users can review that evidence on the run detail page.

Path Parameters

Response

{
  "bug_report_id": "uuid",
  "bug_short_id": "TEST-BA-227",
  "existing": false
}

Returns 404 for a missing or unauthorized run and 409 when the run did not fail or its source automation is no longer available.

Return a five-minute signed redirect for an artifact already referenced by the authorized run. Use the exact name from a run response, such as video.mp4 or screenshot-1.jpg. Arbitrary storage paths are rejected.

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

Query Parameters

Start a Refine with AI job for a recorded mobile automation, or resume its active one. An agent iteratively hardens the recorded tour into a self-healing, device-certified script — layering in resilient locators (accessibility id, resource id, semantic labels) and proving it with repeated green runs on a real device. One active refinement per automation; jobs count against a monthly plan quota. Android apps only for now. Enabled per workspace — a workspace without Refine with AI access receives 403 (contact us to turn it on).

Request Body

Response

201 Created with { refinement }, or 200 OK with { refinement, resumed: true } when the automation already has an active job. Returns 503 when Refine with AI is temporarily unavailable (maintenance or no refinement worker configured in the environment) — no job is created; retry later.

422 when the recorded tour signs in using a saved login profile (a credential field was captured during recording). Refine with AI cannot inject a login profile, so login tours are not refined on this path — certify a login flow with a native Maestro (YAML) run, which injects the profile securely.

Get a refinement's state plus its event log (transcript, stage changes, run reports). Events are ordered by a monotonic cursor for replay.

Query Parameters

Response

200 OK with { refinement, events, cursor }.

Send a chat message to the refining agent. Messages queue and are delivered at the next safe point in the loop — you can send anytime while the job is active. Secrets in the message (API keys, tokens, private keys, password=-style assignments) are automatically masked before the message is stored or reaches the agent.

Request Body

Response

201 Created with { event_id, redacted, redactions } — redacted is true when a secret was masked, and redactions is a by-kind count of what was masked (e.g. { aws_key: 1 }). 400 if the message is empty or exceeds 2000 characters. 409 if the refinement has finished. 429 if the per-refinement message cap is reached or messages are sent too quickly.

Stop an active refinement. The job pauses (keeping its draft and history) and any held device session is released. Resume later via POST /api/mobile/refinements.

Response

200 OK with { refinement }; 409 if already finished.

Approve the refined draft: freezes it as an immutable script version (with full provenance) and copies it into the automation's recorded_actions so future runs use it.

Response

200 OK with { refinement, script_version }; 400 when there is no draft; 409 while the job is still running.

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), login_profile_id, notify_on_fail (none/email/slack/both), notify_email, slack_channel_id. A profile UUID selects an authorized project-scoped identity for this schedule; null explicitly runs without a profile and does not inherit later automation-default changes. If the automation uses reusable authenticated sessions, each selected profile maintains a separately encrypted, target- and execution-scoped session. 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 and inherit the automation’s current login-profile and non-secret variable-profile defaults. Private login profiles require their active creator; shared login profiles require active same-project access. Non-secret variable profiles retain their creator-or-owner/admin policy. Change the automation default to change future scheduled inputs; schedules do not store a separate variable-profile override.

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"
}

Get one mobile schedule, including its automation name, cron expression, timezone, devices, notification settings, enabled state, and next run time. The schedule must belong to a workspace the caller can access.

Path Parameters

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. Only the active schedule creator or an active workspace owner/admin may change its timing, devices, notification settings, or enabled state.

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. Only the active schedule creator or an active workspace owner/admin may delete it.

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. Enterprise 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 PDF report for a performance run. Includes Lighthouse scores, Core Web Vitals, load test summary with latency percentiles, and test metadata.

Path Parameters

Response

Returns application/pdf with an attachment filename derived from the performance test and run.

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. Performance testing is Enterprise-only. Customer limits: Free=0, Enterprise=unlimited.

Response

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

Create a security scan configuration. Requires an 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 the Enterprise monthly security scan cap of 20. 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. 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. AI code review is Enterprise-only; unlimited on Enterprise.

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.