{ "openapi": "3.1.0", "info": { "title": "AI Authoring API", "version": "1.0.0", "description": "The AI Test Authoring API allows you to manage AI-authored test cases, test suites, and test schedules. Use these methods to create, retrieve, update, delete, and run your AI-authored tests programmatically.\n\nRefer to [Getting Started](/dev/api) for Authentication and Server information.\n\n## What You'll Need\n\n- A Sauce Labs enterprise account ([Log in](https://accounts.saucelabs.com/am/XUI/#login/))\n- Your Sauce Labs [username and access key](https://app.saucelabs.com/user-settings)" }, "servers": [ { "url": "https://api.us-west-1.saucelabs.com/ai-authoring/v1", "description": "US West" }, { "url": "https://api.eu-central-1.saucelabs.com/ai-authoring/v1", "description": "EU Central" }, { "url": "https://api.us-east-4.saucelabs.com/ai-authoring/v1", "description": "US East" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "schemas": {}, "parameters": {} }, "paths": { "/storage/{id}": { "get": { "tags": [ "Storage" ], "summary": "Get artifact file", "description": "Downloads a stored artifact (e.g. screenshot) by its UUID. Supports both dashed and dashless UUID formats.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Artifact UUID (accepts both dashed and dashless formats)" }, "required": true, "description": "Artifact UUID (accepts both dashed and dashless formats)", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Artifact file stream", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid path parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_PARAMS" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Missing or invalid Bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "UNAUTHORIZED" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Artifact not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "FILE_NOT_FOUND" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } } } } }, "/testcases": { "get": { "tags": [ "Test Cases" ], "summary": "List test cases", "description": "Returns a paginated list of test cases. Supports filtering by search term, date range, user, team, and test suite.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Case-insensitive search term matched against the test case name" }, "required": false, "description": "Case-insensitive search term matched against the test case name", "name": "search", "in": "query" }, { "schema": { "type": "string", "description": "ISO 8601 start date filter — only return test cases created on or after this date" }, "required": false, "description": "ISO 8601 start date filter — only return test cases created on or after this date", "name": "startDate", "in": "query" }, { "schema": { "type": "string", "description": "ISO 8601 end date filter — only return test cases created on or before this date" }, "required": false, "description": "ISO 8601 end date filter — only return test cases created on or before this date", "name": "endDate", "in": "query" }, { "schema": { "type": "string", "description": "Filter by creator user UUID" }, "required": false, "description": "Filter by creator user UUID", "name": "userId", "in": "query" }, { "schema": { "type": "string", "description": "Filter by team UUID" }, "required": false, "description": "Filter by team UUID", "name": "teamId", "in": "query" }, { "schema": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "Filter by test suite UUID(s). Pass \"null\" to find unassigned test cases. Accepts a single value or an array." }, "required": false, "description": "Filter by test suite UUID(s). Pass \"null\" to find unassigned test cases. Accepts a single value or an array.", "name": "testSuiteId", "in": "query" }, { "schema": { "type": "integer", "description": "Number of results to skip (for offset-based pagination). Defaults to 0." }, "required": false, "description": "Number of results to skip (for offset-based pagination). Defaults to 0.", "name": "skip", "in": "query" }, { "schema": { "type": "integer", "description": "Maximum number of results to return. Set to 0 to only retrieve the total count." }, "required": false, "description": "Maximum number of results to return. Set to 0 to only retrieve the total count.", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Paginated list of test cases", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Test case ObjectId (24-character hex string)" }, "orgId": { "type": "string", "description": "Sauce Labs organization ID that owns this test case" }, "creatorUserId": { "type": "string", "description": "UUID of the user who originally created the test case" }, "creatorUserName": { "type": [ "string", "null" ], "description": "Display name of the creator at the time of creation" }, "lastModifierUserId": { "type": "string", "description": "UUID of the user who last modified the test case" }, "lastModifierUserName": { "type": [ "string", "null" ], "description": "Display name of the last modifier" }, "name": { "type": "string", "description": "Human-readable test case name" }, "revisions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Revision UUID" }, "intent": { "type": "string", "description": "Original natural language intent provided by the user" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique step identifier within the revision" }, "tool": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "go_to_url" ] }, "args": { "type": "object", "properties": { "reasoning": { "type": "string", "description": "AI reasoning for performing this action" }, "url": { "type": "string", "description": "Target URL to navigate to" } }, "required": [ "reasoning", "url" ] } }, "required": [ "type", "args" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "switch_window" ] }, "args": { "type": "object", "properties": { "reasoning": { "type": "string", "description": "AI reasoning for performing this action" }, "matcher": { "type": "string", "description": "Window title or URL matcher" } }, "required": [ "reasoning" ] } }, "required": [ "type", "args" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "enter_key_submit" ] }, "args": { "type": "object", "properties": { "reasoning": { "type": "string", "description": "AI reasoning for performing this action" } }, "required": [ "reasoning" ] } }, "required": [ "type", "args" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "pause" ] }, "args": { "type": "object", "properties": { "reasoning": { "type": "string", "description": "AI reasoning for performing this action" }, "time": { "type": "number", "description": "Pause duration in milliseconds" } }, "required": [ "reasoning", "time" ] } }, "required": [ "type", "args" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "click" ] }, "args": { "type": "object", "properties": { "reasoning": { "type": "string", "description": "AI reasoning for performing this action" }, "xpath": { "type": "string", "description": "XPath selector (deprecated, use selector)" }, "selector": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "css" ] }, "value": { "type": "string" }, "index": { "type": "number" } }, "required": [ "type", "value" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "xpath" ] }, "value": { "type": "string" }, "index": { "type": "number" } }, "required": [ "type", "value" ] } ], "description": "Element selector (CSS or XPath)" } }, "required": [ "reasoning", "selector" ] } }, "required": [ "type", "args" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "input_text" ] }, "args": { "type": "object", "properties": { "reasoning": { "type": "string", "description": "AI reasoning for performing this action" }, "xpath": { "type": "string", "description": "XPath selector (deprecated, use selector)" }, "selector": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "css" ] }, "value": { "type": "string" }, "index": { "type": "number" } }, "required": [ "type", "value" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "xpath" ] }, "value": { "type": "string" }, "index": { "type": "number" } }, "required": [ "type", "value" ] } ], "description": "Element selector (CSS or XPath)" }, "text": { "type": "string", "description": "Text to type into the element" } }, "required": [ "reasoning", "selector", "text" ] } }, "required": [ "type", "args" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "scroll_document" ] }, "args": { "type": "object", "properties": { "reasoning": { "type": "string", "description": "AI reasoning for performing this action" }, "direction": { "type": "string", "enum": [ "down", "up", "left", "right" ] } }, "required": [ "reasoning", "direction" ] } }, "required": [ "type", "args" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "scroll_element" ] }, "args": { "type": "object", "properties": { "reasoning": { "type": "string", "description": "AI reasoning for performing this action" }, "xpath": { "type": "string", "description": "XPath selector (deprecated, use selector)" }, "selector": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "css" ] }, "value": { "type": "string" }, "index": { "type": "number" } }, "required": [ "type", "value" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "xpath" ] }, "value": { "type": "string" }, "index": { "type": "number" } }, "required": [ "type", "value" ] } ], "description": "Element selector (CSS or XPath)" }, "direction": { "type": "string", "enum": [ "down", "up", "left", "right" ] } }, "required": [ "reasoning", "selector", "direction" ] } }, "required": [ "type", "args" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "assert" ] }, "args": { "type": "object", "properties": { "reasoning": { "type": "string", "description": "AI reasoning for performing this action" }, "xpath": { "type": "string", "description": "XPath selector (deprecated, use selector)" }, "selector": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "css" ] }, "value": { "type": "string" }, "index": { "type": "number" } }, "required": [ "type", "value" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "xpath" ] }, "value": { "type": "string" }, "index": { "type": "number" } }, "required": [ "type", "value" ] } ], "description": "Element selector (CSS or XPath)" }, "not": { "type": "boolean", "description": "Negate the assertion" }, "matcher": { "type": "object", "properties": { "name": { "type": "string", "description": "Matcher function name (e.g. \"toBeVisible\", \"toHaveText\")" }, "args": { "type": "array", "items": {}, "description": "Matcher arguments (JSON values)" } }, "required": [ "name" ] } }, "required": [ "reasoning", "selector", "matcher" ] } }, "required": [ "type", "args" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "select" ] }, "args": { "type": "object", "properties": { "reasoning": { "type": "string", "description": "AI reasoning for performing this action" }, "xpath": { "type": "string", "description": "XPath selector (deprecated, use selector)" }, "selector": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "css" ] }, "value": { "type": "string" }, "index": { "type": "number" } }, "required": [ "type", "value" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "xpath" ] }, "value": { "type": "string" }, "index": { "type": "number" } }, "required": [ "type", "value" ] } ], "description": "Element selector (CSS or XPath)" }, "optionValue": { "type": "string", "description": "Value of the option to select" } }, "required": [ "reasoning", "selector", "optionValue" ] } }, "required": [ "type", "args" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "in_shadow_root" ] }, "args": { "type": "object", "properties": { "reasoning": { "type": "string", "description": "AI reasoning for performing this action" }, "xpath": { "type": "string", "description": "XPath selector (deprecated, use selector)" }, "selector": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "css" ] }, "value": { "type": "string" }, "index": { "type": "number" } }, "required": [ "type", "value" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "xpath" ] }, "value": { "type": "string" }, "index": { "type": "number" } }, "required": [ "type", "value" ] } ], "description": "Element selector (CSS or XPath)" }, "tool": { "type": "object", "description": "Nested tool invocation within shadow DOM" } }, "required": [ "reasoning", "selector" ] } }, "required": [ "type", "args" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "finish" ] }, "args": { "type": "object", "properties": { "reasoning": { "type": "string", "description": "AI reasoning for performing this action" } }, "required": [ "reasoning" ], "additionalProperties": {} } }, "required": [ "type", "args" ] } ], "description": "A single tool invocation within a test step" }, "result": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the tool action completed without error" }, "message": { "type": "string", "description": "Detailed result message or error description" } }, "required": [ "success" ] }, "screenshotUrl": { "type": "string", "description": "URL to the screenshot captured after executing this step" } }, "required": [ "id", "tool" ] }, "description": "Ordered sequence of test steps that make up this revision" }, "discoveredIntent": { "type": "string", "description": "AI-refined intent derived from the actual test execution" }, "description": { "type": "string", "description": "Auto-generated human-readable summary of what the revision tests" } }, "required": [ "id", "intent", "steps", "discoveredIntent", "description" ] }, "description": "Chronological list of test case revisions (latest last)" }, "creationDate": { "type": "string", "description": "ISO 8601 timestamp when the test case was created" }, "lastUpdateDate": { "type": "string", "description": "ISO 8601 timestamp of the most recent modification" }, "runSettings": { "type": "object", "properties": { "testUrl": { "type": [ "string", "null" ], "description": "Base URL the test navigates to" }, "scTunnelName": { "type": [ "string", "null" ], "description": "Sauce Connect tunnel name for accessing private sites" }, "primaryTarget": { "type": "object", "properties": { "capabilities": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "description": "W3C WebDriver capabilities (e.g. browserName, platformName, browserVersion)" }, "isRdc": { "type": "boolean", "description": "Whether this target runs on a real device (true) or an emulator/VM (false)" } }, "required": [ "capabilities", "isRdc" ] }, "runTargets": { "type": "array", "items": { "type": "object", "properties": { "capabilities": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "description": "W3C WebDriver capabilities (e.g. browserName, platformName, browserVersion)" }, "isRdc": { "type": "boolean", "description": "Whether this target runs on a real device (true) or an emulator/VM (false)" } }, "required": [ "capabilities", "isRdc" ] }, "description": "All configured browser/device targets for parallel execution" }, "lastBuildName": { "type": [ "string", "null" ], "description": "Most recently used Sauce Labs build name" } }, "required": [ "primaryTarget", "runTargets" ] }, "testSuiteId": { "type": "string", "description": "UUID of the test suite this test case belongs to, if any" } }, "required": [ "id", "orgId", "creatorUserId", "creatorUserName", "lastModifierUserId", "lastModifierUserName", "name", "revisions", "creationDate", "lastUpdateDate", "runSettings" ] }, "description": "Result items for the current page" }, "total": { "type": "number", "description": "Total number of matching items across all pages (independent of skip/limit)" } }, "required": [ "items", "total" ] } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid query string parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_QUERY" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Missing or invalid Bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "UNAUTHORIZED" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } } } } }, "/testcases/{id}": { "get": { "tags": [ "Test Cases" ], "summary": "Get a test case", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Test case ObjectId (24-character hex string)" }, "required": true, "description": "Test case ObjectId (24-character hex string)", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Test case details", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Test case ObjectId (24-character hex string)" }, "orgId": { "type": "string", "description": "Sauce Labs organization ID that owns this test case" }, "creatorUserId": { "type": "string", "description": "UUID of the user who originally created the test case" }, "creatorUserName": { "type": [ "string", "null" ], "description": "Display name of the creator at the time of creation" }, "lastModifierUserId": { "type": "string", "description": "UUID of the user who last modified the test case" }, "lastModifierUserName": { "type": [ "string", "null" ], "description": "Display name of the last modifier" }, "name": { "type": "string", "description": "Human-readable test case name" }, "revisions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Revision UUID" }, "intent": { "type": "string", "description": "Original natural language intent provided by the user" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique step identifier within the revision" }, "tool": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "go_to_url" ] }, "args": { "type": "object", "properties": { "reasoning": { "type": "string", "description": "AI reasoning for performing this action" }, "url": { "type": "string", "description": "Target URL to navigate to" } }, "required": [ "reasoning", "url" ] } }, "required": [ "type", "args" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "switch_window" ] }, "args": { "type": "object", "properties": { "reasoning": { "type": "string", "description": "AI reasoning for performing this action" }, "matcher": { "type": "string", "description": "Window title or URL matcher" } }, "required": [ "reasoning" ] } }, "required": [ "type", "args" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "enter_key_submit" ] }, "args": { "type": "object", "properties": { "reasoning": { "type": "string", "description": "AI reasoning for performing this action" } }, "required": [ "reasoning" ] } }, "required": [ "type", "args" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "pause" ] }, "args": { "type": "object", "properties": { "reasoning": { "type": "string", "description": "AI reasoning for performing this action" }, "time": { "type": "number", "description": "Pause duration in milliseconds" } }, "required": [ "reasoning", "time" ] } }, "required": [ "type", "args" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "click" ] }, "args": { "type": "object", "properties": { "reasoning": { "type": "string", "description": "AI reasoning for performing this action" }, "xpath": { "type": "string", "description": "XPath selector (deprecated, use selector)" }, "selector": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "css" ] }, "value": { "type": "string" }, "index": { "type": "number" } }, "required": [ "type", "value" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "xpath" ] }, "value": { "type": "string" }, "index": { "type": "number" } }, "required": [ "type", "value" ] } ], "description": "Element selector (CSS or XPath)" } }, "required": [ "reasoning", "selector" ] } }, "required": [ "type", "args" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "input_text" ] }, "args": { "type": "object", "properties": { "reasoning": { "type": "string", "description": "AI reasoning for performing this action" }, "xpath": { "type": "string", "description": "XPath selector (deprecated, use selector)" }, "selector": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "css" ] }, "value": { "type": "string" }, "index": { "type": "number" } }, "required": [ "type", "value" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "xpath" ] }, "value": { "type": "string" }, "index": { "type": "number" } }, "required": [ "type", "value" ] } ], "description": "Element selector (CSS or XPath)" }, "text": { "type": "string", "description": "Text to type into the element" } }, "required": [ "reasoning", "selector", "text" ] } }, "required": [ "type", "args" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "scroll_document" ] }, "args": { "type": "object", "properties": { "reasoning": { "type": "string", "description": "AI reasoning for performing this action" }, "direction": { "type": "string", "enum": [ "down", "up", "left", "right" ] } }, "required": [ "reasoning", "direction" ] } }, "required": [ "type", "args" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "scroll_element" ] }, "args": { "type": "object", "properties": { "reasoning": { "type": "string", "description": "AI reasoning for performing this action" }, "xpath": { "type": "string", "description": "XPath selector (deprecated, use selector)" }, "selector": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "css" ] }, "value": { "type": "string" }, "index": { "type": "number" } }, "required": [ "type", "value" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "xpath" ] }, "value": { "type": "string" }, "index": { "type": "number" } }, "required": [ "type", "value" ] } ], "description": "Element selector (CSS or XPath)" }, "direction": { "type": "string", "enum": [ "down", "up", "left", "right" ] } }, "required": [ "reasoning", "selector", "direction" ] } }, "required": [ "type", "args" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "assert" ] }, "args": { "type": "object", "properties": { "reasoning": { "type": "string", "description": "AI reasoning for performing this action" }, "xpath": { "type": "string", "description": "XPath selector (deprecated, use selector)" }, "selector": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "css" ] }, "value": { "type": "string" }, "index": { "type": "number" } }, "required": [ "type", "value" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "xpath" ] }, "value": { "type": "string" }, "index": { "type": "number" } }, "required": [ "type", "value" ] } ], "description": "Element selector (CSS or XPath)" }, "not": { "type": "boolean", "description": "Negate the assertion" }, "matcher": { "type": "object", "properties": { "name": { "type": "string", "description": "Matcher function name (e.g. \"toBeVisible\", \"toHaveText\")" }, "args": { "type": "array", "items": {}, "description": "Matcher arguments (JSON values)" } }, "required": [ "name" ] } }, "required": [ "reasoning", "selector", "matcher" ] } }, "required": [ "type", "args" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "select" ] }, "args": { "type": "object", "properties": { "reasoning": { "type": "string", "description": "AI reasoning for performing this action" }, "xpath": { "type": "string", "description": "XPath selector (deprecated, use selector)" }, "selector": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "css" ] }, "value": { "type": "string" }, "index": { "type": "number" } }, "required": [ "type", "value" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "xpath" ] }, "value": { "type": "string" }, "index": { "type": "number" } }, "required": [ "type", "value" ] } ], "description": "Element selector (CSS or XPath)" }, "optionValue": { "type": "string", "description": "Value of the option to select" } }, "required": [ "reasoning", "selector", "optionValue" ] } }, "required": [ "type", "args" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "in_shadow_root" ] }, "args": { "type": "object", "properties": { "reasoning": { "type": "string", "description": "AI reasoning for performing this action" }, "xpath": { "type": "string", "description": "XPath selector (deprecated, use selector)" }, "selector": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "css" ] }, "value": { "type": "string" }, "index": { "type": "number" } }, "required": [ "type", "value" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "xpath" ] }, "value": { "type": "string" }, "index": { "type": "number" } }, "required": [ "type", "value" ] } ], "description": "Element selector (CSS or XPath)" }, "tool": { "type": "object", "description": "Nested tool invocation within shadow DOM" } }, "required": [ "reasoning", "selector" ] } }, "required": [ "type", "args" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "finish" ] }, "args": { "type": "object", "properties": { "reasoning": { "type": "string", "description": "AI reasoning for performing this action" } }, "required": [ "reasoning" ], "additionalProperties": {} } }, "required": [ "type", "args" ] } ], "description": "A single tool invocation within a test step" }, "result": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the tool action completed without error" }, "message": { "type": "string", "description": "Detailed result message or error description" } }, "required": [ "success" ] }, "screenshotUrl": { "type": "string", "description": "URL to the screenshot captured after executing this step" } }, "required": [ "id", "tool" ] }, "description": "Ordered sequence of test steps that make up this revision" }, "discoveredIntent": { "type": "string", "description": "AI-refined intent derived from the actual test execution" }, "description": { "type": "string", "description": "Auto-generated human-readable summary of what the revision tests" } }, "required": [ "id", "intent", "steps", "discoveredIntent", "description" ] }, "description": "Chronological list of test case revisions (latest last)" }, "creationDate": { "type": "string", "description": "ISO 8601 timestamp when the test case was created" }, "lastUpdateDate": { "type": "string", "description": "ISO 8601 timestamp of the most recent modification" }, "runSettings": { "type": "object", "properties": { "testUrl": { "type": [ "string", "null" ], "description": "Base URL the test navigates to" }, "scTunnelName": { "type": [ "string", "null" ], "description": "Sauce Connect tunnel name for accessing private sites" }, "primaryTarget": { "type": "object", "properties": { "capabilities": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "description": "W3C WebDriver capabilities (e.g. browserName, platformName, browserVersion)" }, "isRdc": { "type": "boolean", "description": "Whether this target runs on a real device (true) or an emulator/VM (false)" } }, "required": [ "capabilities", "isRdc" ] }, "runTargets": { "type": "array", "items": { "type": "object", "properties": { "capabilities": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "description": "W3C WebDriver capabilities (e.g. browserName, platformName, browserVersion)" }, "isRdc": { "type": "boolean", "description": "Whether this target runs on a real device (true) or an emulator/VM (false)" } }, "required": [ "capabilities", "isRdc" ] }, "description": "All configured browser/device targets for parallel execution" }, "lastBuildName": { "type": [ "string", "null" ], "description": "Most recently used Sauce Labs build name" } }, "required": [ "primaryTarget", "runTargets" ] }, "testSuiteId": { "type": "string", "description": "UUID of the test suite this test case belongs to, if any" } }, "required": [ "id", "orgId", "creatorUserId", "creatorUserName", "lastModifierUserId", "lastModifierUserName", "name", "revisions", "creationDate", "lastUpdateDate", "runSettings" ] } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid path parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_PARAMS" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Missing or invalid Bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "UNAUTHORIZED" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Test case not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "TEST_CASE_NOT_FOUND" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } } } }, "delete": { "tags": [ "Test Cases" ], "summary": "Delete a test case", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Test case ObjectId (24-character hex string)" }, "required": true, "description": "Test case ObjectId (24-character hex string)", "name": "id", "in": "path" } ], "responses": { "204": { "description": "Test case deleted" }, "400": { "description": "Invalid path parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_PARAMS" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Missing or invalid Bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "UNAUTHORIZED" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Test case not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "TEST_CASE_NOT_FOUND" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } } } } }, "/testcases/{id}/run": { "post": { "tags": [ "Test Cases" ], "summary": "Run a test case", "description": "Starts a test case run. Optionally target a specific revision by appending `/{revisionId}` to the path.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Test case ObjectId (24-character hex string)" }, "required": true, "description": "Test case ObjectId (24-character hex string)", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "buildName": { "type": [ "string", "null" ], "maxLength": 100, "description": "Sauce Labs build name to group the run under (max 100 characters)" }, "scTunnelName": { "type": [ "string", "null" ], "maxLength": 1000, "description": "Name of an active Sauce Connect tunnel to route traffic through" }, "targets": { "type": "array", "items": { "type": "object", "properties": { "capabilities": { "type": "object", "additionalProperties": true, "description": "W3C WebDriver capabilities object (e.g. browserName, platformName, browserVersion)" } }, "required": [ "capabilities" ] }, "description": "List of browser/device targets to run the test against. Each entry specifies a capabilities object." } } } } } }, "responses": { "200": { "description": "Test case run created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Test case run UUID" }, "orgId": { "type": "string", "description": "Sauce Labs organization ID" }, "teamId": { "type": "string", "description": "Team UUID that the run belongs to" }, "userId": { "type": "string", "description": "UUID of the user who initiated the run" }, "testCaseId": { "type": "string", "description": "ObjectId of the test case that was run" }, "build": { "type": "string", "description": "Sauce Labs build name grouping this run" }, "jobs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Sauce Labs job ID (used to view results in the Sauce Labs dashboard)" }, "target": { "type": "object", "properties": { "capabilities": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "description": "W3C WebDriver capabilities (e.g. browserName, platformName, browserVersion)" }, "isRdc": { "type": "boolean", "description": "Whether this target runs on a real device (true) or an emulator/VM (false)" } }, "required": [ "capabilities", "isRdc" ] }, "name": { "type": "string", "description": "Job name displayed in the Sauce Labs dashboard" }, "url": { "type": "string", "description": "Direct URL to the job in the Sauce Labs dashboard" }, "isRdc": { "type": "boolean", "description": "Whether the job ran on a real device" }, "success": { "type": "boolean", "description": "Whether all assertions in the job passed" }, "error": { "type": "string", "description": "Error message if the job failed or encountered an infrastructure issue" } }, "required": [ "id", "target", "name" ] }, "description": "Individual Sauce Labs job results (one per target)" }, "creationDate": { "type": "string", "description": "ISO 8601 timestamp when the run was created" }, "testUrl": { "type": "string", "description": "Base URL the test navigated to" } }, "required": [ "id", "orgId", "teamId", "userId", "testCaseId", "build", "jobs", "creationDate" ] } }, "required": [ "data" ] } } } }, "400": { "description": "- Invalid path parameters\n- Invalid request body\n- No run targets configured\n- Sauce Connect tunnel not found", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_PARAMS" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_BODY" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "NO_RUN_TARGETS" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "SC_TUNNEL_NOT_FOUND" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } ] } } } }, "401": { "description": "Missing or invalid Bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "UNAUTHORIZED" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } }, "404": { "description": "- Test case not found\n- Revision not found", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "TEST_CASE_NOT_FOUND" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "TEST_CASE_REVISION_NOT_FOUND" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } ] } } } } } } }, "/testcases/{id}/rename": { "post": { "tags": [ "Test Cases" ], "summary": "Rename a test case", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Test case ObjectId (24-character hex string)" }, "required": true, "description": "Test case ObjectId (24-character hex string)", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Human-readable test case name (1–255 characters)" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Updated test case", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Test case ObjectId (24-character hex string)" }, "orgId": { "type": "string", "description": "Sauce Labs organization ID that owns this test case" }, "creatorUserId": { "type": "string", "description": "UUID of the user who originally created the test case" }, "creatorUserName": { "type": [ "string", "null" ], "description": "Display name of the creator at the time of creation" }, "lastModifierUserId": { "type": "string", "description": "UUID of the user who last modified the test case" }, "lastModifierUserName": { "type": [ "string", "null" ], "description": "Display name of the last modifier" }, "name": { "type": "string", "description": "Human-readable test case name" }, "revisions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Revision UUID" }, "intent": { "type": "string", "description": "Original natural language intent provided by the user" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique step identifier within the revision" }, "tool": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "go_to_url" ] }, "args": { "type": "object", "properties": { "reasoning": { "type": "string", "description": "AI reasoning for performing this action" }, "url": { "type": "string", "description": "Target URL to navigate to" } }, "required": [ "reasoning", "url" ] } }, "required": [ "type", "args" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "switch_window" ] }, "args": { "type": "object", "properties": { "reasoning": { "type": "string", "description": "AI reasoning for performing this action" }, "matcher": { "type": "string", "description": "Window title or URL matcher" } }, "required": [ "reasoning" ] } }, "required": [ "type", "args" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "enter_key_submit" ] }, "args": { "type": "object", "properties": { "reasoning": { "type": "string", "description": "AI reasoning for performing this action" } }, "required": [ "reasoning" ] } }, "required": [ "type", "args" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "pause" ] }, "args": { "type": "object", "properties": { "reasoning": { "type": "string", "description": "AI reasoning for performing this action" }, "time": { "type": "number", "description": "Pause duration in milliseconds" } }, "required": [ "reasoning", "time" ] } }, "required": [ "type", "args" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "click" ] }, "args": { "type": "object", "properties": { "reasoning": { "type": "string", "description": "AI reasoning for performing this action" }, "xpath": { "type": "string", "description": "XPath selector (deprecated, use selector)" }, "selector": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "css" ] }, "value": { "type": "string" }, "index": { "type": "number" } }, "required": [ "type", "value" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "xpath" ] }, "value": { "type": "string" }, "index": { "type": "number" } }, "required": [ "type", "value" ] } ], "description": "Element selector (CSS or XPath)" } }, "required": [ "reasoning", "selector" ] } }, "required": [ "type", "args" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "input_text" ] }, "args": { "type": "object", "properties": { "reasoning": { "type": "string", "description": "AI reasoning for performing this action" }, "xpath": { "type": "string", "description": "XPath selector (deprecated, use selector)" }, "selector": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "css" ] }, "value": { "type": "string" }, "index": { "type": "number" } }, "required": [ "type", "value" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "xpath" ] }, "value": { "type": "string" }, "index": { "type": "number" } }, "required": [ "type", "value" ] } ], "description": "Element selector (CSS or XPath)" }, "text": { "type": "string", "description": "Text to type into the element" } }, "required": [ "reasoning", "selector", "text" ] } }, "required": [ "type", "args" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "scroll_document" ] }, "args": { "type": "object", "properties": { "reasoning": { "type": "string", "description": "AI reasoning for performing this action" }, "direction": { "type": "string", "enum": [ "down", "up", "left", "right" ] } }, "required": [ "reasoning", "direction" ] } }, "required": [ "type", "args" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "scroll_element" ] }, "args": { "type": "object", "properties": { "reasoning": { "type": "string", "description": "AI reasoning for performing this action" }, "xpath": { "type": "string", "description": "XPath selector (deprecated, use selector)" }, "selector": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "css" ] }, "value": { "type": "string" }, "index": { "type": "number" } }, "required": [ "type", "value" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "xpath" ] }, "value": { "type": "string" }, "index": { "type": "number" } }, "required": [ "type", "value" ] } ], "description": "Element selector (CSS or XPath)" }, "direction": { "type": "string", "enum": [ "down", "up", "left", "right" ] } }, "required": [ "reasoning", "selector", "direction" ] } }, "required": [ "type", "args" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "assert" ] }, "args": { "type": "object", "properties": { "reasoning": { "type": "string", "description": "AI reasoning for performing this action" }, "xpath": { "type": "string", "description": "XPath selector (deprecated, use selector)" }, "selector": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "css" ] }, "value": { "type": "string" }, "index": { "type": "number" } }, "required": [ "type", "value" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "xpath" ] }, "value": { "type": "string" }, "index": { "type": "number" } }, "required": [ "type", "value" ] } ], "description": "Element selector (CSS or XPath)" }, "not": { "type": "boolean", "description": "Negate the assertion" }, "matcher": { "type": "object", "properties": { "name": { "type": "string", "description": "Matcher function name (e.g. \"toBeVisible\", \"toHaveText\")" }, "args": { "type": "array", "items": {}, "description": "Matcher arguments (JSON values)" } }, "required": [ "name" ] } }, "required": [ "reasoning", "selector", "matcher" ] } }, "required": [ "type", "args" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "select" ] }, "args": { "type": "object", "properties": { "reasoning": { "type": "string", "description": "AI reasoning for performing this action" }, "xpath": { "type": "string", "description": "XPath selector (deprecated, use selector)" }, "selector": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "css" ] }, "value": { "type": "string" }, "index": { "type": "number" } }, "required": [ "type", "value" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "xpath" ] }, "value": { "type": "string" }, "index": { "type": "number" } }, "required": [ "type", "value" ] } ], "description": "Element selector (CSS or XPath)" }, "optionValue": { "type": "string", "description": "Value of the option to select" } }, "required": [ "reasoning", "selector", "optionValue" ] } }, "required": [ "type", "args" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "in_shadow_root" ] }, "args": { "type": "object", "properties": { "reasoning": { "type": "string", "description": "AI reasoning for performing this action" }, "xpath": { "type": "string", "description": "XPath selector (deprecated, use selector)" }, "selector": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "css" ] }, "value": { "type": "string" }, "index": { "type": "number" } }, "required": [ "type", "value" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "xpath" ] }, "value": { "type": "string" }, "index": { "type": "number" } }, "required": [ "type", "value" ] } ], "description": "Element selector (CSS or XPath)" }, "tool": { "type": "object", "description": "Nested tool invocation within shadow DOM" } }, "required": [ "reasoning", "selector" ] } }, "required": [ "type", "args" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "finish" ] }, "args": { "type": "object", "properties": { "reasoning": { "type": "string", "description": "AI reasoning for performing this action" } }, "required": [ "reasoning" ], "additionalProperties": {} } }, "required": [ "type", "args" ] } ], "description": "A single tool invocation within a test step" }, "result": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the tool action completed without error" }, "message": { "type": "string", "description": "Detailed result message or error description" } }, "required": [ "success" ] }, "screenshotUrl": { "type": "string", "description": "URL to the screenshot captured after executing this step" } }, "required": [ "id", "tool" ] }, "description": "Ordered sequence of test steps that make up this revision" }, "discoveredIntent": { "type": "string", "description": "AI-refined intent derived from the actual test execution" }, "description": { "type": "string", "description": "Auto-generated human-readable summary of what the revision tests" } }, "required": [ "id", "intent", "steps", "discoveredIntent", "description" ] }, "description": "Chronological list of test case revisions (latest last)" }, "creationDate": { "type": "string", "description": "ISO 8601 timestamp when the test case was created" }, "lastUpdateDate": { "type": "string", "description": "ISO 8601 timestamp of the most recent modification" }, "runSettings": { "type": "object", "properties": { "testUrl": { "type": [ "string", "null" ], "description": "Base URL the test navigates to" }, "scTunnelName": { "type": [ "string", "null" ], "description": "Sauce Connect tunnel name for accessing private sites" }, "primaryTarget": { "type": "object", "properties": { "capabilities": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "description": "W3C WebDriver capabilities (e.g. browserName, platformName, browserVersion)" }, "isRdc": { "type": "boolean", "description": "Whether this target runs on a real device (true) or an emulator/VM (false)" } }, "required": [ "capabilities", "isRdc" ] }, "runTargets": { "type": "array", "items": { "type": "object", "properties": { "capabilities": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "description": "W3C WebDriver capabilities (e.g. browserName, platformName, browserVersion)" }, "isRdc": { "type": "boolean", "description": "Whether this target runs on a real device (true) or an emulator/VM (false)" } }, "required": [ "capabilities", "isRdc" ] }, "description": "All configured browser/device targets for parallel execution" }, "lastBuildName": { "type": [ "string", "null" ], "description": "Most recently used Sauce Labs build name" } }, "required": [ "primaryTarget", "runTargets" ] }, "testSuiteId": { "type": "string", "description": "UUID of the test suite this test case belongs to, if any" } }, "required": [ "id", "orgId", "creatorUserId", "creatorUserName", "lastModifierUserId", "lastModifierUserName", "name", "revisions", "creationDate", "lastUpdateDate", "runSettings" ] } }, "required": [ "data" ] } } } }, "400": { "description": "- Invalid path parameters\n- Invalid request body", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_PARAMS" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_BODY" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } ] } } } }, "401": { "description": "Missing or invalid Bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "UNAUTHORIZED" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Test case not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "TEST_CASE_NOT_FOUND" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } } } } }, "/testcases/{id}/runs": { "get": { "tags": [ "Test Cases" ], "summary": "List test case runs", "description": "Returns a paginated list of runs for a specific test case.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Test case ObjectId (24-character hex string)" }, "required": true, "description": "Test case ObjectId (24-character hex string)", "name": "id", "in": "path" }, { "schema": { "type": "string", "description": "ISO 8601 start date filter — only return runs created on or after this date" }, "required": false, "description": "ISO 8601 start date filter — only return runs created on or after this date", "name": "startDate", "in": "query" }, { "schema": { "type": "string", "description": "ISO 8601 end date filter — only return runs created on or before this date" }, "required": false, "description": "ISO 8601 end date filter — only return runs created on or before this date", "name": "endDate", "in": "query" }, { "schema": { "type": "string", "description": "Filter runs by the UUID of the user who initiated them" }, "required": false, "description": "Filter runs by the UUID of the user who initiated them", "name": "userId", "in": "query" }, { "schema": { "type": "string", "description": "Filter runs by team UUID" }, "required": false, "description": "Filter runs by team UUID", "name": "teamId", "in": "query" }, { "schema": { "type": "string", "description": "Filter runs by test case ObjectId" }, "required": false, "description": "Filter runs by test case ObjectId", "name": "testCaseId", "in": "query" }, { "schema": { "type": "integer", "description": "Number of results to skip (for offset-based pagination). Defaults to 0." }, "required": false, "description": "Number of results to skip (for offset-based pagination). Defaults to 0.", "name": "skip", "in": "query" }, { "schema": { "type": "integer", "description": "Maximum number of results to return" }, "required": false, "description": "Maximum number of results to return", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Paginated list of test case runs", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Test case run UUID" }, "orgId": { "type": "string", "description": "Sauce Labs organization ID" }, "teamId": { "type": "string", "description": "Team UUID that the run belongs to" }, "userId": { "type": "string", "description": "UUID of the user who initiated the run" }, "testCaseId": { "type": "string", "description": "ObjectId of the test case that was run" }, "build": { "type": "string", "description": "Sauce Labs build name grouping this run" }, "jobs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Sauce Labs job ID (used to view results in the Sauce Labs dashboard)" }, "target": { "type": "object", "properties": { "capabilities": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "description": "W3C WebDriver capabilities (e.g. browserName, platformName, browserVersion)" }, "isRdc": { "type": "boolean", "description": "Whether this target runs on a real device (true) or an emulator/VM (false)" } }, "required": [ "capabilities", "isRdc" ] }, "name": { "type": "string", "description": "Job name displayed in the Sauce Labs dashboard" }, "url": { "type": "string", "description": "Direct URL to the job in the Sauce Labs dashboard" }, "isRdc": { "type": "boolean", "description": "Whether the job ran on a real device" }, "success": { "type": "boolean", "description": "Whether all assertions in the job passed" }, "error": { "type": "string", "description": "Error message if the job failed or encountered an infrastructure issue" } }, "required": [ "id", "target", "name" ] }, "description": "Individual Sauce Labs job results (one per target)" }, "creationDate": { "type": "string", "description": "ISO 8601 timestamp when the run was created" }, "testUrl": { "type": "string", "description": "Base URL the test navigated to" } }, "required": [ "id", "orgId", "teamId", "userId", "testCaseId", "build", "jobs", "creationDate" ] }, "description": "Result items for the current page" }, "total": { "type": "number", "description": "Total number of matching items across all pages (independent of skip/limit)" } }, "required": [ "items", "total" ] } }, "required": [ "data" ] } } } }, "400": { "description": "- Invalid path parameters\n- Invalid query string parameters", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_PARAMS" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_QUERY" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } ] } } } }, "401": { "description": "Missing or invalid Bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "UNAUTHORIZED" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } } } } }, "/testcases/{id}/runs/{runId}": { "get": { "tags": [ "Test Cases" ], "summary": "Get a test case run", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Test case ObjectId (24-character hex string)" }, "required": true, "description": "Test case ObjectId (24-character hex string)", "name": "id", "in": "path" }, { "schema": { "type": "string", "description": "Test case run UUID" }, "required": true, "description": "Test case run UUID", "name": "runId", "in": "path" } ], "responses": { "200": { "description": "Test case run details", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Test case run UUID" }, "orgId": { "type": "string", "description": "Sauce Labs organization ID" }, "teamId": { "type": "string", "description": "Team UUID that the run belongs to" }, "userId": { "type": "string", "description": "UUID of the user who initiated the run" }, "testCaseId": { "type": "string", "description": "ObjectId of the test case that was run" }, "build": { "type": "string", "description": "Sauce Labs build name grouping this run" }, "jobs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Sauce Labs job ID (used to view results in the Sauce Labs dashboard)" }, "target": { "type": "object", "properties": { "capabilities": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "description": "W3C WebDriver capabilities (e.g. browserName, platformName, browserVersion)" }, "isRdc": { "type": "boolean", "description": "Whether this target runs on a real device (true) or an emulator/VM (false)" } }, "required": [ "capabilities", "isRdc" ] }, "name": { "type": "string", "description": "Job name displayed in the Sauce Labs dashboard" }, "url": { "type": "string", "description": "Direct URL to the job in the Sauce Labs dashboard" }, "isRdc": { "type": "boolean", "description": "Whether the job ran on a real device" }, "success": { "type": "boolean", "description": "Whether all assertions in the job passed" }, "error": { "type": "string", "description": "Error message if the job failed or encountered an infrastructure issue" } }, "required": [ "id", "target", "name" ] }, "description": "Individual Sauce Labs job results (one per target)" }, "creationDate": { "type": "string", "description": "ISO 8601 timestamp when the run was created" }, "testUrl": { "type": "string", "description": "Base URL the test navigated to" } }, "required": [ "id", "orgId", "teamId", "userId", "testCaseId", "build", "jobs", "creationDate" ] } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid path parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_PARAMS" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Missing or invalid Bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "UNAUTHORIZED" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Test case run not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "TEST_CASE_RUN_NOT_FOUND" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } } } } }, "/testcases/generate": { "post": { "tags": [ "Test Cases" ], "summary": "Generate a test case", "description": "Kicks off an asynchronous test case generation task. Use `GET /testcases/generate/{taskId}` to poll for status.", "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Human-readable test case name (1–255 characters)" }, "testSuiteId": { "type": "string", "description": "UUID (dashed or dashless). Dashes are stripped automatically." }, "runSettings": { "type": "object", "properties": { "target": { "type": "object", "properties": { "capabilities": { "type": "object", "additionalProperties": true, "description": "W3C WebDriver capabilities object (e.g. browserName, platformName, browserVersion)" } }, "required": [ "capabilities" ] }, "testUrl": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Fully qualified URL to test against (max 2048 characters)" }, "scTunnelName": { "type": "string", "maxLength": 1000, "description": "Name of an active Sauce Connect tunnel to route traffic through" } }, "required": [ "target" ] }, "promptSettings": { "type": "object", "properties": { "intent": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "Natural language test prompt describing what the test should do (1–20 000 characters)" }, "maxSteps": { "type": "integer", "minimum": 1, "maximum": 200, "description": "Maximum number of AI actions during generation (1–200)." } }, "required": [ "intent" ] }, "timeout": { "type": "integer", "minimum": 60000, "maximum": 3600000, "description": "Generation timeout in milliseconds (from 1 minute to 1 hour)." } }, "required": [ "name", "runSettings", "promptSettings" ] } } } }, "responses": { "202": { "description": "Generation task accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "taskId": { "type": "string" } }, "required": [ "taskId" ], "description": "Generation task ID (UUID)" } }, "required": [ "data" ] } } } }, "400": { "description": "- Invalid request body\n- Test suite not found\n- Sauce Connect tunnel not found", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_BODY" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "TEST_SUITE_NOT_FOUND" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "SC_TUNNEL_NOT_FOUND" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } ] } } } }, "401": { "description": "Missing or invalid Bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "UNAUTHORIZED" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } } } } }, "/testcases/generate/{taskId}": { "get": { "tags": [ "Test Cases" ], "summary": "Get test case generation status", "description": "Returns the current status of an asynchronous generation task. On completion, includes the generated test case id; on failure, includes the underlying task error.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Task ID" }, "required": true, "description": "Task ID", "name": "taskId", "in": "path" } ], "responses": { "200": { "description": "Current generation task status", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": [ "QUEUED" ] } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "IN_PROGRESS" ] } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "COMPLETED" ] }, "testCaseId": { "type": "string" } }, "required": [ "status", "testCaseId" ] }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "FAILED" ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "status", "error" ] } ] } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid path parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_PARAMS" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Missing or invalid Bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "UNAUTHORIZED" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Generation task not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "TEST_CASE_GENERATION_TASK_NOT_FOUND" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } } } } }, "/testsuites": { "get": { "tags": [ "Test Suites" ], "summary": "List test suites", "description": "Returns a paginated list of test suites. Supports filtering by IDs, search term, date range, user, and team.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string" }, "description": "Filter by specific test suite UUID(s). Accepts a single value or an array." }, "required": false, "description": "Filter by specific test suite UUID(s). Accepts a single value or an array.", "name": "ids", "in": "query" }, { "schema": { "type": "string", "description": "Case-insensitive search term matched against the suite name" }, "required": false, "description": "Case-insensitive search term matched against the suite name", "name": "search", "in": "query" }, { "schema": { "type": "string", "description": "ISO 8601 start date filter — only return suites created on or after this date" }, "required": false, "description": "ISO 8601 start date filter — only return suites created on or after this date", "name": "startDate", "in": "query" }, { "schema": { "type": "string", "description": "ISO 8601 end date filter — only return suites created on or before this date" }, "required": false, "description": "ISO 8601 end date filter — only return suites created on or before this date", "name": "endDate", "in": "query" }, { "schema": { "type": "string", "description": "Filter by creator user UUID" }, "required": false, "description": "Filter by creator user UUID", "name": "userId", "in": "query" }, { "schema": { "type": "string", "description": "Filter by team UUID" }, "required": false, "description": "Filter by team UUID", "name": "teamId", "in": "query" }, { "schema": { "type": "integer", "description": "Number of results to skip (for offset-based pagination). Defaults to 0." }, "required": false, "description": "Number of results to skip (for offset-based pagination). Defaults to 0.", "name": "skip", "in": "query" }, { "schema": { "type": "integer", "description": "Maximum number of results to return" }, "required": false, "description": "Maximum number of results to return", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Paginated list of test suites", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Test suite UUID" }, "orgId": { "type": "string", "description": "Sauce Labs organization ID" }, "teamId": { "type": "string", "description": "Team UUID that owns the suite" }, "name": { "type": "string", "description": "Human-readable suite name" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Free-form tags for categorization and filtering" }, "creationDate": { "type": "string", "description": "ISO 8601 timestamp when the suite was created" }, "lastUpdate": { "type": "string", "description": "ISO 8601 timestamp of the most recent modification" }, "creatorUserId": { "type": "string", "description": "UUID of the user who created the suite" }, "creatorUserName": { "type": [ "string", "null" ], "description": "Display name of the creator" }, "lastModifierUserId": { "type": "string", "description": "UUID of the user who last modified the suite" }, "lastModifierUserName": { "type": [ "string", "null" ], "description": "Display name of the last modifier" }, "testCaseCount": { "type": "number", "description": "Number of test cases currently in the suite" } }, "required": [ "id", "orgId", "teamId", "name", "tags", "creationDate", "lastUpdate", "creatorUserId", "creatorUserName", "lastModifierUserId", "lastModifierUserName", "testCaseCount" ] }, "description": "Result items for the current page" }, "total": { "type": "number", "description": "Total number of matching items across all pages (independent of skip/limit)" } }, "required": [ "items", "total" ] } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid query string parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_QUERY" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Missing or invalid Bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "UNAUTHORIZED" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } } } }, "post": { "tags": [ "Test Suites" ], "summary": "Create a test suite", "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Human-readable suite name (1–255 characters)" }, "tags": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": "Free-form tags for categorization (each tag 1–100 characters)" }, "testCases": { "type": "array", "items": { "type": "string", "description": "24-character hex MongoDB ObjectId" }, "description": "Test case ObjectIds to include in the suite" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Created test suite", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Test suite UUID" }, "orgId": { "type": "string", "description": "Sauce Labs organization ID" }, "teamId": { "type": "string", "description": "Team UUID that owns the suite" }, "name": { "type": "string", "description": "Human-readable suite name" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Free-form tags for categorization and filtering" }, "creationDate": { "type": "string", "description": "ISO 8601 timestamp when the suite was created" }, "lastUpdate": { "type": "string", "description": "ISO 8601 timestamp of the most recent modification" }, "creatorUserId": { "type": "string", "description": "UUID of the user who created the suite" }, "creatorUserName": { "type": [ "string", "null" ], "description": "Display name of the creator" }, "lastModifierUserId": { "type": "string", "description": "UUID of the user who last modified the suite" }, "lastModifierUserName": { "type": [ "string", "null" ], "description": "Display name of the last modifier" }, "testCaseCount": { "type": "number", "description": "Number of test cases currently in the suite" } }, "required": [ "id", "orgId", "teamId", "name", "tags", "creationDate", "lastUpdate", "creatorUserId", "creatorUserName", "lastModifierUserId", "lastModifierUserName", "testCaseCount" ] } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid request body", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_BODY" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Missing or invalid Bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "UNAUTHORIZED" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } }, "404": { "description": "One or more test cases not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "TEST_CASES_NOT_FOUND" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } } } } }, "/testsuites/{id}": { "get": { "tags": [ "Test Suites" ], "summary": "Get a test suite", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Test suite UUID" }, "required": true, "description": "Test suite UUID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Test suite details", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Test suite UUID" }, "orgId": { "type": "string", "description": "Sauce Labs organization ID" }, "teamId": { "type": "string", "description": "Team UUID that owns the suite" }, "name": { "type": "string", "description": "Human-readable suite name" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Free-form tags for categorization and filtering" }, "creationDate": { "type": "string", "description": "ISO 8601 timestamp when the suite was created" }, "lastUpdate": { "type": "string", "description": "ISO 8601 timestamp of the most recent modification" }, "creatorUserId": { "type": "string", "description": "UUID of the user who created the suite" }, "creatorUserName": { "type": [ "string", "null" ], "description": "Display name of the creator" }, "lastModifierUserId": { "type": "string", "description": "UUID of the user who last modified the suite" }, "lastModifierUserName": { "type": [ "string", "null" ], "description": "Display name of the last modifier" }, "testCaseCount": { "type": "number", "description": "Number of test cases currently in the suite" } }, "required": [ "id", "orgId", "teamId", "name", "tags", "creationDate", "lastUpdate", "creatorUserId", "creatorUserName", "lastModifierUserId", "lastModifierUserName", "testCaseCount" ] } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid path parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_PARAMS" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Missing or invalid Bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "UNAUTHORIZED" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Test suite not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "TEST_SUITE_NOT_FOUND" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } } } }, "post": { "tags": [ "Test Suites" ], "summary": "Update a test suite", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Test suite UUID" }, "required": true, "description": "Test suite UUID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "New suite name (1–255 characters)" }, "tags": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": "Replace all tags with this list (each tag 1–100 characters)" }, "testCases": { "type": "array", "items": { "type": "string", "description": "24-character hex MongoDB ObjectId" }, "description": "Replace all test cases in the suite with these ObjectIds. Mutually exclusive with addTestCases/removeTestCases." }, "addTestCases": { "type": "array", "items": { "type": "string", "description": "24-character hex MongoDB ObjectId" }, "description": "Test case ObjectIds to append to the suite" }, "removeTestCases": { "type": "array", "items": { "type": "string", "description": "24-character hex MongoDB ObjectId" }, "description": "Test case ObjectIds to remove from the suite" } } } } } }, "responses": { "200": { "description": "Updated test suite", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Test suite UUID" }, "orgId": { "type": "string", "description": "Sauce Labs organization ID" }, "teamId": { "type": "string", "description": "Team UUID that owns the suite" }, "name": { "type": "string", "description": "Human-readable suite name" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Free-form tags for categorization and filtering" }, "creationDate": { "type": "string", "description": "ISO 8601 timestamp when the suite was created" }, "lastUpdate": { "type": "string", "description": "ISO 8601 timestamp of the most recent modification" }, "creatorUserId": { "type": "string", "description": "UUID of the user who created the suite" }, "creatorUserName": { "type": [ "string", "null" ], "description": "Display name of the creator" }, "lastModifierUserId": { "type": "string", "description": "UUID of the user who last modified the suite" }, "lastModifierUserName": { "type": [ "string", "null" ], "description": "Display name of the last modifier" }, "testCaseCount": { "type": "number", "description": "Number of test cases currently in the suite" } }, "required": [ "id", "orgId", "teamId", "name", "tags", "creationDate", "lastUpdate", "creatorUserId", "creatorUserName", "lastModifierUserId", "lastModifierUserName", "testCaseCount" ] } }, "required": [ "data" ] } } } }, "400": { "description": "- Invalid path parameters\n- Invalid request body\n- Invalid or missing test cases\n- Test cases not found", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_PARAMS" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_BODY" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_TEST_CASES" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "TEST_CASES_NOT_FOUND" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } ] } } } }, "401": { "description": "Missing or invalid Bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "UNAUTHORIZED" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Test suite not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "TEST_SUITE_NOT_FOUND" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } } } }, "delete": { "tags": [ "Test Suites" ], "summary": "Delete a test suite", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Test suite UUID" }, "required": true, "description": "Test suite UUID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "deleteTestCases": { "type": "boolean", "description": "When true, permanently deletes all test cases belonging to this suite as well" } } } } } }, "responses": { "204": { "description": "Test suite deleted" }, "400": { "description": "- Invalid path parameters\n- Invalid request body", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_PARAMS" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_BODY" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } ] } } } }, "401": { "description": "Missing or invalid Bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "UNAUTHORIZED" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Test suite not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "TEST_SUITE_NOT_FOUND" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } } } } }, "/testsuites/{id}/run": { "post": { "tags": [ "Test Suites" ], "summary": "Run all test cases in a suite", "description": "Queues test case runs for every test case in the suite.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Test suite UUID" }, "required": true, "description": "Test suite UUID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "buildName": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 255, "description": "Sauce Labs build name to group all suite runs under (max 255 characters)" } } } } } }, "responses": { "200": { "description": "Suite run initiated", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Suite run UUID" }, "orgId": { "type": "string", "description": "Sauce Labs organization ID" }, "teamId": { "type": "string", "description": "Team UUID" }, "userId": { "type": "string", "description": "UUID of the user who initiated the suite run" }, "runCount": { "type": "number", "description": "Number of individual test case runs that were queued" }, "buildName": { "type": "string", "description": "Sauce Labs build name grouping all runs in this suite execution" } }, "required": [ "id", "orgId", "teamId", "userId", "runCount", "buildName" ] } }, "required": [ "data" ] } } } }, "400": { "description": "- Invalid path parameters\n- Invalid request body\n- No jobs to run", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_PARAMS" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_BODY" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "TEST_SUITE_NO_RUN_JOBS" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } ] } } } }, "401": { "description": "Missing or invalid Bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "UNAUTHORIZED" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Test suite not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "TEST_SUITE_NOT_FOUND" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } } } } }, "/test-schedules": { "get": { "tags": [ "Test Schedules" ], "summary": "List test schedules", "description": "Returns a paginated list of test schedules. Supports filtering by IDs, search term, date range, user, team, and test suite IDs.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "array", "items": { "type": "string" }, "description": "Filter by specific schedule UUID(s). Accepts a single value or an array." }, "required": false, "description": "Filter by specific schedule UUID(s). Accepts a single value or an array.", "name": "ids", "in": "query" }, { "schema": { "type": "string", "description": "Case-insensitive search term matched against the schedule name" }, "required": false, "description": "Case-insensitive search term matched against the schedule name", "name": "search", "in": "query" }, { "schema": { "type": "string", "description": "ISO 8601 start date filter — only return schedules created on or after this date" }, "required": false, "description": "ISO 8601 start date filter — only return schedules created on or after this date", "name": "startDate", "in": "query" }, { "schema": { "type": "string", "description": "ISO 8601 end date filter — only return schedules created on or before this date" }, "required": false, "description": "ISO 8601 end date filter — only return schedules created on or before this date", "name": "endDate", "in": "query" }, { "schema": { "type": "string", "description": "Filter by creator user UUID" }, "required": false, "description": "Filter by creator user UUID", "name": "userId", "in": "query" }, { "schema": { "type": "string", "description": "Filter by team UUID" }, "required": false, "description": "Filter by team UUID", "name": "teamId", "in": "query" }, { "schema": { "type": "integer", "description": "Number of results to skip (for offset-based pagination). Defaults to 0." }, "required": false, "description": "Number of results to skip (for offset-based pagination). Defaults to 0.", "name": "skip", "in": "query" }, { "schema": { "type": "integer", "description": "Maximum number of results to return" }, "required": false, "description": "Maximum number of results to return", "name": "limit", "in": "query" }, { "schema": { "type": "array", "items": { "type": "string" }, "description": "Filter schedules that contain any of these test suite UUID(s). Accepts a single value or an array." }, "required": false, "description": "Filter schedules that contain any of these test suite UUID(s). Accepts a single value or an array.", "name": "testSuiteIds", "in": "query" } ], "responses": { "200": { "description": "Paginated list of test schedules", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Test schedule UUID" }, "orgId": { "type": "string", "description": "Sauce Labs organization ID" }, "teamId": { "type": "string", "description": "Team UUID that owns the schedule" }, "creatorUserId": { "type": "string", "description": "UUID of the user who created the schedule" }, "creatorUserName": { "type": [ "string", "null" ], "description": "Display name of the creator" }, "creationDate": { "type": "string", "description": "ISO 8601 timestamp when the schedule was created" }, "lastModifierUserId": { "type": "string", "description": "UUID of the user who last modified the schedule" }, "lastModifierUserName": { "type": [ "string", "null" ], "description": "Display name of the last modifier" }, "lastUpdateDate": { "type": "string", "description": "ISO 8601 timestamp of the most recent modification" }, "name": { "type": "string", "description": "Human-readable schedule name" }, "settings": { "type": "object", "properties": { "startDate": { "type": "string", "description": "ISO 8601 date after which the schedule is active" }, "endDate": { "type": "string", "description": "ISO 8601 date after which the schedule stops triggering" }, "maxRuns": { "type": "number", "description": "Maximum total number of runs allowed. Schedule is disabled once reached." }, "cron": { "type": "string", "description": "Standard 5-field cron expression defining the trigger frequency" }, "timezone": { "type": "string", "description": "IANA timezone used to evaluate the cron expression (e.g. \"America/New_York\")" }, "scTunnelName": { "type": "string", "description": "Sauce Connect tunnel name for accessing private sites" }, "buildName": { "type": "string", "description": "Sauce Labs build name applied to each scheduled run" }, "runningUserId": { "type": "string", "description": "UUID of the user whose credentials are used for scheduled runs" } }, "required": [ "cron", "timezone", "runningUserId" ] }, "state": { "type": "object", "properties": { "stateName": { "type": "string", "enum": [ "ENABLED", "DISABLED", "ERRORED", "RUNNING" ], "description": "Current schedule state: ENABLED (active), DISABLED (paused), ERRORED (stopped due to failure), RUNNING (executing right now)" }, "lastRunError": { "type": "string", "description": "Error message from the most recent failed run" }, "lastRunDate": { "type": "string", "description": "ISO 8601 timestamp of the most recent run" }, "nextRunDate": { "type": "string", "description": "ISO 8601 timestamp of the next scheduled trigger" }, "remainingRuns": { "type": "number", "description": "Number of runs remaining before maxRuns is reached. Absent when maxRuns is not set." } }, "required": [ "stateName" ] }, "testSuiteIds": { "type": "array", "items": { "type": "string" }, "description": "UUIDs of the test suites executed on each trigger" } }, "required": [ "id", "orgId", "teamId", "creatorUserId", "creatorUserName", "creationDate", "lastModifierUserId", "lastModifierUserName", "lastUpdateDate", "name", "settings", "state", "testSuiteIds" ] }, "description": "Result items for the current page" }, "total": { "type": "number", "description": "Total number of matching items across all pages (independent of skip/limit)" } }, "required": [ "items", "total" ] } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid query string parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_QUERY" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Missing or invalid Bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "UNAUTHORIZED" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } } } }, "post": { "tags": [ "Test Schedules" ], "summary": "Create a test schedule", "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Human-readable schedule name (1–255 characters)" }, "settings": { "type": "object", "properties": { "cron": { "type": "string", "description": "Standard 5-field cron expression (minute hour day month weekday)", "example": "0 */1 * * *" }, "timezone": { "type": "string", "description": "IANA timezone identifier (e.g. \"America/New_York\", \"Europe/London\")", "example": "America/New_York" }, "runningUserId": { "type": "string", "description": "UUID of the user whose credentials are used to run the tests" }, "startDate": { "type": "string", "description": "ISO 8601 date after which the schedule becomes active. Runs will not trigger before this date." }, "endDate": { "type": "string", "description": "ISO 8601 date after which the schedule stops. No runs will trigger after this date." }, "maxRuns": { "type": "integer", "description": "Maximum total number of runs the schedule may trigger. The schedule is disabled once reached." }, "scTunnelName": { "type": "string", "description": "Name of an active Sauce Connect tunnel to route traffic through" }, "buildName": { "type": "string", "description": "Sauce Labs build name to group all scheduled runs under" } }, "required": [ "cron", "timezone", "runningUserId" ] }, "testSuiteIds": { "type": "array", "items": { "type": "string", "description": "UUID (dashed or dashless). Dashes are stripped automatically." }, "description": "UUIDs of the test suites to run on each trigger" }, "stateName": { "type": "string", "enum": [ "ENABLED", "DISABLED" ], "description": "Initial schedule state. Use ENABLED to start triggering immediately." } }, "required": [ "name", "settings", "testSuiteIds", "stateName" ] } } } }, "responses": { "200": { "description": "Created test schedule", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Test schedule UUID" }, "orgId": { "type": "string", "description": "Sauce Labs organization ID" }, "teamId": { "type": "string", "description": "Team UUID that owns the schedule" }, "creatorUserId": { "type": "string", "description": "UUID of the user who created the schedule" }, "creatorUserName": { "type": [ "string", "null" ], "description": "Display name of the creator" }, "creationDate": { "type": "string", "description": "ISO 8601 timestamp when the schedule was created" }, "lastModifierUserId": { "type": "string", "description": "UUID of the user who last modified the schedule" }, "lastModifierUserName": { "type": [ "string", "null" ], "description": "Display name of the last modifier" }, "lastUpdateDate": { "type": "string", "description": "ISO 8601 timestamp of the most recent modification" }, "name": { "type": "string", "description": "Human-readable schedule name" }, "settings": { "type": "object", "properties": { "startDate": { "type": "string", "description": "ISO 8601 date after which the schedule is active" }, "endDate": { "type": "string", "description": "ISO 8601 date after which the schedule stops triggering" }, "maxRuns": { "type": "number", "description": "Maximum total number of runs allowed. Schedule is disabled once reached." }, "cron": { "type": "string", "description": "Standard 5-field cron expression defining the trigger frequency" }, "timezone": { "type": "string", "description": "IANA timezone used to evaluate the cron expression (e.g. \"America/New_York\")" }, "scTunnelName": { "type": "string", "description": "Sauce Connect tunnel name for accessing private sites" }, "buildName": { "type": "string", "description": "Sauce Labs build name applied to each scheduled run" }, "runningUserId": { "type": "string", "description": "UUID of the user whose credentials are used for scheduled runs" } }, "required": [ "cron", "timezone", "runningUserId" ] }, "state": { "type": "object", "properties": { "stateName": { "type": "string", "enum": [ "ENABLED", "DISABLED", "ERRORED", "RUNNING" ], "description": "Current schedule state: ENABLED (active), DISABLED (paused), ERRORED (stopped due to failure), RUNNING (executing right now)" }, "lastRunError": { "type": "string", "description": "Error message from the most recent failed run" }, "lastRunDate": { "type": "string", "description": "ISO 8601 timestamp of the most recent run" }, "nextRunDate": { "type": "string", "description": "ISO 8601 timestamp of the next scheduled trigger" }, "remainingRuns": { "type": "number", "description": "Number of runs remaining before maxRuns is reached. Absent when maxRuns is not set." } }, "required": [ "stateName" ] }, "testSuiteIds": { "type": "array", "items": { "type": "string" }, "description": "UUIDs of the test suites executed on each trigger" } }, "required": [ "id", "orgId", "teamId", "creatorUserId", "creatorUserName", "creationDate", "lastModifierUserId", "lastModifierUserName", "lastUpdateDate", "name", "settings", "state", "testSuiteIds" ] } }, "required": [ "data" ] } } } }, "400": { "description": "- Invalid request body\n- Test suites not found\n- Running user not found", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_BODY" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "TEST_SUITES_NOT_FOUND" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "RUNNING_USER_NOT_FOUND" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } ] } } } }, "401": { "description": "Missing or invalid Bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "UNAUTHORIZED" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } } } } }, "/test-schedules/{id}": { "get": { "tags": [ "Test Schedules" ], "summary": "Get a test schedule", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Test schedule UUID" }, "required": true, "description": "Test schedule UUID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Test schedule details", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Test schedule UUID" }, "orgId": { "type": "string", "description": "Sauce Labs organization ID" }, "teamId": { "type": "string", "description": "Team UUID that owns the schedule" }, "creatorUserId": { "type": "string", "description": "UUID of the user who created the schedule" }, "creatorUserName": { "type": [ "string", "null" ], "description": "Display name of the creator" }, "creationDate": { "type": "string", "description": "ISO 8601 timestamp when the schedule was created" }, "lastModifierUserId": { "type": "string", "description": "UUID of the user who last modified the schedule" }, "lastModifierUserName": { "type": [ "string", "null" ], "description": "Display name of the last modifier" }, "lastUpdateDate": { "type": "string", "description": "ISO 8601 timestamp of the most recent modification" }, "name": { "type": "string", "description": "Human-readable schedule name" }, "settings": { "type": "object", "properties": { "startDate": { "type": "string", "description": "ISO 8601 date after which the schedule is active" }, "endDate": { "type": "string", "description": "ISO 8601 date after which the schedule stops triggering" }, "maxRuns": { "type": "number", "description": "Maximum total number of runs allowed. Schedule is disabled once reached." }, "cron": { "type": "string", "description": "Standard 5-field cron expression defining the trigger frequency" }, "timezone": { "type": "string", "description": "IANA timezone used to evaluate the cron expression (e.g. \"America/New_York\")" }, "scTunnelName": { "type": "string", "description": "Sauce Connect tunnel name for accessing private sites" }, "buildName": { "type": "string", "description": "Sauce Labs build name applied to each scheduled run" }, "runningUserId": { "type": "string", "description": "UUID of the user whose credentials are used for scheduled runs" } }, "required": [ "cron", "timezone", "runningUserId" ] }, "state": { "type": "object", "properties": { "stateName": { "type": "string", "enum": [ "ENABLED", "DISABLED", "ERRORED", "RUNNING" ], "description": "Current schedule state: ENABLED (active), DISABLED (paused), ERRORED (stopped due to failure), RUNNING (executing right now)" }, "lastRunError": { "type": "string", "description": "Error message from the most recent failed run" }, "lastRunDate": { "type": "string", "description": "ISO 8601 timestamp of the most recent run" }, "nextRunDate": { "type": "string", "description": "ISO 8601 timestamp of the next scheduled trigger" }, "remainingRuns": { "type": "number", "description": "Number of runs remaining before maxRuns is reached. Absent when maxRuns is not set." } }, "required": [ "stateName" ] }, "testSuiteIds": { "type": "array", "items": { "type": "string" }, "description": "UUIDs of the test suites executed on each trigger" } }, "required": [ "id", "orgId", "teamId", "creatorUserId", "creatorUserName", "creationDate", "lastModifierUserId", "lastModifierUserName", "lastUpdateDate", "name", "settings", "state", "testSuiteIds" ] } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid path parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_PARAMS" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Missing or invalid Bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "UNAUTHORIZED" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Test schedule not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "TEST_SCHEDULE_NOT_FOUND" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } } } }, "post": { "tags": [ "Test Schedules" ], "summary": "Update a test schedule", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Test schedule UUID" }, "required": true, "description": "Test schedule UUID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "New schedule name (1–255 characters)" }, "settings": { "type": "object", "properties": { "startDate": { "type": "string", "description": "ISO 8601 start date. Set to null to remove the constraint." }, "endDate": { "type": "string", "description": "ISO 8601 end date. Set to null to remove the constraint." }, "maxRuns": { "type": "integer", "description": "Maximum total number of runs. Set to null to remove the limit." }, "cron": { "type": "string", "description": "Standard 5-field cron expression (minute hour day month weekday)", "example": "0 */1 * * *" }, "timezone": { "type": "string", "description": "IANA timezone identifier (e.g. \"America/New_York\", \"Europe/London\")", "example": "America/New_York" }, "scTunnelName": { "type": [ "string", "null" ], "description": "Name of an active Sauce Connect tunnel. Set to null to remove." }, "buildName": { "type": [ "string", "null" ], "description": "Sauce Labs build name. Set to null to remove." }, "runningUserId": { "type": "string", "description": "UUID of the user whose credentials are used to run the tests" } } }, "testSuiteIds": { "type": "array", "items": { "type": "string", "description": "UUID (dashed or dashless). Dashes are stripped automatically." }, "description": "Replace all test suites with these UUIDs. Mutually exclusive with addTestSuiteIds/removeTestSuiteIds." }, "addTestSuiteIds": { "type": "array", "items": { "type": "string", "description": "UUID (dashed or dashless). Dashes are stripped automatically." }, "description": "Test suite UUIDs to append to the schedule" }, "removeTestSuiteIds": { "type": "array", "items": { "type": "string", "description": "UUID (dashed or dashless). Dashes are stripped automatically." }, "description": "Test suite UUIDs to remove from the schedule" }, "stateName": { "type": "string", "enum": [ "ENABLED", "DISABLED" ], "description": "Set to ENABLED to activate or DISABLED to pause the schedule" } } } } } }, "responses": { "200": { "description": "Updated test schedule", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Test schedule UUID" }, "orgId": { "type": "string", "description": "Sauce Labs organization ID" }, "teamId": { "type": "string", "description": "Team UUID that owns the schedule" }, "creatorUserId": { "type": "string", "description": "UUID of the user who created the schedule" }, "creatorUserName": { "type": [ "string", "null" ], "description": "Display name of the creator" }, "creationDate": { "type": "string", "description": "ISO 8601 timestamp when the schedule was created" }, "lastModifierUserId": { "type": "string", "description": "UUID of the user who last modified the schedule" }, "lastModifierUserName": { "type": [ "string", "null" ], "description": "Display name of the last modifier" }, "lastUpdateDate": { "type": "string", "description": "ISO 8601 timestamp of the most recent modification" }, "name": { "type": "string", "description": "Human-readable schedule name" }, "settings": { "type": "object", "properties": { "startDate": { "type": "string", "description": "ISO 8601 date after which the schedule is active" }, "endDate": { "type": "string", "description": "ISO 8601 date after which the schedule stops triggering" }, "maxRuns": { "type": "number", "description": "Maximum total number of runs allowed. Schedule is disabled once reached." }, "cron": { "type": "string", "description": "Standard 5-field cron expression defining the trigger frequency" }, "timezone": { "type": "string", "description": "IANA timezone used to evaluate the cron expression (e.g. \"America/New_York\")" }, "scTunnelName": { "type": "string", "description": "Sauce Connect tunnel name for accessing private sites" }, "buildName": { "type": "string", "description": "Sauce Labs build name applied to each scheduled run" }, "runningUserId": { "type": "string", "description": "UUID of the user whose credentials are used for scheduled runs" } }, "required": [ "cron", "timezone", "runningUserId" ] }, "state": { "type": "object", "properties": { "stateName": { "type": "string", "enum": [ "ENABLED", "DISABLED", "ERRORED", "RUNNING" ], "description": "Current schedule state: ENABLED (active), DISABLED (paused), ERRORED (stopped due to failure), RUNNING (executing right now)" }, "lastRunError": { "type": "string", "description": "Error message from the most recent failed run" }, "lastRunDate": { "type": "string", "description": "ISO 8601 timestamp of the most recent run" }, "nextRunDate": { "type": "string", "description": "ISO 8601 timestamp of the next scheduled trigger" }, "remainingRuns": { "type": "number", "description": "Number of runs remaining before maxRuns is reached. Absent when maxRuns is not set." } }, "required": [ "stateName" ] }, "testSuiteIds": { "type": "array", "items": { "type": "string" }, "description": "UUIDs of the test suites executed on each trigger" } }, "required": [ "id", "orgId", "teamId", "creatorUserId", "creatorUserName", "creationDate", "lastModifierUserId", "lastModifierUserName", "lastUpdateDate", "name", "settings", "state", "testSuiteIds" ] } }, "required": [ "data" ] } } } }, "400": { "description": "- Invalid path parameters\n- Invalid request body\n- Invalid test suites\n- Test suites not found\n- Running user not found", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_PARAMS" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_BODY" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_TEST_SUITES" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "TEST_SUITES_NOT_FOUND" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "RUNNING_USER_NOT_FOUND" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } ] } } } }, "401": { "description": "Missing or invalid Bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "UNAUTHORIZED" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Test schedule not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "TEST_SCHEDULE_NOT_FOUND" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } } } }, "delete": { "tags": [ "Test Schedules" ], "summary": "Delete a test schedule", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Test schedule UUID" }, "required": true, "description": "Test schedule UUID", "name": "id", "in": "path" } ], "responses": { "204": { "description": "Test schedule deleted" }, "400": { "description": "Invalid path parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_PARAMS" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Missing or invalid Bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "UNAUTHORIZED" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Test schedule not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "TEST_SCHEDULE_NOT_FOUND" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } } } } }, "/variables": { "get": { "tags": [ "Variables" ], "summary": "List variables", "description": "Returns a paginated list of variables. Secret values are masked (the `value` field is absent for secrets).", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "integer", "description": "Number of results to skip (for offset-based pagination). Defaults to 0." }, "required": false, "description": "Number of results to skip (for offset-based pagination). Defaults to 0.", "name": "skip", "in": "query" }, { "schema": { "type": "integer", "description": "Maximum number of results to return (1–200)." }, "required": false, "description": "Maximum number of results to return (1–200).", "name": "limit", "in": "query" }, { "schema": { "type": "string", "enum": [ "org", "team", "testSuite", "testCase" ], "description": "Filter by scope: org, team, testSuite, or testCase. Visibility is always restricted to the caller`s team regardless of scope." }, "required": false, "description": "Filter by scope: org, team, testSuite, or testCase. Visibility is always restricted to the caller`s team regardless of scope.", "name": "scope", "in": "query" }, { "schema": { "type": "string", "description": "Filter by test suite UUID (required when scope=testSuite)" }, "required": false, "description": "Filter by test suite UUID (required when scope=testSuite)", "name": "testSuiteId", "in": "query" }, { "schema": { "type": "string", "description": "Filter by test case ObjectId (required when scope=testCase)" }, "required": false, "description": "Filter by test case ObjectId (required when scope=testCase)", "name": "testCaseId", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Case-insensitive search term matched against the variable name" }, "required": false, "description": "Case-insensitive search term matched against the variable name", "name": "search", "in": "query" } ], "responses": { "200": { "description": "Paginated list of variables", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Variable UUID" }, "orgId": { "type": "string", "description": "Sauce Labs organization ID" }, "teamId": { "type": "string", "description": "Team UUID" }, "testSuiteId": { "type": [ "string", "null" ], "description": "Test suite UUID (set when scope=testSuite)" }, "testCaseId": { "type": [ "string", "null" ], "description": "Test case ObjectId (set when scope=testCase)" }, "scope": { "type": "string", "enum": [ "org", "team", "testSuite", "testCase" ], "description": "Scope at which the variable is defined" }, "name": { "type": "string", "description": "Variable name" }, "isSecret": { "type": "boolean", "description": "Whether the value is a secret" }, "value": { "type": [ "string", "null" ], "description": "Plaintext value. Absent (not null) when isSecret is true — fetch via GET /variables/secret/{variableId} instead." }, "creatorUserId": { "type": "string", "description": "UUID of the user who created the variable" }, "creatorUserName": { "type": [ "string", "null" ], "description": "Display name of the creator" }, "lastModifierUserId": { "type": "string", "description": "UUID of the user who last modified the variable" }, "lastModifierUserName": { "type": [ "string", "null" ], "description": "Display name of the last modifier" }, "creationDate": { "type": "string", "description": "ISO 8601 timestamp when the variable was created" }, "lastUpdate": { "type": "string", "description": "ISO 8601 timestamp of the most recent modification" } }, "required": [ "id", "orgId", "teamId", "testSuiteId", "testCaseId", "scope", "name", "isSecret", "creatorUserId", "creatorUserName", "lastModifierUserId", "lastModifierUserName", "creationDate", "lastUpdate" ] }, "description": "Result items for the current page" }, "total": { "type": "number", "description": "Total number of matching items across all pages (independent of skip/limit)" } }, "required": [ "items", "total" ] } }, "required": [ "data" ] } } } }, "400": { "description": "- Invalid query string parameters\n- Scope/scope-id mismatch", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_QUERY" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "VARIABLE_SCOPE_INVALID" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } ] } } } }, "401": { "description": "Missing or invalid Bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "UNAUTHORIZED" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } } } }, "post": { "tags": [ "Variables" ], "summary": "Create a variable", "description": "When `isSecret` is true, the value is persisted in a separate collection and is never returned by GET endpoints. Use GET /variables/secret/{variableId} to retrieve it.", "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "org", "team", "testSuite", "testCase" ], "description": "Scope at which the variable is defined. The variable inherits the caller team via the auth context." }, "testSuiteId": { "type": "string", "description": "Required when scope=testSuite. Must be omitted for other scopes." }, "testCaseId": { "type": "string", "description": "Required when scope=testCase. Must be omitted for other scopes." }, "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Variable name (1–255 characters)" }, "isSecret": { "type": "boolean", "description": "When true, the value is stored separately in variableSecrets and never returned in GET /variables responses." }, "value": { "type": "string", "minLength": 1, "description": "Plaintext value (1+ characters). For secrets, the value is stored separately and never returned in GET /variables responses." } }, "required": [ "scope", "name", "isSecret", "value" ] }, "example": { "scope": "org", "name": "apiToken", "isSecret": true, "value": "" } } } }, "responses": { "200": { "description": "Created variable", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Variable UUID" }, "orgId": { "type": "string", "description": "Sauce Labs organization ID" }, "teamId": { "type": "string", "description": "Team UUID" }, "testSuiteId": { "type": [ "string", "null" ], "description": "Test suite UUID (set when scope=testSuite)" }, "testCaseId": { "type": [ "string", "null" ], "description": "Test case ObjectId (set when scope=testCase)" }, "scope": { "type": "string", "enum": [ "org", "team", "testSuite", "testCase" ], "description": "Scope at which the variable is defined" }, "name": { "type": "string", "description": "Variable name" }, "isSecret": { "type": "boolean", "description": "Whether the value is a secret" }, "value": { "type": [ "string", "null" ], "description": "Plaintext value. Absent (not null) when isSecret is true — fetch via GET /variables/secret/{variableId} instead." }, "creatorUserId": { "type": "string", "description": "UUID of the user who created the variable" }, "creatorUserName": { "type": [ "string", "null" ], "description": "Display name of the creator" }, "lastModifierUserId": { "type": "string", "description": "UUID of the user who last modified the variable" }, "lastModifierUserName": { "type": [ "string", "null" ], "description": "Display name of the last modifier" }, "creationDate": { "type": "string", "description": "ISO 8601 timestamp when the variable was created" }, "lastUpdate": { "type": "string", "description": "ISO 8601 timestamp of the most recent modification" } }, "required": [ "id", "orgId", "teamId", "testSuiteId", "testCaseId", "scope", "name", "isSecret", "creatorUserId", "creatorUserName", "lastModifierUserId", "lastModifierUserName", "creationDate", "lastUpdate" ] } }, "required": [ "data" ] } } } }, "400": { "description": "- Invalid request body\n- Scope/scope-id mismatch", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_BODY" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "VARIABLE_SCOPE_INVALID" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } ] } } } }, "401": { "description": "Missing or invalid Bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "UNAUTHORIZED" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } }, "409": { "description": "A variable with this name already exists at this scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "VARIABLE_NAME_CONFLICT" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } } } } }, "/variables/secret/{variableId}": { "get": { "tags": [ "Variables" ], "summary": "Reveal a secret variable value", "description": "Returns the plaintext secret value. Access is audited.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Variable UUID" }, "required": true, "description": "Variable UUID", "name": "variableId", "in": "path" } ], "responses": { "200": { "description": "Plaintext secret value", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "variableId": { "type": "string", "description": "Variable UUID" }, "value": { "type": "string", "description": "Plaintext secret value. Returned only by GET /variables/secret/{variableId}." } }, "required": [ "variableId", "value" ] } }, "required": [ "data" ] } } } }, "400": { "description": "- Invalid path parameters\n- Variable is not a secret", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_PARAMS" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "VARIABLE_NOT_A_SECRET" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } ] } } } }, "401": { "description": "Missing or invalid Bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "UNAUTHORIZED" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Variable not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "VARIABLE_NOT_FOUND" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } } } } }, "/variables/{id}": { "get": { "tags": [ "Variables" ], "summary": "Get a single variable", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Variable UUID" }, "required": true, "description": "Variable UUID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Variable details (secret values are masked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Variable UUID" }, "orgId": { "type": "string", "description": "Sauce Labs organization ID" }, "teamId": { "type": "string", "description": "Team UUID" }, "testSuiteId": { "type": [ "string", "null" ], "description": "Test suite UUID (set when scope=testSuite)" }, "testCaseId": { "type": [ "string", "null" ], "description": "Test case ObjectId (set when scope=testCase)" }, "scope": { "type": "string", "enum": [ "org", "team", "testSuite", "testCase" ], "description": "Scope at which the variable is defined" }, "name": { "type": "string", "description": "Variable name" }, "isSecret": { "type": "boolean", "description": "Whether the value is a secret" }, "value": { "type": [ "string", "null" ], "description": "Plaintext value. Absent (not null) when isSecret is true — fetch via GET /variables/secret/{variableId} instead." }, "creatorUserId": { "type": "string", "description": "UUID of the user who created the variable" }, "creatorUserName": { "type": [ "string", "null" ], "description": "Display name of the creator" }, "lastModifierUserId": { "type": "string", "description": "UUID of the user who last modified the variable" }, "lastModifierUserName": { "type": [ "string", "null" ], "description": "Display name of the last modifier" }, "creationDate": { "type": "string", "description": "ISO 8601 timestamp when the variable was created" }, "lastUpdate": { "type": "string", "description": "ISO 8601 timestamp of the most recent modification" } }, "required": [ "id", "orgId", "teamId", "testSuiteId", "testCaseId", "scope", "name", "isSecret", "creatorUserId", "creatorUserName", "lastModifierUserId", "lastModifierUserName", "creationDate", "lastUpdate" ] } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid path parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_PARAMS" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Missing or invalid Bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "UNAUTHORIZED" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Variable not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "VARIABLE_NOT_FOUND" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } } } }, "patch": { "tags": [ "Variables" ], "summary": "Update a variable", "description": "Toggling `isSecret` in either direction accepts an optional new `value`. When omitted, the existing value is moved across the variable/secret boundary so a UI toggle flip works without re-supplying it. In both directions the secret row is created or deleted accordingly. Requires `expectedLastUpdate` (echo the value from the prior GET) to detect concurrent edits; returns 412 on mismatch. Modification is only permitted from the team that owns the variable.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Variable UUID" }, "required": true, "description": "Variable UUID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedLastUpdate": { "type": "string", "format": "date-time", "description": "The `lastUpdate` value from the prior GET response (ISO 8601). Used for optimistic concurrency control — the request returns 412 if the variable has been modified since." }, "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "New variable name (1–255 characters)" }, "value": { "type": "string", "minLength": 1, "description": "New value (plaintext, 1+ characters)" }, "isSecret": { "type": "boolean", "description": "Toggle the secret flag. A new `value` is optional in either direction: when omitted, the existing value is moved across the variable/secret boundary so a UI toggle flip works without re-supplying it." } }, "required": [ "expectedLastUpdate" ] } } } }, "responses": { "200": { "description": "Updated variable (secret values are masked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Variable UUID" }, "orgId": { "type": "string", "description": "Sauce Labs organization ID" }, "teamId": { "type": "string", "description": "Team UUID" }, "testSuiteId": { "type": [ "string", "null" ], "description": "Test suite UUID (set when scope=testSuite)" }, "testCaseId": { "type": [ "string", "null" ], "description": "Test case ObjectId (set when scope=testCase)" }, "scope": { "type": "string", "enum": [ "org", "team", "testSuite", "testCase" ], "description": "Scope at which the variable is defined" }, "name": { "type": "string", "description": "Variable name" }, "isSecret": { "type": "boolean", "description": "Whether the value is a secret" }, "value": { "type": [ "string", "null" ], "description": "Plaintext value. Absent (not null) when isSecret is true — fetch via GET /variables/secret/{variableId} instead." }, "creatorUserId": { "type": "string", "description": "UUID of the user who created the variable" }, "creatorUserName": { "type": [ "string", "null" ], "description": "Display name of the creator" }, "lastModifierUserId": { "type": "string", "description": "UUID of the user who last modified the variable" }, "lastModifierUserName": { "type": [ "string", "null" ], "description": "Display name of the last modifier" }, "creationDate": { "type": "string", "description": "ISO 8601 timestamp when the variable was created" }, "lastUpdate": { "type": "string", "description": "ISO 8601 timestamp of the most recent modification" } }, "required": [ "id", "orgId", "teamId", "testSuiteId", "testCaseId", "scope", "name", "isSecret", "creatorUserId", "creatorUserName", "lastModifierUserId", "lastModifierUserName", "creationDate", "lastUpdate" ] } }, "required": [ "data" ] } } } }, "400": { "description": "- Invalid path parameters\n- Invalid request body", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_PARAMS" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_BODY" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } ] } } } }, "401": { "description": "Missing or invalid Bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "UNAUTHORIZED" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Caller is not a member of the team that owns the variable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "VARIABLE_FORBIDDEN" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Variable not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "VARIABLE_NOT_FOUND" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } }, "409": { "description": "A variable with this name already exists at this scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "VARIABLE_NAME_CONFLICT" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } }, "412": { "description": "The variable was modified by someone else since `expectedLastUpdate` was issued", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "VARIABLE_VERSION_CONFLICT" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } } } }, "delete": { "tags": [ "Variables" ], "summary": "Delete a variable", "description": "If the variable is a secret, the secret row is cascaded in the same transaction. Requires `expectedLastUpdate` (echo the value from the prior GET) to detect concurrent edits; returns 412 on mismatch. Deletion is only permitted from the team that owns the variable.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Variable UUID" }, "required": true, "description": "Variable UUID", "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "date-time", "description": "The `lastUpdate` value from the prior GET response (ISO 8601). Used for optimistic concurrency control — the request returns 412 if the variable has been modified since." }, "required": true, "description": "The `lastUpdate` value from the prior GET response (ISO 8601). Used for optimistic concurrency control — the request returns 412 if the variable has been modified since.", "name": "expectedLastUpdate", "in": "query" } ], "responses": { "204": { "description": "Variable deleted" }, "400": { "description": "Invalid path parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_PARAMS" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Missing or invalid Bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "UNAUTHORIZED" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Caller is not a member of the team that owns the variable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "VARIABLE_FORBIDDEN" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Variable not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "VARIABLE_NOT_FOUND" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } }, "412": { "description": "The variable was modified by someone else since `expectedLastUpdate` was issued", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "VARIABLE_VERSION_CONFLICT" ], "description": "Machine-readable error code" }, "detail": { "type": "string", "description": "Human-readable error description with actionable context" } }, "required": [ "code", "detail" ] } }, "required": [ "error" ] } } } } } } } }, "webhooks": {} }