--- openapi: 3.0.1 info: title: WDT Rails API version: v1 description: API documentation for Web Developer Toolkit (WDT) Rails application. This API provides endpoints for authentication, bug capture, test case generation, integrations, and more. contact: name: BrowserStack Engineering url: https://toolkit.browserstack.com license: name: BrowserStack Proprietary url: https://www.browserstack.com/terms paths: "/api/v1/auth/start-sso": get: summary: Initiate SSO authentication with BrowserStack operationId: authStartSso tags: - Authentication description: Redirects the user to BrowserStack SSO login page. Optionally accepts a source parameter to customize the authentication flow. security: [] parameters: - name: source in: query required: false description: Source of the authentication request schema: type: string enum: - extension - preview_screen - name: return_to in: query required: false description: URL to redirect to after successful authentication (only for preview_screen source) schema: type: string responses: '302': description: Redirects to BrowserStack SSO login content: text/html: schema: type: string "/api/v1/auth/callback": get: summary: SSO callback endpoint operationId: authCallback tags: - Authentication description: Redirects to error page with flash message security: [] parameters: - name: code in: query required: true description: Authorization code from BrowserStack SSO schema: type: string - name: state in: query required: false description: State parameter for CSRF protection schema: type: string responses: '302': description: Authentication failed - redirects to error page content: text/html: schema: type: string "/api/v1/bug_capture/emails": post: summary: Relay a Bug Capture email through Raven operationId: bugCaptureRelayEmail tags: - Bug Capture description: Server-to-server relay (LV-3641). Bird Eats Bug selects the recipients and posts the template inputs; wdt-rails owns the template, the branding and the links, and sends through Raven. BEB cannot reach Raven directly. security: - basic_auth: [] parameters: [] responses: '202': description: Queued for delivery content: application/json: schema: type: object properties: success: type: boolean example: true data: type: object properties: queued: type: integer example: 1 template_key: type: string example: workspace-invite source: type: string example: toolkit '422': description: Unknown template, unknown source, or an incomplete model content: application/json: schema: type: object properties: success: type: boolean example: false message: type: string example: 'unknown template_key: session-uploaded' '401': description: Missing or wrong basic auth requestBody: content: application/json: schema: type: object required: - template_key - to - model properties: template_key: type: string enum: - workspace-invite - user-joined-workspace example: workspace-invite source: type: string enum: - beb - toolkit default: beb description: Surface the action happened on; picks the variant and CTA. to: type: string example: invitee@example.com description: One address or a comma separated list. reply_to: type: string nullable: true example: riya@example.com model: type: object example: workspaceId: ws-1 workspaceName: Acme inviterName: Riya Shah "/api/v1/bug_capture/user-data": get: summary: Get bug capture user data operationId: bugCaptureGetUserData tags: - Bug Capture description: Retrieves user data from the bug capture service for the authenticated user security: - session_cookie: [] responses: '200': description: User data retrieved successfully content: application/json: schema: type: object properties: success: type: boolean example: true data: type: object properties: user_id: type: string example: '12345' email: type: string example: user@example.com workspaces: type: array items: type: object '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string example: unauthorized '500': description: Internal server error or bug capture service unavailable content: application/json: schema: type: object properties: success: type: boolean example: false message: type: string example: Failed to get user data "/api/v1/bug_capture/user": post: summary: Create bug capture user operationId: bugCaptureCreateUser tags: - Bug Capture description: Creates a new user in the bug capture service security: - session_cookie: [] parameters: [] responses: '200': description: User created successfully content: application/json: schema: type: object properties: success: type: boolean example: true data: type: object properties: user_id: type: string example: '12345' email: type: string example: user@example.com '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string example: unauthorized '500': description: Internal server error or bug capture service unavailable content: application/json: schema: type: object properties: success: type: boolean example: false message: type: string example: Failed to create user requestBody: content: application/json: schema: type: object properties: email: type: string example: user@example.com name: type: string example: John Doe "/api/v1/bug_capture/session": post: summary: Mint a Bird Eats Bug session token operationId: bugCaptureCreateSession tags: - Bug Capture description: 'Server-side relay (LV-3386): reads the httpOnly wdt_jwt_token cookie and forwards it to Bird Eats Bug to mint a BEB (Hasura) JWT, so the toolkit dashboard can skip the BEB OAuth bounce.' security: - session_cookie: [] responses: '200': description: BEB session token minted successfully content: application/json: schema: type: object properties: success: type: boolean example: true access_token: type: string example: eyJhbGciOiJ... expires_at: type: integer example: 1750000000 '401': description: Unauthorized - wdt_jwt_token cookie missing content: application/json: schema: type: object properties: success: type: boolean example: false message: type: string example: unauthorized '500': description: Internal server error or BEB relay failed content: application/json: schema: type: object properties: success: type: boolean example: false message: type: string example: Failed to mint BEB session "/api/v1/bug_capture/sessions/{sessionId}/files": post: summary: Generate signed URL for file upload operationId: bugCaptureGenerateSignedUrl tags: - Bug Capture description: Generates signed URLs for uploading files (screenshots, videos, etc.) associated with a bug capture session security: - session_cookie: [] parameters: - name: sessionId in: path required: true description: ID of the bug capture session schema: type: string responses: '200': description: Signed URLs generated successfully content: application/json: schema: type: object properties: success: type: boolean example: true data: type: object properties: signed_urls: type: array items: type: object properties: file_name: type: string example: screenshot.png upload_url: type: string example: https://storage.example.com/upload?signature=... '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string example: unauthorized '500': description: Internal server error content: application/json: schema: type: object properties: success: type: boolean example: false message: type: string example: Failed to generate signed URL requestBody: content: application/json: schema: type: object properties: workspace_id: type: string example: ws_123 files: type: array items: type: object properties: name: type: string example: screenshot.png type: type: string example: image/png size: type: integer example: 12345 "/api/v1/bug_capture/workspace/{workspaceId}/session/{sessionId}": post: summary: Upload bug capture session operationId: bugCaptureUploadSession tags: - Bug Capture description: Uploads a complete bug capture session with all associated metadata and files security: - session_cookie: [] parameters: - name: workspaceId in: path required: true description: ID of the workspace schema: type: string - name: sessionId in: path required: true description: ID of the session schema: type: string responses: '200': description: Session uploaded successfully content: application/json: schema: type: object properties: success: type: boolean example: true data: type: object properties: session_id: type: string example: session_123 url: type: string example: https://bugcapture.example.com/session/123 '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string example: unauthorized '500': description: Internal server error content: application/json: schema: type: object properties: success: type: boolean example: false message: type: string example: Failed to upload session requestBody: content: application/json: schema: type: object properties: collectionId: type: string example: col_123 sessionDetails: type: object properties: title: type: string example: 'Bug: Login button not working' description: type: string example: Detailed description of the bug browser: type: string example: Chrome 120 os: type: string example: macOS 14 "/api/v1/bug_capture/sessions/{sessionId}": get: summary: Get bug capture session details operationId: bugCaptureGetSession tags: - Bug Capture description: Retrieves details of a specific bug capture session. This endpoint does not require authentication. security: [] parameters: - name: sessionId in: path required: true description: ID of the bug capture session schema: type: string responses: '200': description: Session details retrieved successfully content: application/json: schema: type: object properties: success: type: boolean example: true data: type: object description: The Bird Eats Bug GET /sessions/:id payload, served natively or proxied properties: session: type: object nullable: true description: The recording, with storage pointers replaced by signed URLs (valid 1h). Workspace-only fields (workspaceId, collectionId, ownerId, uploaderEmail, assignees, labels, integrations, views, notificationSubscriptions) are omitted for non-members; recording resources are omitted when expired. isUserWorkspaceMember: type: boolean hasUserAccess: type: boolean sessionPath: type: string example: "/workspaces/{workspaceId}/collections/{collectionId}/sessions/{sessionId}" isExpired: type: boolean show6MonthDeprecationScreen: type: boolean logsHiddenFromViewer: type: boolean hasCapturedLogs: type: boolean downloadEnabled: type: boolean description: The session's workspace download setting; true when unknown '404': description: Session not found content: application/json: schema: type: object properties: success: type: boolean example: false message: type: string example: Session not found '500': description: Internal server error content: application/json: schema: type: object properties: success: type: boolean example: false message: type: string example: Failed to get session "/api/v1/bug_capture/graphql": post: summary: Execute GraphQL query on bug capture service operationId: bugCaptureGraphql tags: - Bug Capture description: Executes a GraphQL query against the bug capture service security: - session_cookie: [] parameters: [] responses: '200': description: GraphQL query executed successfully content: application/json: schema: type: object properties: success: type: boolean example: true data: type: object description: GraphQL response data '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string example: unauthorized '500': description: Internal server error or GraphQL query failed content: application/json: schema: type: object properties: success: type: boolean example: false message: type: string example: Failed to perform GraphQL operation requestBody: content: application/json: schema: type: object properties: query: type: string example: query { sessions { id title } } description: GraphQL query string variables: type: object example: userId: '12345' description: GraphQL query variables required: - query "/api/v1/cwa/collections": post: summary: Upload a new collection operationId: cwaUploadCollection tags: - CWA description: Upload a new collection with file attachment for Common Workflow Automation security: - session_cookie: [] parameters: [] responses: '201': description: Collection created successfully content: application/json: schema: type: object properties: success: type: boolean example: true message: type: string example: Collection uploaded successfully data: type: object properties: id: type: integer example: 1 name: type: string example: Test Collection created_at: type: string format: date-time '400': description: Bad request - missing file content: application/json: schema: type: object properties: success: type: boolean example: false message: type: string example: File is required '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/Error" requestBody: content: multipart/form-data: schema: type: string required: true description: Name of the collection get: summary: List collections operationId: cwaListCollections tags: - CWA description: Retrieve all collections for the authenticated user security: - session_cookie: [] responses: '200': description: Collections retrieved successfully content: application/json: schema: type: object properties: success: type: boolean example: true data: type: array items: type: object properties: id: type: integer example: 1 name: type: string example: Test Collection created_at: type: string format: date-time "/api/v1/cwa/workflows": post: summary: Create a new workflow operationId: cwaGenerateWorkflow tags: - CWA description: Create a new workflow for Common Workflow Automation security: - session_cookie: [] parameters: [] responses: '201': description: Workflow created successfully content: application/json: schema: type: object properties: success: type: boolean example: true message: type: string example: Workflow created successfully data: type: object properties: id: type: integer example: 1 collection_id: type: integer example: 1 user_prompt: type: string example: Generate a test workflow status: type: string example: pending created_at: type: string format: date-time '400': description: Bad request - missing parameters content: application/json: schema: type: object properties: success: type: boolean example: false message: type: string example: User prompt is required '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/Error" '429': description: Rate limit exceeded - too many workflow generations for this user (LV-3308) content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Rate limit exceeded message: type: string example: Rate limit exceeded, Too many requests. Please try again later. requestBody: content: application/json: schema: type: object properties: collection_id: type: integer example: 1 description: ID of the collection to use user_prompt: type: string example: Generate a test workflow description: User prompt for workflow generation required: - collection_id - user_prompt get: summary: List workflows operationId: cwaListWorkflows tags: - CWA description: Retrieve all workflows for the authenticated user security: - session_cookie: [] responses: '200': description: Workflows retrieved successfully content: application/json: schema: type: object properties: success: type: boolean example: true data: type: array items: type: object properties: id: type: integer example: 1 collection_id: type: integer example: 1 user_prompt: type: string example: Generate a test workflow status: type: string example: pending created_at: type: string format: date-time "/api/v1/cwa/workflows/{id}": parameters: - name: id in: path description: Workflow ID required: true schema: type: integer get: summary: Get workflow details operationId: cwaGetWorkflow tags: - CWA description: Retrieve specific workflow details or status security: - session_cookie: [] parameters: - name: status in: query required: false description: Set to "true" to get only status information schema: type: string responses: '200': description: Workflow retrieved successfully content: application/json: schema: type: object properties: success: type: boolean example: true data: type: object properties: id: type: integer example: 1 collection_id: type: integer example: 1 user_prompt: type: string example: Generate a test workflow status: type: string example: completed workflow_data: type: object created_at: type: string format: date-time updated_at: type: string format: date-time '404': description: Workflow not found content: application/json: schema: type: object properties: success: type: boolean example: false message: type: string example: Workflow not found put: summary: Update workflow operationId: cwaUpdateWorkflow tags: - CWA description: Update an existing workflow security: - session_cookie: [] parameters: [] responses: '200': description: Workflow updated successfully content: application/json: schema: type: object properties: success: type: boolean example: true message: type: string example: Workflow updated successfully data: type: object properties: id: type: integer example: 1 collection_id: type: integer example: 1 user_prompt: type: string example: Updated workflow prompt status: type: string example: pending updated_at: type: string format: date-time '404': description: Workflow not found content: application/json: schema: type: object properties: success: type: boolean example: false message: type: string example: Workflow not found requestBody: content: application/json: schema: type: object properties: user_prompt: type: string example: Updated workflow prompt description: Updated user prompt for workflow generation collection_id: type: integer example: 1 description: Updated collection ID delete: summary: Delete workflow operationId: cwaDeleteWorkflow tags: - CWA description: Soft delete a workflow security: - session_cookie: [] responses: '200': description: Workflow deleted successfully content: application/json: schema: type: object properties: success: type: boolean example: true message: type: string example: Workflow deleted successfully '404': description: Workflow not found content: application/json: schema: type: object properties: success: type: boolean example: false message: type: string example: Workflow not found "/api/v1/cwa/webhook": post: summary: CWA Webhook operationId: cwaWebhook tags: - CWA description: Webhook endpoint for Common Workflow Automation callbacks security: - basic_auth: [] parameters: [] responses: '200': description: Webhook processed successfully content: application/json: schema: type: object properties: success: type: boolean example: true message: type: string example: Webhook processed successfully '401': description: Unauthorized content: application/json: schema: type: object properties: success: type: boolean example: false message: type: string example: Unauthorized requestBody: content: application/json: schema: type: object properties: webhook_action: type: string example: generate status: type: string example: completed result: type: object properties: workflow_id: type: integer example: 1 workflow: type: object required: - webhook_action - status - result "/api/v1/cwa/agent/browser_tokens": post: summary: Mint a short-lived BrowserAgent (TCG) token operationId: cwaAgentBrowserToken tags: - CWA description: Mint a short-lived TCG bearer for the in-extension BrowserAgent engine (LV-3757). Paid-only; counted against the monthly AI generation quota unless resuming a recent one. security: - session_cookie: [] parameters: [] responses: '200': description: Token minted content: application/json: schema: type: object properties: success: type: boolean example: true data: type: object properties: jwt: type: string example: eyJhbGciOi... tcg_host: type: string example: https://lcnc-api.browserstack.com/ai-lca remaining_generations: type: integer example: 19 limits: type: object properties: max_steps_per_automation: type: integer example: 75 monthly_generations: type: integer example: 20 '402': description: Monthly generation quota exhausted content: application/json: schema: type: object properties: success: type: boolean example: false message: type: string code: type: string example: quota_exhausted '502': description: Upstream token mint failed content: application/json: schema: type: object properties: success: type: boolean example: false message: type: string example: Token mint failed code: type: string example: upstream_unavailable requestBody: content: application/json: schema: type: object properties: resume: type: boolean example: false description: Reuse a recent counted generation without spending quota (only honoured while one is recent). "/api/v1/cwa/recordings": get: summary: List saved recordings (metadata only) operationId: cwaListRecordings tags: - CWA description: List the caller recordings newest-first without step payloads. Capped at RECORDINGS_LIST_LIMIT; truncated=true signals older rows were omitted. security: - session_cookie: [] responses: '200': description: Recordings listed content: application/json: schema: type: object properties: success: type: boolean example: true data: type: array items: type: object properties: id: type: integer client_id: type: string example: '1756700001' recording_name: type: string example: A recording step_count: type: integer example: 1 total: type: integer example: 1 truncated: type: boolean example: false post: summary: Create or update a recording (upsert by client_id) operationId: cwaUpsertRecording tags: - CWA description: Create or update a recording keyed on the extension client_id. security: - session_cookie: [] parameters: [] responses: '201': description: Recording created content: application/json: schema: type: object properties: success: type: boolean example: true data: type: object requestBody: content: application/json: schema: type: object properties: client_id: type: string example: '1756700001' recording_name: type: string example: A recording created_via: type: string example: manual url: type: string example: https://example.com current_domain: type: string example: example.com steps: type: array items: type: object required: - client_id "/api/v1/cwa/recordings/{client_id}": parameters: - name: client_id in: path required: true example: '1756700001' schema: type: string get: summary: Fetch one recording with its steps operationId: cwaShowRecording tags: - CWA description: Return a single recording including its step payload. security: - session_cookie: [] responses: '200': description: Recording found content: application/json: schema: type: object properties: success: type: boolean example: true data: type: object properties: client_id: type: string example: '1756700001' steps: type: array items: type: object '404': description: Recording not found content: application/json: schema: type: object properties: success: type: boolean example: false message: type: string example: Recording not found code: type: string example: not_found delete: summary: Delete a recording by client_id operationId: cwaDeleteRecording tags: - CWA description: Delete the caller recording by client_id (idempotent). security: - session_cookie: [] responses: '204': description: Deleted (or already absent) "/api/v1/domain_blacklist": get: summary: Get all blacklisted domains operationId: domainBlacklistIndex tags: - Domain Blacklist description: 'Returns all domains in the blacklist sorted alphabetically. The list is backed by a Redis Set (DOMAIN_BLACKLIST_KEY). Default domains are seeded on first call if the set is empty. Add or remove entries directly via Redis: SADD/SREM domain_blacklist:domains "".' security: - session_cookie: [] responses: '200': description: Domain blacklist returned successfully content: application/json: schema: type: object required: - success - domains properties: success: type: boolean example: true domains: type: array items: type: string example: - baidu - bing - facebook - github - google - stackoverflow '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string example: unauthorized '500': description: Internal server error content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: connection refused "/api/v1/figma/connection-status": get: summary: Get Figma connection status operationId: figmaConnectionStatus tags: - Figma description: Returns whether the authenticated user has a connected Figma OAuth integration security: - session_cookie: [] responses: '200': description: Connection status retrieved successfully content: application/json: schema: type: object properties: connected: type: boolean example: true required: - connected '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string example: unauthorized '500': description: Internal server error content: application/json: schema: type: object properties: error: type: string example: Internal server error "/api/v1/figma/frame-image": get: summary: Fetch Figma frame image operationId: figmaFrameImage tags: - Figma description: Fetches a rendered image URL for a specific Figma frame identified by its URL security: - session_cookie: [] parameters: - name: url in: query required: true description: Full Figma frame URL including node-id query parameter example: https://www.figma.com/file/abc123/MyFile?node-id=1-2 schema: type: string responses: '200': description: Frame image fetched successfully content: application/json: schema: type: object properties: image_url: type: string example: https://s3.amazonaws.com/figma-frames/abc123.png required: - image_url '400': description: Missing url parameter content: application/json: schema: type: object properties: error_type: type: string example: missing_url '401': description: Figma token invalid or session unauthorized content: application/json: schema: type: object properties: error_type: type: string example: token_invalid '403': description: User not connected to Figma content: application/json: schema: type: object properties: error_type: type: string example: not_connected '502': description: Failed to fetch frame from Figma content: application/json: schema: type: object properties: error_type: type: string example: fetch_failed '500': description: Internal server error content: application/json: schema: type: object properties: error: type: string example: Internal server error "/api/v1/figma/disconnect": delete: summary: Disconnect Figma integration operationId: figmaDisconnect tags: - Figma description: Revokes the Figma OAuth connection for the authenticated user security: - session_cookie: [] responses: '200': description: Figma integration disconnected successfully content: application/json: schema: type: object properties: success: type: boolean example: true required: - success '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string example: unauthorized '500': description: Internal server error content: application/json: schema: type: object properties: error: type: string example: Internal server error "/api/v1/integration": get: summary: List user integrations operationId: integrationIndex tags: - Integration description: Retrieves all third-party integrations configured by the authenticated user security: - session_cookie: [] responses: '200': description: Integrations retrieved successfully content: application/json: schema: type: array items: type: object properties: id: type: string example: int_123 type: type: string example: atlassian enum: - atlassian - github - gitlab name: type: string example: My Atlassian Integration status: type: string example: active enum: - active - inactive - error created_at: type: string format: date-time '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string example: unauthorized "/api/v1/integration/list-integrations": get: summary: List available integration types operationId: integrationListIntegrations tags: - Integration description: Returns a list of all available third-party integration types and their configuration status security: - session_cookie: [] responses: '200': description: Integration types retrieved successfully content: application/json: schema: type: object properties: integrations: type: array items: type: object properties: type: type: string example: atlassian name: type: string example: Atlassian (Jira/Confluence) description: type: string example: Connect with Jira and Confluence configured: type: boolean example: true '400': description: Bad request content: application/json: schema: type: object properties: error: type: string example: Failed to retrieve integrations '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string example: unauthorized '500': description: Internal server error content: application/json: schema: type: object properties: error: type: string example: Failed to retrieve integrations "/api/v1/integration/get-pm-tools-organizations": get: summary: Get project management tools organizations operationId: integrationGetPmToolsOrganizations tags: - Integration description: Retrieves organizations/workspaces from connected project management tools (Jira, etc.) security: - session_cookie: [] responses: '200': description: Organizations retrieved successfully content: application/json: schema: type: object properties: organizations: type: array items: type: object properties: id: type: string example: org_123 name: type: string example: My Organization url: type: string example: https://myorg.atlassian.net tool: type: string example: jira '400': description: Bad request content: application/json: schema: type: object properties: error: type: string example: Failed to retrieve organizations '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string example: unauthorized '500': description: Internal server error content: application/json: schema: type: object properties: error: type: string example: Failed to retrieve organizations "/api/v1/integration/get-doc-tools-organizations": get: summary: Get documentation tools organizations operationId: integrationGetDocToolsOrganizations tags: - Integration description: Retrieves organizations/workspaces from connected documentation tools (Confluence, etc.) security: - session_cookie: [] responses: '200': description: Organizations retrieved successfully content: application/json: schema: type: object properties: organizations: type: array items: type: object properties: id: type: string example: org_123 name: type: string example: My Organization url: type: string example: https://myorg.atlassian.net tool: type: string example: confluence '400': description: Bad request content: application/json: schema: type: object properties: error: type: string example: Failed to retrieve organizations '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string example: unauthorized '500': description: Internal server error content: application/json: schema: type: object properties: error: type: string example: Failed to retrieve organizations "/api/v1/integration/get-page-title": get: summary: Extract page title from URL operationId: integrationGetPageTitle tags: - Integration description: Fetches and extracts the page title from a given URL. Useful for integration pages and bookmarks. security: - session_cookie: [] parameters: - name: page_url in: query required: true description: URL of the page to extract title from example: https://example.atlassian.net/browse/PROJ-123 schema: type: string responses: '200': description: Page title extracted successfully content: application/json: schema: type: object properties: title: type: string example: Project Issue - PROJ-123 url: type: string example: https://example.atlassian.net/browse/PROJ-123 '400': description: Bad request - page_url parameter missing or invalid content: application/json: schema: type: object properties: error: type: string example: page_url parameter is required '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string example: unauthorized '500': description: Internal server error content: application/json: schema: type: object properties: error: type: string example: Failed to extract page title "/api/v1/integration/create-ticket": post: summary: Create a ticket in a connected project-management tool operationId: integrationCreateTicket tags: - Integration description: Reports a Visual Overlay finding as a ticket through the central integrations service. The description arrives as plain lines (plus an optional link) and is converted to the rich-doc format the tool expects. security: - session_cookie: [] parameters: [] responses: '201': description: Ticket created content: application/json: schema: type: object properties: external_id: type: string example: LV-1 external_url: type: string example: https://x.atlassian.net/browse/LV-1 '401': description: Tool connection lapsed content: application/json: schema: type: object properties: error: type: string '422': description: Ticket refused content: application/json: schema: type: object properties: error: type: string requestBody: content: application/json: schema: type: object properties: integration_key: type: string example: jira fields: type: object properties: organisation_id: type: string example: org-1 project_id: type: string example: '10000' ticket_type_id: type: string example: '10002' summary: type: string example: 'Visual difference: Navigation item spacing tightened' required: - project_id - ticket_type_id - summary description_lines: type: array items: type: string link: type: object properties: text: type: string uri: type: string required: - fields "/api/v1/integration/add-ticket-attachment": post: summary: Attach a file to a ticket operationId: integrationAddTicketAttachment tags: - Integration description: Attaches one file (the diff image of a Visual Overlay finding) to a ticket created through the central integrations service. security: - session_cookie: [] parameters: [] responses: '200': description: File attached content: application/json: schema: type: object properties: success: type: boolean example: true '422': description: Attachment refused content: application/json: schema: type: object properties: error: type: string '401': description: Tool connection lapsed content: application/json: schema: type: object properties: error: type: string '504': description: Upload sent but not confirmed — check the ticket before retrying content: application/json: schema: type: object properties: error: type: string example: integration_indeterminate requestBody: content: multipart/form-data: schema: type: object properties: file: type: string format: binary ticket_id: type: string example: org___1098201 integration_key: type: string example: jira organisation_id: type: string example: org-1 project_id: type: string example: '10000' required: - file - ticket_id required: true description: The file to attach, and the ticket to attach it to "/api/v1/integrations-service/user-access-token": get: summary: Get a short-lived user access token for the Integrations Service operationId: integrationsServiceUserAccessToken tags: - Integrations Service description: Proxies a request to bsstag.com/api/user-access-tokens using Basic Auth credentials from vault, returning a short-lived JWT that the IntegrationsWidget uses as a Bearer token to authenticate directly with the BrowserStack Integrations Service. security: - session_cookie: [] responses: '200': description: Access token retrieved successfully content: application/json: schema: type: object properties: access_token: type: string example: eyJhbGc... expires_at: type: integer example: 1712345678 description: Unix timestamp when the token expires required: - access_token - expires_at '401': description: Unauthorized - user not authenticated content: application/json: schema: type: object properties: message: type: string example: unauthorized '500': description: Internal server error content: application/json: schema: type: object properties: error: type: object properties: message: type: string example: boom "/api/v1/location_simulator/proxy-token": post: summary: Generate WonderProxy access token operationId: locationSimulatorProxyToken tags: - Location Simulator description: Generates a temporary WonderProxy access token that expires in 30 minutes. Used for geolocation testing. security: - session_cookie: [] responses: '200': description: Proxy token generated successfully content: application/json: schema: type: object properties: success: type: boolean example: true response: type: object properties: token: type: string example: 1-0-1763440656-MEQCIF... description: Temporary WonderProxy access token (expires in 30 minutes) expires_at: type: string format: date-time example: '2024-12-02T10:30:00Z' '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string example: unauthorized '500': description: Internal server error - failed to generate token content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Failed to generate proxy token "/api/v1/location_simulator/proxy-servers": get: summary: Get available WonderProxy servers operationId: locationSimulatorProxyServers tags: - Location Simulator description: Retrieves all available WonderProxy server locations worldwide for geolocation testing security: - session_cookie: [] responses: '200': description: Proxy servers retrieved successfully content: application/json: schema: type: object properties: success: type: boolean example: true response: type: array items: type: object properties: hostname: type: string example: us-east-proxy.wonderproxy.com description: Proxy server hostname title: type: string example: United States - New York description: Human-readable server location location: type: object properties: city: type: string example: New York country: type: string example: United States country_code: type: string example: US latitude: type: number format: float example: 40.7128 longitude: type: number format: float example: -74.006 protocols: type: array items: type: string example: - http - https - socks5 '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string example: unauthorized '500': description: Internal server error - failed to retrieve servers content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Failed to retrieve proxy servers "/api/v1/oauth2_v2/authorize": get: summary: Initiate OAuth2 v2 authentication operationId: oauth2Authorize tags: - Authentication description: Redirects user to OAuth2 v2 authorization endpoint with required query parameters. security: [] parameters: - name: source in: query required: false description: Source of request schema: type: string enum: - extension - preview_screen - name: return_to in: query required: false description: Return URL used only for preview_screen source schema: type: string - name: scope in: query required: false description: OAuth2 scope schema: type: string responses: '302': description: Redirects to OAuth2 authorization endpoint content: text/html: schema: type: string "/api/v1/oauth2_v2/callback": get: summary: OAuth2 v2 callback endpoint operationId: oauth2Callback tags: - Authentication description: Handles OAuth2 v2 callback and redirects to success or error page. security: [] parameters: - name: code in: query required: true description: Authorization code schema: type: string - name: state in: query required: true description: CSRF state token schema: type: string responses: '302': description: Authentication failed - invalid state content: text/html: schema: type: string "/api/v1/oauth2_v2/token": post: summary: Exchange authorization code for access token operationId: oauth2Token tags: - Authentication description: OAuth2 v2 token endpoint for authorization code exchange. security: [] parameters: [] responses: '200': description: Token response returned content: application/json: schema: type: object properties: access_token: type: string example: jwt.token.value token_type: type: string example: Bearer expires_in: type: integer example: 7200 refresh_token: type: string nullable: true example: refresh-token scope: type: string nullable: true example: read write created_at: type: integer example: 1732000000 required: - access_token - token_type - expires_in - created_at '400': description: Unsupported grant type content: application/json: schema: type: object properties: error: type: string example: unsupported_grant_type required: - error '401': description: Token exchange failed content: application/json: schema: type: object properties: error: type: string example: Failed to obtain access token required: - error requestBody: content: application/x-www-form-urlencoded: schema: type: string required: true description: Must be authorization_code "/api/v1/tcg/{tcg_id}/export": get: summary: Download AI-generated test cases in a specific export format operationId: tcgExport tags: - TCG description: Returns a signed S3 URL for the test cases of the given TCG in the requested format (testrail | qase | bstack_tm | markdown). The file is generated lazily on first request for legacy TCGs and cached on subsequent calls. The legacy default CSV is served via the existing list-response csv_export_file_url field and is intentionally not handled here. security: - session_cookie: [] parameters: - name: tcg_id in: path required: true description: ID of the test case generation request schema: type: string - name: format in: query required: true description: Export format schema: type: string enum: - testrail - qase - bstack_tm - markdown responses: '200': description: Lazy-generates for legacy TCGs that have no cached file yet content: application/json: schema: type: object properties: url: type: string example: https://s3.example.com/signed format: type: string example: testrail filename: type: string example: TMPD-1110_testrail.csv '400': description: Invalid format '401': description: Unauthorized '404': description: Tcg not owned by current user '500': description: Generation failed "/api/v1/tcg/{tcg_id}/push-export": post: summary: Push generated test cases into a connected test management tool operationId: tcgPushExport tags: - TCG description: Starts an asynchronous export of the TCG's generated test cases into TestRail, Xray, Azure Test Plans or Zephyr Scale via the central integrations service. Returns immediately with the run record; poll the companion GET endpoint for progress. Every export CREATES new cases in the target tool — nothing is updated in place, so exporting twice produces two independent sets. security: - session_cookie: [] parameters: - name: tcg_id in: path required: true description: ID of the test case generation request schema: type: string responses: '202': description: Export accepted and queued content: application/json: schema: type: object properties: data: type: object properties: id: type: string type: type: string example: tcg-push-exports attributes: type: object properties: export-type: type: string example: testrail status: type: object description: Run state. Lives on the tool-specific target, so a future tool can report progress its own way. properties: state: type: string enum: - pending - in_progress - success - partial - failed total: type: integer succeeded: type: integer failed: type: integer skipped: type: integer description: 'Cases dedupe held back. Counted from their own rows, NOT derived as total - succeeded - failed: a run that stops on its time budget leaves cases with no row at all, so that subtraction no longer holds.' skip_exported: type: boolean attempts: type: integer target: type: object description: Where this run is sending its cases, flattened from the per-tool target record. properties: type: type: string example: TcgTestrailExportTarget project-id: type: string example: '2' container: type: string example: section 9 site-url: type: string example: https://acme.testrail.io total-count: type: integer example: 42 success-count: type: integer example: 0 failure-count: type: integer example: 0 '422': description: Unsupported tool, missing project, or nothing to export content: application/json: schema: type: object properties: error: type: string example: unsupported_tool '404': description: TCG not found for this user content: application/json: schema: type: object properties: error: type: string example: not_found requestBody: content: application/json: schema: type: object required: - tool - project_id properties: tool: type: string enum: - testrail - xray - azure-testplan - zephyr-scale description: 'Integration key of the target tool. qTest and QMetry are not accepted: their connectors are read-only upstream.' project_id: type: string example: '10001' description: Project in the target tool folder_id: type: string example: "/Regression/Critical" description: 'Destination container, interpreted per tool and stored on a typed target record: a section id for TestRail (required there), a folder PATH for Xray and Zephyr Scale, a test plan id for Azure Test Plans.' suite_id: type: string description: TestRail multi-suite projects, and the test suite id for Azure Test Plans area_path: type: string description: Azure Test Plans only iteration_path: type: string description: Azure Test Plans only create_preconditions: type: boolean default: true description: 'Xray only: create each case''s precondition as its own linked Jira issue' skip_exported: type: boolean default: true example: true description: Dedupe. Any case an earlier run already created in this PROJECT is left alone, so a second export does not duplicate it. DEFAULTS TO TRUE — send false only to force a fresh set, which is what someone who deleted the cases in their tool needs, since these records track what we created rather than what still exists. Reported back as status.skipped. folder_name: type: string example: TCG-42 Checkout description: 'Creates (or reuses) a per-run home of this name and targets it: a section under folder_id for TestRail, a folder path for Xray and Zephyr Scale, and a whole TEST PLAN (root suite included) for Azure Test Plans, where it replaces any caller-picked plan and suite.' required: true "/api/v1/tcg/{tcg_id}/push-export/{push_export_id}": get: summary: Progress of a test management export operationId: tcgPushExportStatus tags: - TCG description: Reports how far an export has got. Counts update as the run proceeds. `failures` lists cases that did not reach the tool; `warnings` lists cases that were created but incompletely — e.g. created without being filed into the requested folder, or referencing a dataset that no longer exists. security: - session_cookie: [] parameters: - name: tcg_id in: path required: true schema: type: string - name: push_export_id in: path required: true schema: type: string responses: '200': description: Run status returned content: application/json: schema: type: object properties: data: type: object properties: attributes: type: object properties: status: type: object properties: state: type: string enum: - pending - in_progress - success - partial - failed total: type: integer succeeded: type: integer failed: type: integer created: type: array description: What landed, with links where the site was resolved. items: type: object properties: test_case_id: type: integer external_id: type: string external_key: type: string external_url: type: string nullable: true truncated: type: array description: Names any of the lists below that hit its cap (500 for created/preconditions, 200 for failures/warnings). Empty on almost every run; non-empty means the array you were handed is short of the real count in status. items: type: string preconditions: type: array description: 'Xray only: preconditions are their own Jira issues.' items: type: object properties: test_case_id: type: integer issue_key: type: string issue_url: type: string unresolved: type: array description: Sent, but the tool never answered, so whether these exist is unknown. Neither created nor failed — a retry looks each one up before re-sending, so it cannot duplicate. Show as "needs retry", not as an error. items: type: object properties: test_case_id: type: integer detail: type: string failures: type: array items: type: object properties: test_case_id: type: integer error: type: string warnings: type: array items: type: object properties: test_case_id: type: integer warning: type: string '404': description: Run not found for this TCG content: application/json: schema: type: object properties: error: type: string example: not_found "/api/v1/tcg": get: summary: List all test case generation requests operationId: tcgIndex tags: - TCG description: Retrieves all test case generation requests for the authenticated user, ordered by creation date (newest first) security: - session_cookie: [] responses: '200': description: Test case generation requests retrieved successfully content: application/json: schema: type: array items: type: object properties: id: type: string example: tcg_123 user_id: type: string example: '12345' status: type: string example: completed enum: - pending - processing - completed - failed created_at: type: string format: date-time updated_at: type: string format: date-time '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string example: unauthorized post: summary: Create test case generation request operationId: tcgCreate tags: - TCG description: Creates a new AI-powered test case generation request. Requires either an attachment, scan_id, or page_url parameter. security: - session_cookie: [] parameters: [] responses: '201': description: Test case generation request created successfully content: application/json: schema: type: object properties: id: type: string example: tcg_123 user_id: type: string example: '12345' status: type: string example: pending created_at: type: string format: date-time '400': description: Bad request - missing required parameters '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string example: unauthorized '422': description: Unprocessable entity - validation failed content: application/json: schema: type: object properties: error: type: string example: Validation error message '429': description: Rate limit exceeded - too many generations for this user (LV-3308) content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Rate limit exceeded message: type: string example: Rate limit exceeded, Too many requests. Please try again later. requestBody: content: multipart/form-data: schema: type: string format: binary description: Requirement document for test case generation. PDF; XLSX where enabled. Max 25MB. "/api/v1/tcg/{id}": delete: summary: Delete test case CSV export operationId: tcgDelete tags: - TCG description: Deletes the CSV export file for a specific test case generation request security: - session_cookie: [] parameters: - name: id in: path required: true description: ID of the test case generation request schema: type: string responses: '200': description: CSV export deleted successfully content: application/json: schema: type: object properties: message: type: string example: CSV export deleted successfully '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string example: unauthorized '422': description: Unprocessable entity - deletion failed content: application/json: schema: type: object properties: error: type: string example: Failed to delete CSV export "/api/v1/tcg/validate-permissions": get: summary: Validate user permissions for TCG operationId: tcgValidatePermissions tags: - TCG description: Checks if the current user has access to test case generation features security: - session_cookie: [] responses: '200': description: Permission check completed content: application/json: schema: type: object properties: has_access: type: boolean example: true '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string example: unauthorized "/api/v1/tcg/webhook": post: summary: Webhook for test case generation results operationId: tcgWebhook tags: - TCG description: Receives and stores test case generation results from AI service. Requires HTTP Basic Authentication. security: - wdt_ai_basic: [] parameters: [] responses: '200': description: Test case generation results stored successfully content: application/json: schema: type: object properties: message: type: string example: Test cases stored successfully '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string example: unauthorized '422': description: Unprocessable entity - storage failed content: application/json: schema: type: object properties: error: type: string example: Failed to store test cases requestBody: content: application/json: schema: type: object properties: user_id: type: string example: '12345' tcg_id: type: string example: tcg_123 test_cases: type: array items: type: object properties: title: type: string example: Test login functionality steps: type: array items: type: string required: - user_id "/api/v1/tcg/test-case-steps-webhook": post: summary: Webhook for test case steps operationId: tcgTestCaseStepsWebhook tags: - TCG description: Receives and stores individual test case steps from AI service. Requires HTTP Basic Authentication. security: - wdt_ai_basic: [] parameters: [] responses: '200': description: Test case steps stored successfully content: application/json: schema: type: object properties: message: type: string example: Test case steps stored successfully '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string example: unauthorized '422': description: Unprocessable entity - storage failed content: application/json: schema: type: object properties: error: type: string example: Failed to store test case steps requestBody: content: application/json: schema: type: object properties: user_id: type: string example: '12345' tcg_id: type: string example: tcg_123 steps: type: array items: type: object properties: step_number: type: integer example: 1 description: type: string example: Navigate to login page expected_result: type: string example: Login page is displayed required: - user_id "/api/v1/tcg/{id}/mark-downloaded": post: summary: Mark test cases as downloaded operationId: tcgMarkDownloaded tags: - TCG description: Marks a test case generation request as downloaded by the user security: - session_cookie: [] parameters: - name: id in: path required: true description: ID of the test case generation request schema: type: string responses: '200': description: Marked as downloaded successfully content: application/json: schema: type: object properties: message: type: string example: Test cases marked as downloaded '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string example: unauthorized '422': description: Unprocessable entity - operation failed content: application/json: schema: type: object properties: error: type: string example: Failed to mark as downloaded "/api/v1/tcg/{id}/stop": post: summary: Stop test case generation operationId: tcgStop tags: - TCG description: Stops an in-progress test case generation request security: - session_cookie: [] parameters: - name: id in: path required: true description: ID of the test case generation request schema: type: string responses: '200': description: Test case generation stopped successfully content: application/json: schema: type: object properties: message: type: string example: Test case generation stopped '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string example: unauthorized '422': description: Unprocessable entity - operation failed content: application/json: schema: type: object properties: error: type: string example: Failed to stop test case generation "/api/v1/tcg/{id}/refine": post: summary: Refine generated test cases with a follow-up prompt operationId: tcgRefine tags: - TCG description: 'Refines an already-completed test case generation in place: the TCG service iterates on the prior context (same contextReferenceKey) using the given prompt, and the report is rebuilt through the existing webhook pipeline (LV-3525).' security: - session_cookie: [] parameters: - name: id in: path required: true description: ID of the completed test case generation to refine schema: type: string responses: '200': description: Refinement started successfully content: application/json: schema: type: object properties: data: type: object properties: id: type: string example: '123' attributes: type: object properties: status: type: string example: processing refining: type: boolean example: true '422': description: Unprocessable entity - refinement rejected content: application/json: schema: type: object properties: error: type: string example: Only completed test generations can be refined requestBody: content: application/json: schema: type: object properties: user_prompt: type: string example: Add negative and edge cases, change login priorities to P0 required: - user_prompt required: true "/api/v1/toolkit_ai/check-spelling": post: summary: Check spelling for HTML content operationId: toolkitAiCheckSpelling tags: - Toolkit AI description: Runs spell check on provided HTML content and returns suggestions security: - session_cookie: [] parameters: [] responses: '200': description: Spell check completed successfully content: application/json: schema: type: object properties: success: type: boolean example: true response: type: object properties: suggestions: type: array items: type: string example: - world '400': description: Bad request - html_file missing content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: html_file is required '403': description: Forbidden - user lacks access content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: You do not have access to AI Spell Checker '429': description: Too many requests - rate limited content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Rate limit exceeded message: type: string example: Rate limit exceeded '500': description: Internal server error content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Unexpected failure requestBody: content: application/json: schema: type: object properties: html_file: type: string example: "Hello wrld" language: type: string example: en model: type: string example: gpt-4o page_url: type: string example: https://example.com/page required: - html_file "/api/v1/toolkit_ai/check-text-spelling": post: summary: Check spelling for text sentences operationId: toolkitAiCheckTextSpelling tags: - Toolkit AI description: Runs spell check on a list of sentences security: - session_cookie: [] parameters: [] responses: '200': description: Spell check completed successfully content: application/json: schema: type: object properties: success: type: boolean example: true response: type: object properties: suggestions: type: array items: type: string example: - Hello world '400': description: Bad request - sentences array missing content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: sentences array is required '403': description: Forbidden - user lacks access content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: You do not have access to AI Spell Checker '429': description: Too many requests - rate limited content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Rate limit exceeded message: type: string example: Rate limit exceeded '500': description: Internal server error content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Unexpected failure requestBody: content: application/json: schema: type: object properties: sentences: type: array items: type: string example: - Helo wrld language: type: string example: en model: type: string example: gpt-4o page_url: type: string example: https://example.com/page custom_dictionary: type: array items: type: string example: - BrowserStack required: - sentences "/api/v1/toolkit_ai/fill-form": post: summary: Fill form content using AI operationId: toolkitAiFillForm tags: - Toolkit AI description: Uses AI to fill a form with provided parameters security: - session_cookie: [] parameters: [] responses: '200': description: Form filled successfully content: application/json: schema: type: object properties: success: type: boolean example: true response: type: object example: fields: - name: first_name value: John limit_remaining: 4 '402': description: Form filler quota exhausted content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Form filler quota exhausted code: type: string example: quota_exhausted '403': description: Forbidden - user lacks access content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: You do not have access to AI Form Filler code: type: string example: forbidden '500': description: Internal server error content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Unexpected failure requestBody: content: application/json: schema: type: object properties: fields: type: array items: type: object properties: name: type: string example: first_name value: type: string example: John "/api/v1/toolkit_ai/generate-dataset": post: summary: Generate a test dataset for a form operationId: toolkitAiGenerateDataset tags: - Toolkit AI description: Generates N cohesive rows of synthetic test data for a form, honouring per-field natural-language rules (LV-3626). Also serves column regeneration via targetFields + existingRows. security: - session_cookie: [] parameters: [] responses: '200': description: Dataset generated successfully content: application/json: schema: type: object properties: success: type: boolean example: true response: type: object example: success: true message: Dataset generated successfully rows: - phone: "+91 9812345670" - phone: "+91 9876501234" notes: processing_time_ms: 6100 limit_remaining: 3 '400': description: Invalid request payload content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: fields is required code: type: string example: error '402': description: Form filler quota exhausted content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Form filler quota exhausted code: type: string example: quota_exhausted '403': description: Forbidden - user lacks access content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: You do not have access to AI Form Filler code: type: string example: forbidden requestBody: content: application/json: schema: type: object required: - fields properties: fields: type: array items: type: object properties: name: type: string example: phone type: type: string example: tel label: type: string example: Phone number rule: type: string example: Indian phone numbers, +91, 10 digits options: type: array items: type: string rowCount: type: integer example: 20 formContext: type: string example: Signup form locale: type: string example: IN targetFields: type: array items: type: string existingRows: type: array items: type: object "/api/v1/user/get-user-profile": get: summary: Get current user profile operationId: userGetUserProfile tags: - User description: Retrieves the profile information of the currently authenticated user security: - session_cookie: [] responses: '200': description: Free user profile carries form_fills.remaining inside fencing content: application/json: schema: type: object properties: id: type: integer example: 12345 email: type: string example: user@example.com name: type: string example: John Doe browserstack_user_id: type: string example: bs_12345 '401': description: Unauthorized - user not authenticated content: application/json: schema: "$ref": "#/components/schemas/Error" "/api/v1/user/get-user-favorite-tools": get: summary: Get user favorite tools operationId: userGetUserFavoriteTools tags: - User description: Retrieves the favorite tools for the currently authenticated user security: - session_cookie: [] responses: '200': description: User favorite tools retrieved successfully content: application/json: schema: type: object properties: success: type: boolean example: true user_id: type: integer example: 123 favorite_tools: type: array items: type: object properties: rank: type: integer example: 1 tool_name: type: string example: BugCapture required: - rank - tool_name required: - success - user_id - favorite_tools '500': description: Internal server error for actual errors content: application/json: schema: type: object properties: success: type: boolean example: false message: type: string example: An error occurred while fetching favorite tools user_id: type: integer example: 123 favorite_tools: type: array items: {} example: [] required: - success - message - user_id - favorite_tools '401': description: Unauthorized - user not authenticated content: application/json: schema: "$ref": "#/components/schemas/Error" "/api/v1/user/expire-session-user": post: summary: Expire all user sessions operationId: userExpireSessionUser tags: - User description: Expires all active sessions for a given user. Used for security and session management. Requires API authentication. security: - basic_auth: [] parameters: [] responses: '200': description: User not found content: application/json: schema: type: object properties: success: type: boolean example: false message: type: string example: User not found '401': description: Unauthorized - API authentication failed content: application/json: schema: "$ref": "#/components/schemas/Error" requestBody: content: application/json: schema: type: object properties: data: type: object properties: id: type: string example: bs_12345 description: BrowserStack user ID required: - data "/api/v1/user/logout": get: summary: Logout current user operationId: userLogout tags: - User description: Logs out the current user by clearing their session and cookies security: - session_cookie: [] parameters: - name: Sec-Fetch-Site in: header required: false description: Fetch Metadata request header set by the browser. A value of `cross-site` is always refused; the extension reports `none` and the dashboard `same-origin`, so neither is affected. schema: type: string example: cross-site responses: '302': description: User logged out successfully - redirects to logout page content: text/html: schema: type: string '401': description: Unauthorized - user not authenticated content: text/html: schema: "$ref": "#/components/schemas/Error" '403': description: Forbidden - cross-site forced logout blocked (LV-3306) content: text/html: schema: type: string "/api/v1/visual-compare/comparisons": post: summary: Create a Percy comparison between a reference image and a tab capture operationId: visualCompareCreate tags: - Visual Compare description: Uploads a reference image (Figma frame or user upload) and a tab capture, uploads the reference as a Percy build and waits for it to finish, then uploads the capture on the same branch and starts the comparison. Both images must arrive pre-normalized to identical CSS-pixel dimensions (LV-3590). security: - session_cookie: [] parameters: [] responses: '201': description: Comparison started content: application/json: schema: type: object properties: data: type: object properties: comparison_id: type: string example: '13' build_id: type: string example: '11' baseline_build_id: type: string example: '9' '422': description: Comparison rejected content: application/json: schema: type: object properties: error: type: string requestBody: content: multipart/form-data: schema: type: object properties: reference: type: string format: binary description: Reference image (the baseline) capture: type: string format: binary description: Tab capture (the head image) width: type: integer example: 1280 height: type: integer example: 800 required: - reference - capture - width - height required: true description: Both images, pre-normalized to the same CSS-pixel size, plus that size "/api/v1/visual-compare/comparisons/{id}": get: summary: Fetch the state and result of a comparison operationId: visualCompareShow tags: - Visual Compare security: - session_cookie: [] parameters: - name: id in: path required: true schema: type: string responses: '200': description: Comparison state content: application/json: schema: type: object properties: data: type: object properties: state: type: string example: finished diff_ratio: type: number example: 0.021 nullable: true raw: type: object '422': description: Comparison lookup failed content: application/json: schema: type: object properties: error: type: string "/api/v1/visual-compare/comparisons/{id}/ignore-prompt": post: summary: Draft an AI prompt that ignores differences like the picked one operationId: visualCompareIgnorePrompt tags: - Visual Compare description: 'Ask AI, step one: given the ids of the AI regions the user picked on a finished comparison, returns the prompt Percy AI drafted to ignore similar differences. Waits for the draft (a few seconds).' security: - session_cookie: [] parameters: - name: id in: path required: true schema: type: string responses: '200': description: Prompt drafted content: application/json: schema: type: object properties: data: type: object properties: prompt: type: string example: Ignore changes in icon colours. mode: type: string example: ignore '422': description: Prompt could not be drafted content: application/json: schema: type: object properties: error: type: string requestBody: content: application/json: schema: type: object properties: region_ids: type: array items: type: string example: - I0R7PC description: Percy AI region ids of the differences to ignore (alphanumeric) required: - region_ids "/api/v1/visual-compare/comparisons/{id}/ai-recompute": post: summary: Run an AI prompt on a comparison operationId: visualCompareAiRecompute tags: - Visual Compare description: 'Ask AI, step two: re-runs the AI pass on the comparison with the given prompt (mode `ignore` or `unignore`). Percy processes it asynchronously; poll `/ai-job`, then re-read the comparison for the updated regions.' security: - session_cookie: [] parameters: - name: id in: path required: true schema: type: string responses: '200': description: Recompute started content: application/json: schema: type: object properties: data: type: object properties: comparison_id: type: string example: '13' prompt: type: string mode: type: string example: ignore '422': description: Recompute refused content: application/json: schema: type: object properties: error: type: string requestBody: content: application/json: schema: type: object properties: prompt: type: string example: Ignore changes in icon colours. mode: type: string enum: - ignore - unignore example: ignore required: - prompt "/api/v1/visual-compare/comparisons/{id}/ai-job": get: summary: Check whether an AI recompute has finished operationId: visualCompareAiJob tags: - Visual Compare security: - session_cookie: [] parameters: - name: id in: path required: true schema: type: string responses: '200': description: Job state content: application/json: schema: type: object properties: data: type: object properties: done: type: boolean example: true error: type: string nullable: true '422': description: Job lookup failed content: application/json: schema: type: object properties: error: type: string servers: - url: https://toolkit.browserstack.com description: Production server - url: https://toolkit.bsstag.com description: Staging server - url: http://localhost:3000 description: Development server components: securitySchemes: session_cookie: type: apiKey in: cookie name: _wdt_rails_session description: Session-based authentication using Rails session cookie basic_auth: type: http scheme: basic description: HTTP Basic Authentication for webhook endpoints wdt_ai_basic: type: http scheme: basic description: HTTP Basic Authentication for TCG service webhooks (WDT AI client credentials) schemas: Error: type: object properties: success: type: boolean example: false error: type: string example: An error occurred message: type: string example: Detailed error message tags: - name: Authentication description: SSO authentication endpoints - name: User description: User management and synchronization - name: Group description: Group data synchronization - name: TCG description: Test Case Generation (AI-powered) - name: Atlassian description: Atlassian (Jira/Confluence) integration - name: Integration description: Third-party integrations management - name: Automation description: Automation environment configuration - name: Bug Capture description: Bug capture and session management - name: Location Simulator description: Geolocation testing with WonderProxy - name: Domain Blacklist description: Read-only access to the Redis-backed domain blacklist - name: Figma description: Figma OAuth integration for visual overlay