{ "openapi": "3.0.1", "info": { "title": "Hyperbrowser API", "version": "1.0.0" }, "servers": [ { "url": "https://api.hyperbrowser.ai", "description": "Production server" } ], "components": { "schemas": { "X402SessionParams": { "type": "object", "additionalProperties": false, "description": "Optional preferences for a browser session priced at 0.10 USDC per hour, paid upfront for timeoutMinutes. Unknown fields are rejected before payment verification. Web recording is disabled. Other regular session creation options are not supported.", "default": {}, "properties": { "screen": { "type": "object", "additionalProperties": false, "description": "Browser screen dimensions. An omitted dimension uses its default.", "default": { "width": 1280, "height": 720 }, "properties": { "width": { "type": "number", "minimum": 500, "maximum": 3840, "default": 1280 }, "height": { "type": "number", "minimum": 360, "maximum": 2160, "default": 720 } } }, "viewOnlyLiveView": { "type": "boolean", "default": false, "description": "Make the live-view link read-only. CDP, WebDriver, and the computer action endpoint still allow browser control." }, "timeoutMinutes": { "type": "integer", "minimum": 5, "maximum": 60, "default": 30, "description": "Maximum session lifetime in minutes, from 5 through 60. Defaults to 30. Determines the session duration and upfront price at 0.10 USDC per hour. Connection token lifetimes and expiresAt follow this value." } } }, "X402SessionResponse": { "type": "object", "additionalProperties": false, "description": "Connection credentials and a management token for the purchased browser. Save this response; get does not reissue connection credentials. These tokens cannot authenticate regular account APIs.", "required": [ "id", "wsEndpoint", "webdriverEndpoint", "liveUrl", "computerActionEndpoint", "token", "expiresAt", "managementToken" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Purchased session ID." }, "wsEndpoint": { "type": "string", "format": "uri", "description": "CDP WebSocket URL for Playwright, Puppeteer, or another CDP client. Includes its authentication token." }, "webdriverEndpoint": { "type": "string", "format": "uri", "description": "Selenium/WebDriver endpoint. Send token in the x-hyperbrowser-token header." }, "liveUrl": { "type": "string", "format": "uri", "description": "Authenticated live-view URL. Interaction is disabled when viewOnlyLiveView is true." }, "computerActionEndpoint": { "type": "string", "format": "uri", "description": "Endpoint for mouse, keyboard, and screenshot actions. Includes its authentication token." }, "token": { "type": "string", "description": "Credential scoped to this browser session. Use it for WebDriver authentication, not the regular get/list/stop/update/extend session APIs." }, "expiresAt": { "type": "string", "format": "date-time", "description": "Returned session expiry timestamp based on timeoutMinutes. The browser can stop earlier if closed or disconnected." }, "managementToken": { "type": "string", "description": "Bearer token for GET /x402/session/{id} and PUT /x402/session/{id}/stop only. Valid for 24 hours from purchase, including after browser expiry. Does not authenticate browser connections or regular account APIs." } } }, "ScreenConfig": { "type": "object", "properties": { "width": { "type": "number", "default": 1280 }, "height": { "type": "number", "default": 720 } } }, "SessionLaunchState": { "type": "object", "properties": { "useUltraStealth": { "type": "boolean" }, "useStealth": { "type": "boolean" }, "useProxy": { "type": "boolean" }, "solveCaptchas": { "type": "boolean" }, "solverType": { "type": "string", "enum": [ "visual" ], "description": "Optional CAPTCHA solver mode. Set to visual to use the visual reCAPTCHA solver." }, "adblock": { "type": "boolean" }, "trackers": { "type": "boolean" }, "annoyances": { "type": "boolean" }, "screen": { "$ref": "#/components/schemas/ScreenConfig" }, "enableWebRecording": { "type": "boolean" }, "enableVideoWebRecording": { "type": "boolean" }, "enableLogCapture": { "type": "boolean" }, "acceptCookies": { "type": "boolean" }, "profile": { "$ref": "#/components/schemas/CreateSessionProfile" }, "staticIpId": { "type": "string" }, "saveDownloads": { "type": "boolean" }, "enableWindowManager": { "type": "boolean" }, "enableWindowManagerTaskbar": { "type": "boolean" }, "viewOnlyLiveView": { "type": "boolean" }, "disablePasswordManager": { "type": "boolean" }, "enableAlwaysOpenPdfExternally": { "type": "boolean" }, "disablePostQuantumKeyAgreement": { "type": "boolean" }, "enableWebMcp": { "type": "boolean", "description": "Whether WebMCP was enabled when this session launched." }, "webBotAuth": { "$ref": "#/components/schemas/SessionWebBotAuth", "description": "Present only for a session that signs its requests with Web Bot Auth." } }, "nullable": true }, "SessionWebBotAuth": { "type": "object", "required": [ "signatureAgent" ], "description": "How a session signs its requests with Web Bot Auth.", "properties": { "signatureAgent": { "type": "string", "description": "The identity the session signs as, `https://www.hyperbrowser.ai`." }, "onlyDomains": { "type": "array", "items": { "type": "string" }, "description": "Present when signing is limited to these hostnames and their subdomains." } } }, "Session": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "teamId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "active", "closed", "error", "close-error" ] }, "startTime": { "type": "string", "format": "timestamp-milliseconds", "nullable": true }, "endTime": { "type": "string", "format": "timestamp-milliseconds", "nullable": true }, "createdAt": { "type": "string", "format": "iso8601" }, "updatedAt": { "type": "string", "format": "iso8601" }, "launchState": { "$ref": "#/components/schemas/SessionLaunchState" }, "creditsUsed": { "type": "number", "nullable": true } } }, "SessionDetail": { "allOf": [ { "$ref": "#/components/schemas/Session" }, { "type": "object", "properties": { "sessionUrl": { "type": "string" }, "liveUrl": { "type": "string" }, "token": { "type": "string" }, "wsEndpoint": { "type": "string" }, "webdriverEndpoint": { "type": "string" }, "computerActionEndpoint": { "type": "string" } } } ] }, "BasicResponse": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ] }, "UpdateSessionProfileParams": { "type": "object", "properties": { "persistChanges": { "type": "boolean", "description": "Whether profile changes should be persisted after the session ends." }, "persistNetworkCache": { "type": "boolean", "description": "Whether network cache should be persisted into the profile." } } }, "UpdateSessionProfileRequest": { "type": "object", "required": [ "type", "params" ], "properties": { "type": { "type": "string", "enum": [ "profile" ] }, "params": { "$ref": "#/components/schemas/UpdateSessionProfileParams" } } }, "UpdateSessionProxyLocationParams": { "type": "object", "properties": { "country": { "$ref": "#/components/schemas/ProxyCountry" }, "state": { "$ref": "#/components/schemas/ProxyState" }, "city": { "type": "string", "description": "City for managed proxy geolocation." } } }, "UpdateSessionProxyParams": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean", "description": "Whether proxying should be active for the running session." }, "staticIpId": { "type": "string", "format": "uuid", "description": "Static IP allocation to use when enabling a static IP proxy." }, "location": { "$ref": "#/components/schemas/UpdateSessionProxyLocationParams" } } }, "UpdateSessionProxyRequest": { "type": "object", "required": [ "type", "params" ], "properties": { "type": { "type": "string", "enum": [ "proxy" ] }, "params": { "$ref": "#/components/schemas/UpdateSessionProxyParams" } } }, "UpdateSessionScreenParams": { "type": "object", "required": [ "width", "height" ], "properties": { "width": { "type": "integer", "minimum": 500, "maximum": 3840 }, "height": { "type": "integer", "minimum": 360, "maximum": 2160 } } }, "UpdateSessionScreenRequest": { "type": "object", "required": [ "type", "params" ], "properties": { "type": { "type": "string", "enum": [ "screen" ] }, "params": { "$ref": "#/components/schemas/UpdateSessionScreenParams" } } }, "UpdateSessionSolveCaptchasParams": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean", "description": "Whether automatic CAPTCHA solving should be enabled for this running session." }, "solverType": { "type": "string", "enum": [ "visual" ], "description": "Optional CAPTCHA solver mode. Set to visual to use the visual reCAPTCHA solver." } } }, "UpdateSessionSolveCaptchasRequest": { "type": "object", "required": [ "type", "params" ], "properties": { "type": { "type": "string", "enum": [ "solveCaptchas" ] }, "params": { "$ref": "#/components/schemas/UpdateSessionSolveCaptchasParams" } } }, "UpdateSessionRequest": { "oneOf": [ { "$ref": "#/components/schemas/UpdateSessionProfileRequest" }, { "$ref": "#/components/schemas/UpdateSessionProxyRequest" }, { "$ref": "#/components/schemas/UpdateSessionScreenRequest" }, { "$ref": "#/components/schemas/UpdateSessionSolveCaptchasRequest" } ], "discriminator": { "propertyName": "type", "mapping": { "profile": "#/components/schemas/UpdateSessionProfileRequest", "proxy": "#/components/schemas/UpdateSessionProxyRequest", "screen": "#/components/schemas/UpdateSessionScreenRequest", "solveCaptchas": "#/components/schemas/UpdateSessionSolveCaptchasRequest" } } }, "UpdateSessionResponse": { "allOf": [ { "$ref": "#/components/schemas/BasicResponse" }, { "type": "object", "properties": { "solveCaptchas": { "type": "boolean", "description": "Returned for solveCaptchas updates." }, "sessionId": { "type": "string", "description": "Returned for solveCaptchas updates." }, "telemetryReady": { "type": "boolean", "description": "Returned for solveCaptchas updates." } } } ] }, "UpdateSessionSolveCaptchasResponse": { "allOf": [ { "$ref": "#/components/schemas/BasicResponse" }, { "type": "object", "properties": { "solveCaptchas": { "type": "boolean" }, "sessionId": { "type": "string" }, "telemetryReady": { "type": "boolean" } } } ] }, "CaptchaEvaluationType": { "type": "string", "enum": [ "turnstile", "cloudflare-challenge", "aliexpress", "recaptcha", "amazon" ], "description": "CAPTCHA target to evaluate manually." }, "ImageCaptchaParam": { "type": "object", "properties": { "imageSelector": { "type": "string" }, "inputSelector": { "type": "string" } } }, "CaptchaEvaluationParams": { "type": "object", "properties": { "captcha": { "$ref": "#/components/schemas/CaptchaEvaluationType" }, "captchaType": { "$ref": "#/components/schemas/CaptchaEvaluationType" }, "text": { "$ref": "#/components/schemas/CaptchaEvaluationType" }, "iterations": { "type": "integer", "minimum": 1, "maximum": 20 }, "maxIterations": { "type": "integer", "minimum": 1, "maximum": 20 }, "solverType": { "type": "string", "enum": [ "visual" ], "description": "Optional CAPTCHA solver mode. Set to visual to use the visual reCAPTCHA solver." }, "imageCaptchaParams": { "type": "array", "items": { "$ref": "#/components/schemas/ImageCaptchaParam" } }, "useUltraStealth": { "type": "boolean" } } }, "CaptchaEvaluationPageResult": { "type": "object", "properties": { "url": { "type": "string" }, "targetId": { "type": "string", "nullable": true }, "iterationsRun": { "type": "integer" }, "solved": { "type": "boolean" }, "solvedCaptchas": { "type": "array", "items": { "$ref": "#/components/schemas/CaptchaEvaluationType" } }, "checkedCaptchas": { "type": "array", "items": { "$ref": "#/components/schemas/CaptchaEvaluationType" } }, "captchaSolvedCounts": { "type": "object", "additionalProperties": { "type": "number" } }, "lastSolveTime": { "type": "object", "additionalProperties": { "type": "number" } } } }, "CaptchaEvaluationResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "captcha": { "allOf": [ { "$ref": "#/components/schemas/CaptchaEvaluationType" } ], "nullable": true }, "iterationsRequested": { "type": "integer" }, "iterationsRun": { "type": "integer" }, "solved": { "type": "boolean" }, "solvedCaptchas": { "type": "array", "items": { "$ref": "#/components/schemas/CaptchaEvaluationType" } }, "pages": { "type": "array", "items": { "$ref": "#/components/schemas/CaptchaEvaluationPageResult" } } } }, "CreateProfileParams": { "type": "object", "properties": { "name": { "type": "string" } } }, "CreateProfileResponse": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string", "nullable": true } } }, "ProfileResponse": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string", "nullable": true }, "teamId": { "type": "string" }, "createdAt": { "type": "string", "format": "iso8601" }, "updatedAt": { "type": "string", "format": "iso8601" } } }, "ProfileListResponse": { "type": "object", "properties": { "profiles": { "type": "array", "items": { "$ref": "#/components/schemas/ProfileResponse" } }, "totalCount": { "type": "number" }, "page": { "type": "number" }, "perPage": { "type": "number" } } }, "ProxyCountry": { "type": "string", "enum": [ "AD", "AE", "AF", "AL", "AM", "AO", "AR", "AT", "AU", "AW", "AZ", "BA", "BD", "BE", "BG", "BH", "BJ", "BO", "BR", "BS", "BT", "BY", "BZ", "CA", "CF", "CH", "CI", "CL", "CM", "CN", "CO", "CR", "CU", "CY", "CZ", "DE", "DJ", "DK", "DM", "EC", "EE", "EG", "ES", "ET", "EU", "FI", "FJ", "FR", "GB", "GE", "GH", "GM", "GR", "HK", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IN", "IQ", "IR", "IS", "IT", "JM", "JO", "JP", "KE", "KH", "KR", "KW", "KZ", "LB", "LI", "LR", "LT", "LU", "LV", "MA", "MC", "MD", "ME", "MG", "MK", "ML", "MM", "MN", "MR", "MT", "MU", "MV", "MX", "MY", "MZ", "NG", "NL", "NO", "NZ", "OM", "PA", "PE", "PH", "PK", "PL", "PR", "PT", "PY", "QA", "RANDOM_COUNTRY", "RO", "RS", "RU", "SA", "SC", "SD", "SE", "SG", "SI", "SK", "SN", "SS", "TD", "TG", "TH", "TM", "TN", "TR", "TT", "TW", "UA", "UG", "US", "UY", "UZ", "VE", "VG", "VN", "YE", "ZA", "ZM", "ZW", "ad", "ae", "af", "al", "am", "ao", "ar", "at", "au", "aw", "az", "ba", "bd", "be", "bg", "bh", "bj", "bo", "br", "bs", "bt", "by", "bz", "ca", "cf", "ch", "ci", "cl", "cm", "cn", "co", "cr", "cu", "cy", "cz", "de", "dj", "dk", "dm", "ec", "ee", "eg", "es", "et", "eu", "fi", "fj", "fr", "gb", "ge", "gh", "gm", "gr", "hk", "hn", "hr", "ht", "hu", "id", "ie", "il", "in", "iq", "ir", "is", "it", "jm", "jo", "jp", "ke", "kh", "kr", "kw", "kz", "lb", "li", "lr", "lt", "lu", "lv", "ma", "mc", "md", "me", "mg", "mk", "ml", "mm", "mn", "mr", "mt", "mu", "mv", "mx", "my", "mz", "ng", "nl", "no", "nz", "om", "pa", "pe", "ph", "pk", "pl", "pr", "pt", "py", "qa", "ro", "rs", "ru", "sa", "sc", "sd", "se", "sg", "si", "sk", "sn", "ss", "td", "tg", "th", "tm", "tn", "tr", "tt", "tw", "ua", "ug", "us", "uy", "uz", "ve", "vg", "vn", "ye", "za", "zm", "zw" ] }, "OperatingSystem": { "type": "string", "enum": [ "windows", "android", "macos", "linux", "ios" ] }, "Platform": { "type": "string", "enum": [ "chrome", "firefox", "safari", "edge" ] }, "Device": { "type": "string", "enum": [ "desktop", "mobile" ] }, "ISO639_1": { "type": "string", "enum": [ "aa", "ab", "ae", "af", "ak", "am", "an", "ar", "as", "av", "ay", "az", "ba", "be", "bg", "bh", "bi", "bm", "bn", "bo", "br", "bs", "ca", "ce", "ch", "co", "cr", "cs", "cu", "cv", "cy", "da", "de", "dv", "dz", "ee", "el", "en", "eo", "es", "et", "eu", "fa", "ff", "fi", "fj", "fo", "fr", "fy", "ga", "gd", "gl", "gn", "gu", "gv", "ha", "he", "hi", "ho", "hr", "ht", "hu", "hy", "hz", "ia", "id", "ie", "ig", "ii", "ik", "io", "is", "it", "iu", "ja", "jv", "ka", "kg", "ki", "kj", "kk", "kl", "km", "kn", "ko", "kr", "ks", "ku", "kv", "kw", "ky", "la", "lb", "lg", "li", "ln", "lo", "lt", "lu", "lv", "mg", "mh", "mi", "mk", "ml", "mn", "mo", "mr", "ms", "mt", "my", "na", "nb", "nd", "ne", "ng", "nl", "nn", "no", "nr", "nv", "ny", "oc", "oj", "om", "or", "os", "pa", "pi", "pl", "ps", "pt", "qu", "rm", "rn", "ro", "ru", "rw", "sa", "sc", "sd", "se", "sg", "si", "sk", "sl", "sm", "sn", "so", "sq", "sr", "ss", "st", "su", "sv", "sw", "ta", "te", "tg", "th", "ti", "tk", "tl", "tn", "to", "tr", "ts", "tt", "tw", "ty", "ug", "uk", "ur", "uz", "ve", "vi", "vo", "wa", "wo", "xh", "yi", "yo", "za", "zh", "zu" ] }, "ProxyState": { "type": "string", "enum": [ "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY", "al", "ak", "az", "ar", "ca", "co", "ct", "de", "fl", "ga", "hi", "id", "il", "in", "ia", "ks", "ky", "la", "me", "md", "ma", "mi", "mn", "ms", "mo", "mt", "ne", "nv", "nh", "nj", "nm", "ny", "nc", "nd", "oh", "ok", "or", "pa", "ri", "sc", "sd", "tn", "tx", "ut", "vt", "va", "wa", "wv", "wi", "wy" ], "nullable": true, "description": "Optional state code for proxies to US states. Is mutually exclusive with proxyCity. Takes in two letter state code." }, "SessionRegion": { "type": "string", "description": "Region to run the session in. The asia-south region is only available on Enterprise and Select plans. Get in touch at https://calendly.com/shri-hyperbrowser/demo.", "enum": [ "us", "us-central", "us-west", "us-east", "asia-south", "europe-west" ] }, "JobStatus": { "type": "string", "enum": [ "pending", "running", "completed", "failed", "stopped" ] }, "JobStatusResponse": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/JobStatus" } }, "required": [ "status" ] }, "RecordingStatus": { "type": "string", "enum": [ "not_enabled", "pending", "in_progress", "completed", "failed" ] }, "DownloadsStatus": { "type": "string", "enum": [ "not_enabled", "pending", "in_progress", "completed", "failed" ] }, "CrawledPage": { "type": "object", "properties": { "url": { "type": "string" }, "status": { "type": "string", "enum": [ "completed", "failed" ] }, "error": { "type": "string", "nullable": true }, "metadata": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } }, "markdown": { "type": "string" }, "html": { "type": "string" }, "links": { "type": "array", "items": { "type": "string" } }, "screenshot": { "type": "string" } }, "required": [ "url", "status" ] }, "ScrapeOptions": { "type": "object", "properties": { "formats": { "type": "array", "items": { "type": "string", "enum": [ "html", "links", "markdown", "screenshot" ] }, "default": [ "markdown" ] }, "includeTags": { "type": "array", "items": { "type": "string" } }, "excludeTags": { "type": "array", "items": { "type": "string" } }, "onlyMainContent": { "type": "boolean", "default": true }, "waitFor": { "type": "number", "default": 0 }, "timeout": { "type": "number", "default": 30000 }, "waitUntil": { "type": "string", "enum": [ "load", "domcontentloaded", "networkidle" ], "default": "load" }, "screenshotOptions": { "type": "object", "description": "Options for the screenshot. Both `fullPage` and `cropToContent` cannot be true at the same time.", "properties": { "fullPage": { "type": "boolean", "default": false }, "format": { "type": "string", "enum": [ "jpeg", "png", "webp" ], "default": "webp" }, "cropToContent": { "type": "boolean", "default": false, "description": "Automatically adjusts the screenshot height to match the page's actual content. If the page is shorter than the viewport, the screenshot is trimmed to remove any empty space below the content. If the page is taller than the viewport, the screenshot is cropped to the height of the viewport." }, "cropToContentMaxHeight": { "type": "number", "description": "The maximum height of the screenshot when `cropToContent` is true. Overrides the height set in the `screen` configuration." }, "cropToContentMinHeight": { "type": "number", "description": "The minimum height of the screenshot when `cropToContent` is true. Overrides the height set in the `screen` configuration." } } }, "storageState": { "type": "object", "properties": { "localStorage": { "type": "object", "additionalProperties": { "type": "string" } }, "sessionStorage": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "CreateSessionProfile": { "type": "object", "properties": { "id": { "type": "string" }, "persistChanges": { "type": "boolean" }, "persistNetworkCache": { "type": "boolean", "description": "When persisting profile changes, also persist the browser's network cache (HTTP cache)." } } }, "CreateSessionParams": { "type": "object", "properties": { "useUltraStealth": { "type": "boolean", "default": false }, "useStealth": { "type": "boolean", "default": false }, "useProxy": { "type": "boolean", "default": false }, "proxyServer": { "type": "string", "description": "Custom proxy server host." }, "proxyServerPassword": { "type": "string", "description": "Password for authenticating with the custom proxy server." }, "proxyServerUsername": { "type": "string", "description": "Username for authenticating with the custom proxy server." }, "proxyCountry": { "$ref": "#/components/schemas/ProxyCountry" }, "proxyState": { "$ref": "#/components/schemas/ProxyState" }, "proxyCity": { "type": "string", "example": "new york", "nullable": true, "description": "Desired Country. Is mutually exclusive with proxyState. Some cities might not be supported, so before using a new city, we recommend trying it out" }, "region": { "$ref": "#/components/schemas/SessionRegion" }, "operatingSystems": { "type": "array", "items": { "$ref": "#/components/schemas/OperatingSystem" } }, "device": { "type": "array", "items": { "$ref": "#/components/schemas/Device" } }, "platform": { "type": "array", "items": { "$ref": "#/components/schemas/Platform" } }, "locales": { "type": "array", "items": { "$ref": "#/components/schemas/ISO639_1" }, "default": [ "en" ] }, "screen": { "$ref": "#/components/schemas/ScreenConfig" }, "solveCaptchas": { "type": "boolean", "default": false }, "solverType": { "type": "string", "enum": [ "visual" ], "description": "Optional CAPTCHA solver mode. Set to visual to use the visual reCAPTCHA solver." }, "adblock": { "type": "boolean", "default": false }, "trackers": { "type": "boolean", "default": false }, "annoyances": { "type": "boolean", "default": false }, "enableWebRecording": { "type": "boolean" }, "enableVideoWebRecording": { "type": "boolean", "default": false, "description": "enableWebRecording must also be true for this to work" }, "profile": { "$ref": "#/components/schemas/CreateSessionProfile" }, "acceptCookies": { "type": "boolean" }, "staticIpId": { "type": "string", "format": "uuid" }, "saveDownloads": { "type": "boolean", "default": false }, "extensionIds": { "type": "array", "items": { "type": "string", "format": "uuid", "nullable": false }, "default": [] }, "urlBlocklist": { "type": "array", "items": { "type": "string", "nullable": false }, "default": [] }, "browserArgs": { "type": "array", "items": { "type": "string", "nullable": false }, "default": [] }, "imageCaptchaParams": { "type": "array", "items": { "type": "object", "properties": { "imageSelector": { "type": "string" }, "inputSelector": { "type": "string" } } }, "nullable": true }, "timeoutMinutes": { "type": "number", "minimum": 1, "maximum": 720 }, "enableWindowManager": { "type": "boolean", "default": false }, "enableWindowManagerTaskbar": { "type": "boolean", "default": false }, "viewOnlyLiveView": { "type": "boolean", "default": false }, "disablePasswordManager": { "type": "boolean", "default": false }, "enableAlwaysOpenPdfExternally": { "type": "boolean", "default": false }, "disablePostQuantumKeyAgreement": { "type": "boolean", "default": false }, "enableWebMcp": { "type": "boolean", "default": false, "description": "Enable discovery and invocation of WebMCP tools exposed by pages in this browser session. Must be set when creating the session; disabled by default." }, "credentials": { "type": "array", "maxItems": 20, "items": { "oneOf": [ { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$", "description": "A secret's name." }, { "type": "object", "properties": { "secret": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$", "description": "A secret's name." } }, "required": [ "secret" ], "additionalProperties": false }, { "type": "object", "properties": { "vault": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$", "description": "A vault's name: attaches the secrets its entries point at now." } }, "required": [ "vault" ], "additionalProperties": false }, { "type": "object", "properties": { "onePassword": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$", "description": "An `op_token` secret's name: 1Password fills in this session may read with it. The token itself is never typed." } }, "required": [ "onePassword" ], "additionalProperties": false } ] }, "description": "Secrets the session may fill with POST /api/session/{id}/credentials/fill: a secret's name, `{\"secret\": name}`, `{\"vault\": name}` for the secrets a vault's entries point at, or `{\"onePassword\": name}` for an `op_token` secret that 1Password fills read with. You can only attach them when you create the session; an empty list is the same as none. Only `secret` and `totp` secrets can be attached as a name, `secret` or vault entry, and only an `op_token` as `onePassword`. Requires secrets to be enabled for your team; please contact support to enable them (otherwise 403 SECRETS_FEATURE_DISABLED), and, for restricted API keys, the secrets.use scope. The session runs on a Firecracker browser and Chrome's password manager is turned off. An unknown name returns 404 SECRET_NOT_FOUND or VAULT_NOT_FOUND, an `op_token` secret named as a credential, or a `onePassword` that isn't an `op_token`, 409 SECRET_TYPE_MISMATCH and a vault without entries 400 SECRET_SOURCES_INVALID. If the session can't run on Firecracker, you get 400 CREDENTIALS_UNSUPPORTED_RUNTIME, or 429 when no Firecracker host is free (retry shortly). Restoring a browser snapshot taken with the password manager on returns 400 CREDENTIALS_SNAPSHOT_PASSWORD_MANAGER_ENABLED." }, "webBotAuth": { "oneOf": [ { "type": "boolean" }, { "$ref": "#/components/schemas/WebBotAuthParams" } ], "description": "Sign the session's requests with [Web Bot Auth](/sessions/web-bot-auth) so websites can verify that they come from Hyperbrowser. Pass `{\"onlyDomains\": [...]}` to sign only for those hosts. Available on request: contact info@hyperbrowser.ai to get access. Supported when creating a session and for agent tasks; scrape, crawl, and extract reject it. Cannot be combined with `useUltraStealth` or `startFromSnapshot`." }, "proxyRoutes": { "type": "array", "maxItems": 32, "items": { "$ref": "#/components/schemas/ProxyRoute" }, "description": "Choose, per host, whether traffic goes through the session's proxy or straight out. The first route that matches a host decides; hosts that no route matches use the proxy. At most 128 patterns across all routes. Requires `useProxy`. Available on request: contact info@hyperbrowser.ai to get access. See [proxy routes](/sessions/proxy-routes). Only supported when creating a session; cannot be combined with `allowInternetAccess: false`, `allowOut`, or `denyOut`." } }, "default": { "useStealth": false, "useProxy": false, "acceptCookies": false } }, "WebBotAuthParams": { "type": "object", "additionalProperties": false, "description": "Limits Web Bot Auth signing to some hosts.", "properties": { "onlyDomains": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50, "description": "Sign only requests to these hostnames (for example `example.com`) and their subdomains. No scheme, port, or path." } } }, "ProxyRoute": { "type": "object", "additionalProperties": false, "required": [ "match", "proxy" ], "description": "Sends traffic for matching hosts through the session's proxy or straight out.", "properties": { "match": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 1 } ], "description": "A hostname, `*.example.com` (subdomains, not `example.com` itself), or `*` (every host), or a list of them. Ports, URLs, and IP addresses are not accepted." }, "proxy": { "type": "string", "enum": [ "direct", "default" ], "description": "`direct` sends the traffic straight out of the browser's machine; `default` sends it through the session's proxy." } } }, "GetSessionRecordingUrlResponse": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/RecordingStatus" }, "recordingUrl": { "type": "string", "nullable": true }, "error": { "type": "string", "nullable": true } }, "required": [ "status" ] }, "GetSessionVideoRecordingUrlResponse": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/RecordingStatus" }, "recordingUrl": { "type": "string", "nullable": true }, "error": { "type": "string", "nullable": true } }, "required": [ "status" ] }, "GetSessionDownloadsUrlResponse": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/DownloadsStatus" }, "downloadsUrl": { "type": "string", "nullable": true }, "error": { "type": "string", "nullable": true } }, "required": [ "status" ] }, "StartScrapeJobParams": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "minLength": 1 }, "sessionOptions": { "$ref": "#/components/schemas/CreateSessionParams" }, "scrapeOptions": { "$ref": "#/components/schemas/ScrapeOptions" } } }, "StartScrapeJobResponse": { "type": "object", "properties": { "jobId": { "type": "string" } } }, "ScrapeJobData": { "type": "object", "properties": { "metadata": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } }, "markdown": { "type": "string" }, "html": { "type": "string" }, "links": { "type": "array", "items": { "type": "string" } }, "screenshot": { "type": "string" } } }, "ScrapeJobResponse": { "type": "object", "properties": { "jobId": { "type": "string" }, "status": { "$ref": "#/components/schemas/JobStatus" }, "data": { "$ref": "#/components/schemas/ScrapeJobData" }, "error": { "type": "string" } }, "required": [ "jobId", "status" ] }, "StartBatchScrapeJobParams": { "type": "object", "properties": { "urls": { "type": "array", "items": { "type": "string" } }, "sessionOptions": { "$ref": "#/components/schemas/CreateSessionParams" }, "scrapeOptions": { "$ref": "#/components/schemas/ScrapeOptions" } }, "required": [ "urls" ] }, "ScrapedPage": { "type": "object", "properties": { "url": { "type": "string" }, "status": { "$ref": "#/components/schemas/JobStatus" }, "error": { "type": "string", "nullable": true }, "metadata": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } }, "markdown": { "type": "string" }, "html": { "type": "string" }, "links": { "type": "array", "items": { "type": "string" } }, "screenshot": { "type": "string" } }, "required": [ "url", "status" ] }, "GetBatchScrapeJobParams": { "type": "object", "properties": { "page": { "type": "number" }, "batchSize": { "type": "number" } } }, "StartBatchScrapeJobResponse": { "type": "object", "properties": { "jobId": { "type": "string" } }, "required": [ "jobId" ] }, "BatchScrapeJobResponse": { "type": "object", "properties": { "jobId": { "type": "string" }, "status": { "$ref": "#/components/schemas/JobStatus" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ScrapedPage" } }, "error": { "type": "string" }, "totalScrapedPages": { "type": "number" }, "totalPageBatches": { "type": "number" }, "currentPageBatch": { "type": "number" }, "batchSize": { "type": "number" } } }, "StartExtractJobParams": { "type": "object", "properties": { "urls": { "type": "array", "items": { "type": "string" } }, "systemPrompt": { "type": "string" }, "maxLinks": { "type": "number" }, "prompt": { "type": "string" }, "schema": { "type": "object" }, "sessionOptions": { "$ref": "#/components/schemas/CreateSessionParams" }, "waitFor": { "default": 0, "type": "number" } }, "additionalProperties": false, "required": [ "urls" ] }, "StartExtractJobResponse": { "type": "object", "properties": { "jobId": { "type": "string" } }, "required": [ "jobId" ] }, "ExtractJobResponse": { "type": "object", "properties": { "jobId": { "type": "string" }, "status": { "$ref": "#/components/schemas/JobStatus" }, "data": { "type": "object" }, "error": { "type": "string" } }, "additionalProperties": false, "required": [ "jobId", "status" ] }, "ErrorResponse": { "type": "object", "properties": { "message": { "type": "string" } } }, "CreateExtensionParams": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" }, "name": { "type": "string" } }, "required": [ "file" ] }, "ExtensionResponse": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "createdAt": { "type": "string", "format": "iso8601" }, "updatedAt": { "type": "string", "format": "iso8601" } } }, "HyperAgentVersion": { "type": "string", "enum": [ "0.8.0", "1.1.0" ], "default": "0.8.0" }, "HyperAgentLlm": { "type": "string", "enum": [ "gpt-6-luna", "gpt-5.6-luna", "gpt-5.5", "gpt-5.2", "gpt-5.1", "gpt-5", "gpt-5-mini", "gpt-4o", "gpt-4o-mini", "gpt-4.1", "gpt-4.1-mini", "claude-sonnet-5", "claude-sonnet-4-6", "claude-haiku-5-5", "gemini-2.5-flash", "gemini-3.8-flash", "gemini-3.7-flash", "gemini-3-flash-preview" ], "default": "gpt-4o" }, "StartHyperAgentTaskParams": { "type": "object", "properties": { "task": { "type": "string" }, "version": { "$ref": "#/components/schemas/HyperAgentVersion" }, "llm": { "$ref": "#/components/schemas/HyperAgentLlm" }, "sessionId": { "type": "string" }, "maxSteps": { "type": "number", "default": 20 }, "keepBrowserOpen": { "type": "boolean", "default": false }, "sessionOptions": { "$ref": "#/components/schemas/CreateSessionParams" }, "useCustomApiKeys": { "type": "boolean", "default": false }, "apiKeys": { "type": "object", "properties": { "openai": { "type": "string" }, "anthropic": { "type": "string" }, "google": { "type": "string" } } } }, "required": [ "task" ], "default": { "task": "go to example.com" } }, "StartHyperAgentTaskResponse": { "type": "object", "properties": { "jobId": { "type": "string" }, "liveUrl": { "type": "string", "nullable": true } }, "required": [ "jobId" ] }, "HyperAgentTaskResponse": { "type": "object", "properties": { "jobId": { "type": "string" }, "status": { "$ref": "#/components/schemas/JobStatus" }, "data": { "type": "object", "properties": { "steps": { "type": "array", "items": { "type": "object" } }, "finalResult": { "type": "string", "nullable": true } } }, "error": { "type": "string", "nullable": true }, "liveUrl": { "type": "string", "nullable": true } }, "required": [ "jobId", "status" ] }, "BrowserUseVersion": { "type": "string", "enum": [ "0.1.40", "0.7.10", "latest" ], "default": "0.1.40" }, "BrowserUseLlm": { "type": "string", "enum": [ "gpt-4o", "gpt-4o-mini", "gpt-4.1", "gpt-4.1-mini", "claude-sonnet-5", "claude-sonnet-4-6", "claude-haiku-5-5", "gemini-2.0-flash", "gemini-2.5-flash", "gemini-3.8-flash" ], "default": "gemini-2.0-flash" }, "StartBrowserUseTaskParams": { "type": "object", "properties": { "task": { "type": "string" }, "version": { "$ref": "#/components/schemas/BrowserUseVersion" }, "llm": { "$ref": "#/components/schemas/BrowserUseLlm" }, "sessionId": { "type": "string" }, "validateOutput": { "type": "boolean", "default": false }, "useVision": { "type": "boolean", "default": true }, "useVisionForPlanner": { "type": "boolean", "default": false }, "maxActionsPerStep": { "type": "number", "default": 10 }, "maxInputTokens": { "type": "number", "default": 128000 }, "plannerLlm": { "$ref": "#/components/schemas/BrowserUseLlm" }, "pageExtractionLlm": { "$ref": "#/components/schemas/BrowserUseLlm" }, "plannerInterval": { "type": "number", "default": 10 }, "maxSteps": { "type": "number", "default": 20 }, "maxFailures": { "type": "number", "default": 3 }, "initialActions": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": true } } }, "sensitiveData": { "type": "object", "additionalProperties": { "type": "string" } }, "messageContext": { "type": "string" }, "keepBrowserOpen": { "type": "boolean", "default": false }, "sessionOptions": { "$ref": "#/components/schemas/CreateSessionParams" }, "useCustomApiKeys": { "type": "boolean", "default": false }, "apiKeys": { "type": "object", "properties": { "openai": { "type": "string" }, "anthropic": { "type": "string" }, "google": { "type": "string" } } } }, "required": [ "task" ], "default": { "task": "go to example.com" } }, "StartBrowserUseTaskResponse": { "type": "object", "properties": { "jobId": { "type": "string" }, "liveUrl": { "type": "string", "nullable": true } }, "required": [ "jobId" ] }, "BrowserUseTaskResponse": { "type": "object", "properties": { "jobId": { "type": "string" }, "status": { "$ref": "#/components/schemas/JobStatus" }, "data": { "type": "object", "properties": { "steps": { "type": "array", "items": { "type": "object" } }, "finalResult": { "type": "string", "nullable": true } } }, "error": { "type": "string", "nullable": true }, "liveUrl": { "type": "string", "nullable": true } }, "required": [ "jobId", "status" ] }, "ClaudeComputerUseLlm": { "type": "string", "enum": [ "claude-opus-5-5", "claude-fable-5-1", "claude-opus-5", "claude-opus-4-5", "claude-opus-4-6", "claude-opus-4-7", "claude-opus-4-8", "claude-haiku-5-5", "claude-haiku-4-5-20251001", "claude-sonnet-5-5", "claude-sonnet-5", "claude-sonnet-4-6" ], "default": "claude-sonnet-5-5" }, "ClaudeComputerUseReasoningEffort": { "type": "string", "enum": [ "low", "medium", "high", "xhigh", "max" ] }, "StartClaudeComputerUseTaskParams": { "type": "object", "properties": { "task": { "type": "string" }, "llm": { "$ref": "#/components/schemas/ClaudeComputerUseLlm" }, "reasoningEffort": { "$ref": "#/components/schemas/ClaudeComputerUseReasoningEffort" }, "sessionId": { "type": "string" }, "maxFailures": { "type": "number", "default": 3 }, "maxSteps": { "type": "number", "default": 20 }, "keepBrowserOpen": { "type": "boolean", "default": false }, "sessionOptions": { "$ref": "#/components/schemas/CreateSessionParams" }, "useCustomApiKeys": { "type": "boolean", "default": false }, "apiKeys": { "type": "object", "properties": { "anthropic": { "type": "string" } } }, "useComputerAction": { "type": "boolean", "default": false } }, "required": [ "task" ], "default": { "task": "go to example.com" } }, "StartClaudeComputerUseTaskResponse": { "type": "object", "properties": { "jobId": { "type": "string" }, "liveUrl": { "type": "string", "nullable": true } }, "required": [ "jobId" ] }, "ClaudeComputerUseTaskResponse": { "type": "object", "properties": { "jobId": { "type": "string" }, "status": { "$ref": "#/components/schemas/JobStatus" }, "data": { "type": "object", "properties": { "steps": { "type": "array", "items": { "type": "object" } }, "finalResult": { "type": "string", "nullable": true } } }, "error": { "type": "string", "nullable": true }, "liveUrl": { "type": "string", "nullable": true } }, "required": [ "jobId", "status" ] }, "GeminiComputerUseLlm": { "type": "string", "enum": [ "gemini-4-argon", "gemini-3.8-flash", "gemini-3.7-flash", "gemini-3.6-flash", "gemini-3.5-flash", "gemini-3.5-flash-lite", "gemini-3-flash-preview", "gemini-2.5-computer-use-preview-10-2025" ], "default": "gemini-3.8-flash" }, "GeminiComputerUseReasoningEffort": { "type": "string", "description": "Optional reasoning effort for Gemini. Omit to use the model's default. gemini-4-argon, gemini-3.8-flash, and gemini-3.7-flash support low, medium, and high. gemini-3.6-flash, gemini-3.5-flash, gemini-3.5-flash-lite, and gemini-3-flash-preview also support minimal.", "enum": [ "minimal", "low", "medium", "high" ] }, "StartGeminiComputerUseTaskParams": { "type": "object", "properties": { "task": { "type": "string" }, "llm": { "$ref": "#/components/schemas/GeminiComputerUseLlm" }, "reasoningEffort": { "$ref": "#/components/schemas/GeminiComputerUseReasoningEffort" }, "sessionId": { "type": "string" }, "maxFailures": { "type": "number", "default": 3 }, "maxSteps": { "type": "number", "default": 20 }, "keepBrowserOpen": { "type": "boolean", "default": false }, "sessionOptions": { "$ref": "#/components/schemas/CreateSessionParams" }, "useCustomApiKeys": { "type": "boolean", "default": false }, "apiKeys": { "type": "object", "properties": { "google": { "type": "string" } } }, "useComputerAction": { "type": "boolean", "default": false } }, "required": [ "task" ], "default": { "task": "go to example.com" } }, "StartGeminiComputerUseTaskResponse": { "type": "object", "properties": { "jobId": { "type": "string" }, "liveUrl": { "type": "string", "nullable": true } }, "required": [ "jobId" ] }, "GeminiComputerUseTaskResponse": { "type": "object", "properties": { "jobId": { "type": "string" }, "status": { "$ref": "#/components/schemas/JobStatus" }, "data": { "type": "object", "properties": { "steps": { "type": "array", "items": { "type": "object" } }, "finalResult": { "type": "string", "nullable": true } } }, "error": { "type": "string", "nullable": true }, "liveUrl": { "type": "string", "nullable": true } }, "required": [ "jobId", "status" ] }, "MetaComputerUseLlm": { "type": "string", "enum": [ "muse-spark-1.1", "muse-spark-1.2", "muse-spark-1.3", "muse-wonder-1.0" ], "default": "muse-spark-1.3" }, "MetaReasoningEffort": { "type": "string", "description": "Reasoning effort for Muse Spark and Muse Wonder. The max effort is only supported by muse-spark-1.3 and muse-wonder-1.0.", "enum": [ "minimal", "low", "medium", "high", "xhigh", "max" ], "default": "medium" }, "StartMetaComputerUseTaskParams": { "type": "object", "properties": { "task": { "type": "string" }, "llm": { "$ref": "#/components/schemas/MetaComputerUseLlm" }, "reasoningEffort": { "$ref": "#/components/schemas/MetaReasoningEffort" }, "sessionId": { "type": "string" }, "maxFailures": { "type": "number", "default": 3 }, "maxSteps": { "type": "number", "default": 50 }, "keepBrowserOpen": { "type": "boolean", "default": false }, "sessionOptions": { "$ref": "#/components/schemas/CreateSessionParams" }, "useCustomApiKeys": { "type": "boolean", "default": false }, "apiKeys": { "type": "object", "properties": { "meta": { "type": "string" } } }, "useComputerAction": { "type": "boolean", "default": true } }, "required": [ "task" ], "default": { "task": "go to example.com" } }, "StartMetaComputerUseTaskResponse": { "type": "object", "properties": { "jobId": { "type": "string" }, "liveUrl": { "type": "string", "nullable": true } }, "required": [ "jobId" ] }, "MetaComputerUseTaskResponse": { "type": "object", "properties": { "jobId": { "type": "string" }, "status": { "$ref": "#/components/schemas/JobStatus" }, "data": { "type": "object", "properties": { "steps": { "type": "array", "items": { "type": "object" } }, "finalResult": { "type": "string", "nullable": true } } }, "error": { "type": "string", "nullable": true }, "liveUrl": { "type": "string", "nullable": true } }, "required": [ "jobId", "status" ] }, "GrokComputerUseLlm": { "type": "string", "enum": [ "grok-4.7", "grok-4.6", "grok-4.5" ], "default": "grok-4.7" }, "GrokReasoningEffort": { "type": "string", "enum": [ "low", "medium", "high" ], "default": "medium" }, "StartGrokComputerUseTaskParams": { "type": "object", "properties": { "task": { "type": "string" }, "llm": { "$ref": "#/components/schemas/GrokComputerUseLlm" }, "reasoningEffort": { "$ref": "#/components/schemas/GrokReasoningEffort" }, "sessionId": { "type": "string" }, "maxFailures": { "type": "number", "default": 3 }, "maxSteps": { "type": "number", "default": 50 }, "keepBrowserOpen": { "type": "boolean", "default": false }, "sessionOptions": { "$ref": "#/components/schemas/CreateSessionParams" }, "useCustomApiKeys": { "type": "boolean", "default": false }, "apiKeys": { "type": "object", "properties": { "xai": { "type": "string" } } }, "useComputerAction": { "type": "boolean", "default": true } }, "required": [ "task" ], "default": { "task": "go to example.com" } }, "StartGrokComputerUseTaskResponse": { "type": "object", "properties": { "jobId": { "type": "string" }, "liveUrl": { "type": "string", "nullable": true } }, "required": [ "jobId" ] }, "GrokComputerUseTaskResponse": { "type": "object", "properties": { "jobId": { "type": "string" }, "status": { "$ref": "#/components/schemas/JobStatus" }, "data": { "type": "object", "properties": { "steps": { "type": "array", "items": { "type": "object" } }, "finalResult": { "type": "string", "nullable": true } } }, "error": { "type": "string", "nullable": true }, "liveUrl": { "type": "string", "nullable": true } }, "required": [ "jobId", "status" ] }, "JevComputerUseLlm": { "type": "string", "enum": [ "jev-1.13.0", "jev-latest" ], "default": "jev-1.13.0" }, "JevTextLlm": { "type": "string", "enum": [ "gemini-3.5-flash-lite" ], "default": "gemini-3.5-flash-lite" }, "StartJevComputerUseTaskParams": { "type": "object", "properties": { "task": { "type": "string" }, "llm": { "$ref": "#/components/schemas/JevComputerUseLlm" }, "textLlm": { "$ref": "#/components/schemas/JevTextLlm" }, "sessionId": { "type": "string" }, "maxFailures": { "type": "number", "default": 3 }, "maxSteps": { "type": "number", "default": 100 }, "keepBrowserOpen": { "type": "boolean", "default": false }, "sessionOptions": { "$ref": "#/components/schemas/CreateSessionParams" }, "useCustomApiKeys": { "type": "boolean", "default": false }, "apiKeys": { "type": "object", "properties": { "jev": { "type": "string" }, "google": { "type": "string" } } } }, "required": [ "task" ], "default": { "task": "go to example.com" } }, "StartJevComputerUseTaskResponse": { "type": "object", "properties": { "jobId": { "type": "string" }, "liveUrl": { "type": "string", "nullable": true } }, "required": [ "jobId" ] }, "JevComputerUseTaskResponse": { "type": "object", "properties": { "jobId": { "type": "string" }, "status": { "$ref": "#/components/schemas/JobStatus" }, "data": { "type": "object", "properties": { "steps": { "type": "array", "items": { "type": "object" } }, "finalResult": { "type": "string", "nullable": true } } }, "error": { "type": "string", "nullable": true }, "liveUrl": { "type": "string", "nullable": true } }, "required": [ "jobId", "status" ] }, "CuaLlm": { "type": "string", "enum": [ "computer-use-preview", "gpt-6-astra", "gpt-6.1-sol", "gpt-6.1-terra", "gpt-6-sol", "gpt-6-luna", "gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", "gpt-5.5", "gpt-5.4", "gpt-5.4-mini" ], "default": "computer-use-preview" }, "CuaReasoningEffort": { "type": "string", "enum": [ "none", "low", "medium", "high", "xhigh", "max" ], "default": "medium" }, "StartCuaTaskParams": { "type": "object", "properties": { "task": { "type": "string" }, "llm": { "$ref": "#/components/schemas/CuaLlm" }, "reasoningEffort": { "$ref": "#/components/schemas/CuaReasoningEffort" }, "sessionId": { "type": "string" }, "maxFailures": { "type": "number", "default": 3 }, "maxSteps": { "type": "number", "default": 20 }, "keepBrowserOpen": { "type": "boolean", "default": false }, "sessionOptions": { "$ref": "#/components/schemas/CreateSessionParams" }, "useCustomApiKeys": { "type": "boolean", "default": false }, "apiKeys": { "type": "object", "properties": { "openai": { "type": "string" } } }, "useComputerAction": { "type": "boolean", "default": false } }, "required": [ "task" ], "default": { "task": "go to example.com" } }, "StartCuaTaskResponse": { "type": "object", "properties": { "jobId": { "type": "string" }, "liveUrl": { "type": "string", "nullable": true } }, "required": [ "jobId" ] }, "CuaTaskResponse": { "type": "object", "properties": { "jobId": { "type": "string" }, "status": { "$ref": "#/components/schemas/JobStatus" }, "data": { "type": "object", "properties": { "steps": { "type": "array", "items": { "type": "object" } }, "finalResult": { "type": "string", "nullable": true } } }, "error": { "type": "string", "nullable": true }, "liveUrl": { "type": "string", "nullable": true } }, "required": [ "jobId", "status" ] }, "FetchStealthMode": { "type": "string", "enum": [ "none", "auto", "ultra" ] }, "FetchSanitizeMode": { "type": "string", "enum": [ "none", "basic", "advanced" ] }, "FetchStatus": { "type": "string", "enum": [ "completed", "failed", "pending", "running" ] }, "FetchWaitUntil": { "type": "string", "enum": [ "load", "domcontentloaded", "networkidle" ] }, "FetchScreenshotFormat": { "type": "string", "enum": [ "jpeg", "png", "webp" ] }, "PageStatus": { "type": "string", "enum": [ "completed", "failed", "pending", "running" ] }, "WebSearchStatus": { "type": "string", "enum": [ "completed", "failed", "pending", "running", "stopped" ] }, "WebSearchFiletype": { "type": "string", "enum": [ "pdf", "doc", "docx", "xls", "xlsx", "ppt", "pptx", "html" ] }, "FetchOutputScreenshotOptions": { "type": "object", "properties": { "fullPage": { "type": "boolean" }, "format": { "$ref": "#/components/schemas/FetchScreenshotFormat" }, "cropToContent": { "type": "boolean" }, "cropToContentMaxHeight": { "type": "integer" }, "cropToContentMinHeight": { "type": "integer" } } }, "FetchStorageStateOptions": { "type": "object", "properties": { "localStorage": { "type": "object", "additionalProperties": { "type": "string" } }, "sessionStorage": { "type": "object", "additionalProperties": { "type": "string" } } } }, "FetchBrowserLocationOptions": { "type": "object", "properties": { "country": { "type": "string" }, "state": { "type": "string" }, "city": { "type": "string" } } }, "FetchOutputMarkdown": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "markdown" ] } }, "required": [ "type" ] }, "FetchOutputHtml": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "html" ] } }, "required": [ "type" ] }, "FetchOutputLinks": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "links" ] } }, "required": [ "type" ] }, "FetchOutputScreenshot": { "allOf": [ { "$ref": "#/components/schemas/FetchOutputScreenshotOptions" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "screenshot" ] } }, "required": [ "type" ] } ] }, "FetchOutputJsonOptions": { "type": "object", "properties": { "schema": { "type": "object" }, "prompt": { "type": "string", "description": "Natural language prompt describing what data to extract. If only prompt is provided, a schema is auto-generated from it. If both prompt and schema are provided, the schema defines the output structure while the prompt provides additional guidance for the extraction." } } }, "FetchOutputJson": { "allOf": [ { "$ref": "#/components/schemas/FetchOutputJsonOptions" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json" ] } }, "required": [ "type" ] } ] }, "FetchOutputOptions": { "type": "object", "properties": { "formats": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/FetchOutputMarkdown" }, { "$ref": "#/components/schemas/FetchOutputHtml" }, { "$ref": "#/components/schemas/FetchOutputLinks" }, { "$ref": "#/components/schemas/FetchOutputScreenshot" }, { "$ref": "#/components/schemas/FetchOutputJson" }, { "$ref": "#/components/schemas/FetchOutputBranding" }, { "type": "string", "enum": [ "markdown", "html", "links", "screenshot", "branding" ] } ] } }, "sanitize": { "$ref": "#/components/schemas/FetchSanitizeMode" }, "includeSelectors": { "type": "array", "items": { "type": "string" } }, "excludeSelectors": { "type": "array", "items": { "type": "string" } }, "storageState": { "$ref": "#/components/schemas/FetchStorageStateOptions" } } }, "FetchBrowserOptions": { "type": "object", "properties": { "screen": { "$ref": "#/components/schemas/ScreenConfig" }, "profileId": { "type": "string" }, "solveCaptchas": { "type": "string" }, "location": { "$ref": "#/components/schemas/FetchBrowserLocationOptions" } } }, "FetchNavigationOptions": { "type": "object", "properties": { "waitUntil": { "$ref": "#/components/schemas/FetchWaitUntil" }, "timeoutMs": { "type": "integer" }, "waitFor": { "type": "integer" } } }, "FetchCacheOptions": { "type": "object", "properties": { "maxAgeSeconds": { "type": "integer" } } }, "FetchParams": { "type": "object", "properties": { "url": { "type": "string" }, "stealth": { "$ref": "#/components/schemas/FetchStealthMode" }, "outputs": { "$ref": "#/components/schemas/FetchOutputOptions" }, "browser": { "$ref": "#/components/schemas/FetchBrowserOptions" }, "navigation": { "$ref": "#/components/schemas/FetchNavigationOptions" }, "cache": { "$ref": "#/components/schemas/FetchCacheOptions" } }, "required": [ "url" ] }, "FetchResponseData": { "type": "object", "properties": { "metadata": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } }, "html": { "type": "string" }, "markdown": { "type": "string" }, "links": { "type": "array", "items": { "type": "string" } }, "screenshot": { "type": "string" }, "json": { "type": "object" }, "branding": { "$ref": "#/components/schemas/BrandingProfile" } } }, "FetchResponse": { "type": "object", "properties": { "jobId": { "type": "string" }, "status": { "$ref": "#/components/schemas/FetchStatus" }, "error": { "type": "string", "nullable": true }, "data": { "$ref": "#/components/schemas/FetchResponseData" } }, "required": [ "jobId", "status" ] }, "WebCrawlOptions": { "type": "object", "properties": { "maxPages": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "followLinks": { "type": "boolean", "default": true }, "ignoreSitemap": { "type": "boolean", "default": false }, "excludePatterns": { "type": "array", "items": { "type": "string" } }, "includePatterns": { "type": "array", "items": { "type": "string" } } } }, "StartWebCrawlJobParams": { "type": "object", "properties": { "url": { "type": "string" }, "stealth": { "$ref": "#/components/schemas/FetchStealthMode" }, "outputs": { "$ref": "#/components/schemas/FetchOutputOptions" }, "browser": { "$ref": "#/components/schemas/FetchBrowserOptions" }, "navigation": { "$ref": "#/components/schemas/FetchNavigationOptions" }, "cache": { "$ref": "#/components/schemas/FetchCacheOptions" }, "crawlOptions": { "$ref": "#/components/schemas/WebCrawlOptions" } }, "required": [ "url" ] }, "WebCrawlPageData": { "type": "object", "properties": { "url": { "type": "string" }, "status": { "$ref": "#/components/schemas/PageStatus" }, "error": { "type": "string", "nullable": true }, "metadata": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } }, "markdown": { "type": "string" }, "html": { "type": "string" }, "links": { "type": "array", "items": { "type": "string" } }, "screenshot": { "type": "string" }, "json": { "type": "object" }, "branding": { "$ref": "#/components/schemas/BrandingProfile" } }, "required": [ "url", "status" ] }, "WebCrawlJobResponse": { "type": "object", "properties": { "jobId": { "type": "string", "format": "uuid" }, "status": { "$ref": "#/components/schemas/JobStatus" }, "error": { "type": "string", "nullable": true }, "totalPages": { "type": "integer", "minimum": 0 }, "totalPageBatches": { "type": "integer", "minimum": 0 }, "currentPageBatch": { "type": "integer", "minimum": 0 }, "batchSize": { "type": "integer", "minimum": 1 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebCrawlPageData" } } }, "required": [ "status", "jobId" ] }, "WebSearchFilters": { "type": "object", "properties": { "exactPhrase": { "type": "boolean" }, "semanticPhrase": { "type": "boolean" }, "excludeTerms": { "type": "array", "items": { "type": "string" } }, "boostTerms": { "type": "array", "items": { "type": "string" } }, "filetype": { "$ref": "#/components/schemas/WebSearchFiletype" }, "site": { "type": "string" }, "excludeSite": { "type": "string" }, "intitle": { "type": "string" }, "inurl": { "type": "string" } } }, "WebSearchLocation": { "type": "object", "properties": { "country": { "type": "string" }, "state": { "type": "string" }, "city": { "type": "string" } }, "required": [ "country" ] }, "WebSearchParams": { "type": "object", "properties": { "query": { "type": "string" }, "page": { "type": "integer" }, "maxAgeSeconds": { "type": "integer" }, "location": { "$ref": "#/components/schemas/WebSearchLocation" }, "filters": { "$ref": "#/components/schemas/WebSearchFilters" } }, "required": [ "query" ] }, "WebSearchResultItem": { "type": "object", "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "description": { "type": "string" } }, "required": [ "title", "url", "description" ] }, "WebSearchResponseData": { "type": "object", "properties": { "query": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/WebSearchResultItem" } } }, "required": [ "query", "results" ] }, "WebSearchResponse": { "type": "object", "properties": { "jobId": { "type": "string" }, "status": { "$ref": "#/components/schemas/WebSearchStatus" }, "error": { "type": "string", "nullable": true }, "data": { "$ref": "#/components/schemas/WebSearchResponseData" } }, "required": [ "jobId", "status" ] }, "FetchOutputBranding": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "branding" ] } }, "required": [ "type" ] }, "BrandingProfile": { "type": "object", "description": "Visual brand profile extracted via DOM analysis + LLM enhancement. All fields optional; the server may return a partial profile when the LLM refuses or fails.", "properties": { "colorScheme": { "type": "string", "description": "Page color scheme. Common values: light, dark." }, "colors": { "type": "object", "description": "Color role assignments. Common keys: primary, secondary, accent, background, textPrimary, textSecondary, link." }, "fonts": { "type": "array", "description": "Cleaned brand fonts with roles.", "items": { "type": "object", "properties": { "family": { "type": "string" }, "role": { "type": "string" } } } }, "typography": { "type": "object", "description": "Font families, stacks, and sizes. Keys: fontFamilies, fontStacks, fontSizes, lineHeights, fontWeights." }, "spacing": { "type": "object", "description": "Spacing scale. Common keys: baseUnit, borderRadius, padding, margins, gridGutter." }, "components": { "type": "object", "description": "Per-component style dictionaries. Common keys: buttonPrimary, buttonSecondary, input. Each value has background, textColor, borderColor, borderRadius, borderRadiusCorners, shadow." }, "images": { "type": "object", "description": "Brand images. Common keys: logo, logoHref, logoAlt, favicon, ogImage." }, "personality": { "type": "object", "description": "Brand personality. Common keys: tone, energy, targetAudience." }, "designSystem": { "type": "object", "description": "Detected design system. Common keys: framework, componentLibrary." }, "confidence": { "type": "object", "description": "Confidence scores (0-1). Common keys: buttons, colors, overall." } } }, "SandboxNetworkPolicy": { "type": "object", "description": "Effective outbound network policy for a sandbox.", "properties": { "allowInternetAccess": { "type": "boolean", "default": true, "description": "Whether general outbound internet access is allowed." }, "allowOut": { "type": "array", "items": { "type": "string" }, "description": "Outbound allow rules. Each entry is an IPv4 address, CIDR range, or domain." }, "denyOut": { "type": "array", "items": { "type": "string" }, "description": "Outbound deny rules. Each entry is an IPv4 address or CIDR range." } }, "required": [ "allowInternetAccess", "allowOut", "denyOut" ] }, "SandboxNetworkPolicyPatch": { "type": "object", "description": "Partial network policy update. Omitted fields keep their current values.", "properties": { "allowInternetAccess": { "type": "boolean" }, "allowOut": { "type": "array", "items": { "type": "string" }, "description": "Outbound allow rules (IPv4 address, CIDR range, or domain)." }, "denyOut": { "type": "array", "items": { "type": "string" }, "description": "Outbound deny rules (IPv4 address or CIDR range)." } }, "additionalProperties": false }, "SandboxRuntimeTarget": { "type": "object", "description": "Runtime API connection details. Null while a GPU sandbox is provisioning, or if it ended before acquiring a runtime. Wait for status active before using these URLs.", "properties": { "transport": { "type": "string", "enum": [ "regional_proxy" ] }, "host": { "type": "string", "description": "Regional runtime origin." }, "baseUrl": { "type": "string", "description": "Base URL for runtime API requests for this sandbox." } }, "required": [ "transport", "host", "baseUrl" ], "nullable": true }, "SandboxExposedPort": { "type": "object", "properties": { "port": { "type": "integer", "minimum": 1, "maximum": 65535 }, "auth": { "type": "boolean", "description": "Whether requests to the exposed URL require authentication." }, "url": { "type": "string", "description": "Public URL that routes to the exposed port." }, "browserUrl": { "type": "string", "description": "URL that bootstraps browser access. For authenticated ports this includes a short-lived grant token." }, "browserUrlExpiresAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Expiry of the browser bootstrap grant, if auth is enabled." } }, "required": [ "port", "auth", "url" ] }, "SandboxExposePortParams": { "type": "object", "properties": { "port": { "type": "integer", "minimum": 1, "maximum": 65535, "description": "Port inside the sandbox to expose." }, "auth": { "type": "boolean", "default": false, "description": "Require authentication for requests to the exposed URL." } }, "required": [ "port" ] }, "SandboxUnexposePortParams": { "type": "object", "properties": { "port": { "type": "integer", "minimum": 1, "maximum": 65535 } }, "required": [ "port" ] }, "SandboxUnexposePortResponse": { "type": "object", "properties": { "port": { "type": "integer" }, "exposed": { "type": "boolean", "description": "Always false after a successful unexpose." } }, "required": [ "port", "exposed" ] }, "SandboxVolumeMount": { "type": "object", "description": "A volume mount attached at sandbox launch. Keys of the `mounts` map are absolute mount paths inside the sandbox.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Volume ID." }, "type": { "type": "string", "enum": [ "rw", "ro" ], "default": "rw", "description": "Mount access mode." }, "shared": { "type": "boolean", "description": "Allow the volume to be mounted by multiple sandboxes at once." } }, "required": [ "id" ] }, "CreateSandboxParams": { "type": "object", "description": "Provide exactly one start source: imageName (with optional imageId), snapshotName (CPU sandboxes, with optional snapshotId), or diskId (macOS). GPU sandboxes require GPU access, a GPU-ready team image, and region us. Set gpu to select the GPU runtime automatically. macOS is in beta and requires runtimeClass macos and region us. Contact info@hyperbrowser.ai for GPU or macOS access. Memory snapshots restore their original resources; Mac disk resizing is not supported.", "properties": { "runtimeClass": { "type": "string", "enum": [ "firecracker", "gvisor-cpu", "macos" ], "description": "Runtime selection. Requests without GPU or macOS options create CPU sandboxes (firecracker). Setting gpu selects gvisor-cpu automatically; omit runtimeClass for GPU creation. Set macos explicitly for a Mac sandbox." }, "gpu": { "type": "string", "enum": [ "L4", "A10G", "L40S", "A100-40GB", "A100-80GB", "RTX-PRO-6000", "H100", "H200", "B200", "B300" ], "description": "GPU product to allocate. Requires GPU access, region us, and a GPU-ready image built by your team. GPU sandboxes return HTTP 202 with status provisioning. Poll GET /api/sandbox/{id} until active before using the runtime. Availability depends on capacity and requested resources." }, "gpuCount": { "type": "integer", "minimum": 1, "maximum": 8, "default": 1, "description": "Number of whole GPUs of the requested type, on one host. Requires gpu. Supported counts depend on the GPU product and available host sizes." }, "diskId": { "type": "string", "format": "uuid", "description": "Existing persistent Mac disk to boot. Requires runtimeClass macos. Use instead of imageName or snapshotName. The disk must be ready and detached; each disk can run in only one sandbox at a time." }, "imageName": { "type": "string", "description": "Image name to launch from. CPU sandboxes can use a base image such as node or python, or a custom image. GPU sandboxes require a GPU-ready image built by your team; wait for gpuImageReady on its build. For macOS, use macos-base with runtimeClass macos; each image launch creates a new writable disk." }, "imageId": { "type": "string", "format": "uuid", "description": "Pin a specific image revision. Requires imageName." }, "snapshotName": { "type": "string", "description": "CPU sandbox memory snapshot to restore. GPU sandboxes do not support snapshots; macOS uses diskId instead." }, "snapshotId": { "type": "string", "format": "uuid", "description": "Pin a specific snapshot revision. Requires snapshotName." }, "region": { "$ref": "#/components/schemas/SessionRegion" }, "enableRecording": { "type": "boolean", "default": false, "description": "Enable recording. For macOS, captures an HLS desktop recording available in the dashboard Recording tab." }, "exposedPorts": { "type": "array", "items": { "$ref": "#/components/schemas/SandboxExposePortParams" }, "description": "Ports to expose at launch." }, "mounts": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/SandboxVolumeMount" }, "description": "Volume mounts, keyed by absolute mount path inside a CPU sandbox. GPU and macOS sandboxes do not support shared volume mounts." }, "vcpus": { "type": "integer", "minimum": 1, "maximum": 32, "description": "vCPU count for image launches or macOS disk launches. macOS requires at least 2 vCPUs; available sizes depend on your plan and host capacity." }, "memMiB": { "type": "integer", "minimum": 512, "maximum": 262144, "description": "System memory (RAM) in MiB for image launches or macOS disk launches. For GPU sandboxes this is separate from GPU memory (VRAM), which is determined by gpu. macOS requires at least 4096 MiB, in multiples of 1024 MiB. Plan and host limits apply." }, "diskSizeMiB": { "type": "integer", "minimum": 2048, "maximum": 65536, "description": "Disk size in MiB for image launches. GPU sandboxes default to and require at least 12288 MiB (12 GiB), with a maximum of 65536 MiB (64 GiB), subject to plan and host limits. GPU disk is ephemeral and files are deleted when the sandbox stops. For macOS, omit this field to use the source disk size; resizing is not supported." }, "timeoutMinutes": { "type": "integer", "maximum": 1440, "description": "Maximum sandbox lifetime in minutes, measured from when it starts running. For GPU sandboxes, provisioning time is excluded.", "minimum": 0 }, "allowInternetAccess": { "type": "boolean", "default": true, "description": "Outbound internet access policy." }, "allowOut": { "type": "array", "items": { "type": "string" }, "description": "Outbound allow rules (IPv4 address, CIDR range, or domain). macOS supports IPv4 addresses and CIDRs only." }, "denyOut": { "type": "array", "items": { "type": "string" }, "description": "Outbound deny rules (IPv4 address or CIDR range). macOS supports IPv4 addresses and CIDRs only." }, "secrets": { "allOf": [ { "$ref": "#/components/schemas/SecretReferences" } ], "description": "CPU image launches only; GPU and macOS sandboxes do not support secret injection. Secrets to set as environment variables for the image's startup command only, merged over `vault`'s variables; they aren't added to the sandbox's default environment. Supported for image launches of images that have a startup command; otherwise you get 400 SECRET_STARTUP_UNSUPPORTED (to run your own command with secrets, use POST /api/sandbox/{id}/processes). Requires secrets to be enabled for your team; please contact support to enable them (otherwise 403 SECRETS_FEATURE_DISABLED), and, for restricted API keys, the secrets.use scope. If the startup command can't be started, the sandbox is stopped and you get the host's error with its own code, such as 422 SECRET_VALUE_INVALID or 501 SECRET_TOTP_UNSUPPORTED, with `retryable` true for 5xx statuses since a new sandbox may run on another host. You get 502 SECRET_STARTUP_FAILED instead (with `causeCode` when the host gave one) when the host couldn't be reached, the command may have started, or stopping the sandbox couldn't be confirmed, and 422 SECRET_STARTUP_COMMAND_FAILED with `exitCode` when the command exits with 126 or 127 right after starting. SECRET_STARTUP_FAILED and SECRET_STARTUP_COMMAND_FAILED include `sandboxId` when stopping the sandbox couldn't be confirmed, so you can stop it yourself." }, "vault": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$", "description": "Name of a vault whose variables to set for the image's startup command, before `secrets`. The same rules as `secrets` apply, and together with `secrets` and `onePassword` they set at most 32 variables." }, "onePassword": { "allOf": [ { "$ref": "#/components/schemas/OnePasswordSource" } ], "description": "1Password fields to set as environment variables for the image's startup command, read from 1Password when it starts. The same rules as `secrets` apply. If 1Password can't provide a value, the sandbox is stopped and you get 422 SECRET_ONEPASSWORD_REFERENCE_FAILED or SECRET_ONEPASSWORD_AUTH_FAILED, 429 SECRET_ONEPASSWORD_RATE_LIMITED, or 502 or 503 SECRET_ONEPASSWORD_FAILED; all but the 422s are retryable." } }, "oneOf": [ { "title": "Image launch", "required": [ "imageName" ], "not": { "anyOf": [ { "required": [ "snapshotName" ] }, { "required": [ "snapshotId" ] }, { "required": [ "diskId" ] } ] } }, { "title": "Snapshot restore", "required": [ "snapshotName" ], "not": { "anyOf": [ { "required": [ "imageName" ] }, { "required": [ "imageId" ] }, { "required": [ "vcpus" ] }, { "required": [ "memMiB" ] }, { "required": [ "diskSizeMiB" ] }, { "required": [ "diskId" ] }, { "required": [ "runtimeClass" ], "properties": { "runtimeClass": { "enum": [ "macos" ] } } }, { "required": [ "gpu" ] }, { "required": [ "gpuCount" ] } ] } }, { "title": "macOS disk launch (Beta)", "required": [ "runtimeClass", "diskId" ], "properties": { "runtimeClass": { "enum": [ "macos" ] } }, "not": { "anyOf": [ { "required": [ "imageName" ] }, { "required": [ "imageId" ] }, { "required": [ "snapshotName" ] }, { "required": [ "snapshotId" ] }, { "required": [ "gpu" ] }, { "required": [ "gpuCount" ] } ] } } ] }, "SandboxStatus": { "type": "string", "enum": [ "provisioning", "active", "stopping", "closed", "close-error", "error" ], "description": "Current sandbox lifecycle status. GPU sandboxes begin in provisioning with no runtime or token. Poll until active, or stop on a terminal status and inspect closeReason. macOS can report stopping while disk changes are saved." }, "Sandbox": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "runtimeClass": { "type": "string", "enum": [ "firecracker", "gvisor-cpu", "macos" ], "description": "Runtime selected for this sandbox." }, "diskId": { "type": "string", "format": "uuid", "description": "Persistent disk ID, present for macOS sandboxes. Reuse it after the disk is ready and detached." }, "ready": { "type": "boolean", "description": "Present for macOS. True when the sandbox is active and its runtime is ready for commands. If false, fetch the sandbox again and check status before retrying." }, "teamId": { "type": "string" }, "status": { "$ref": "#/components/schemas/SandboxStatus" }, "startTime": { "oneOf": [ { "type": "number", "nullable": true }, { "type": "string", "pattern": "^[0-9]+$" } ], "description": "Start timestamp in epoch milliseconds, serialized as a number or numeric string. May be null." }, "endTime": { "oneOf": [ { "type": "number", "nullable": true }, { "type": "string", "pattern": "^[0-9]+$" } ], "description": "End timestamp in epoch milliseconds, serialized as a number or numeric string. May be null." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "closeReason": { "type": "string", "nullable": true }, "creditsUsed": { "type": "number", "nullable": true }, "region": { "$ref": "#/components/schemas/SessionRegion" }, "vcpus": { "type": "integer", "nullable": true }, "memMiB": { "type": "integer", "nullable": true }, "diskSizeMiB": { "type": "integer", "nullable": true }, "timeoutMinutes": { "type": "integer", "nullable": true }, "network": { "$ref": "#/components/schemas/SandboxNetworkPolicy" }, "sessionUrl": { "type": "string", "description": "Dashboard URL for this sandbox." }, "duration": { "type": "number", "description": "Total runtime in milliseconds (0 while running)." }, "proxyBytesUsed": { "type": "number" }, "runtime": { "$ref": "#/components/schemas/SandboxRuntimeTarget" }, "exposedPorts": { "type": "array", "items": { "$ref": "#/components/schemas/SandboxExposedPort" } }, "gpuType": { "type": "string", "nullable": true, "description": "Allocated GPU product, present for GPU sandboxes. Corresponds to the gpu creation parameter." }, "gpuCount": { "type": "integer", "nullable": true, "description": "Number of allocated GPUs, present for GPU sandboxes." }, "capabilities": { "$ref": "#/components/schemas/SandboxCapabilities" } }, "required": [ "id", "status", "region", "runtime", "exposedPorts" ] }, "SandboxDetail": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "runtimeClass": { "type": "string", "enum": [ "firecracker", "gvisor-cpu", "macos" ], "description": "Runtime selected for this sandbox." }, "diskId": { "type": "string", "format": "uuid", "description": "Persistent disk ID, present for macOS sandboxes. Reuse it after the disk is ready and detached." }, "ready": { "type": "boolean", "description": "Present for macOS. True when the sandbox is active and its runtime is ready for commands. If false, fetch the sandbox again and check status before retrying." }, "teamId": { "type": "string" }, "status": { "$ref": "#/components/schemas/SandboxStatus" }, "startTime": { "oneOf": [ { "type": "number", "nullable": true }, { "type": "string", "pattern": "^[0-9]+$" } ], "description": "Start timestamp in epoch milliseconds, serialized as a number or numeric string. May be null." }, "endTime": { "oneOf": [ { "type": "number", "nullable": true }, { "type": "string", "pattern": "^[0-9]+$" } ], "description": "End timestamp in epoch milliseconds, serialized as a number or numeric string. May be null." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "closeReason": { "type": "string", "nullable": true }, "creditsUsed": { "type": "number", "nullable": true }, "region": { "$ref": "#/components/schemas/SessionRegion" }, "vcpus": { "type": "integer", "nullable": true }, "memMiB": { "type": "integer", "nullable": true }, "diskSizeMiB": { "type": "integer", "nullable": true }, "timeoutMinutes": { "type": "integer", "nullable": true }, "network": { "$ref": "#/components/schemas/SandboxNetworkPolicy" }, "sessionUrl": { "type": "string", "description": "Dashboard URL for this sandbox." }, "duration": { "type": "number", "description": "Total runtime in milliseconds (0 while running)." }, "proxyBytesUsed": { "type": "number" }, "runtime": { "$ref": "#/components/schemas/SandboxRuntimeTarget" }, "exposedPorts": { "type": "array", "items": { "$ref": "#/components/schemas/SandboxExposedPort" } }, "token": { "type": "string", "nullable": true, "description": "Sandbox runtime session token (24h TTL). Send as Authorization: Bearer for runtime API calls. Null during GPU provisioning and when the sandbox is unavailable." }, "tokenExpiresAt": { "type": "string", "format": "date-time", "nullable": true }, "gpuType": { "type": "string", "nullable": true, "description": "Allocated GPU product, present for GPU sandboxes. Corresponds to the gpu creation parameter." }, "gpuCount": { "type": "integer", "nullable": true, "description": "Number of allocated GPUs, present for GPU sandboxes." }, "capabilities": { "$ref": "#/components/schemas/SandboxCapabilities" } }, "required": [ "id", "status", "region", "runtime", "exposedPorts" ] }, "CreateSandboxResponse": { "allOf": [ { "$ref": "#/components/schemas/SandboxDetail" }, { "type": "object", "properties": { "startupSecrets": { "type": "array", "items": { "$ref": "#/components/schemas/SandboxSecretBinding" }, "description": "Each variable the startup command received. Present only when you passed `secrets`, `vault` or `onePassword`." } } } ] }, "SandboxListResponse": { "type": "object", "properties": { "sandboxes": { "type": "array", "items": { "$ref": "#/components/schemas/Sandbox" } }, "totalCount": { "type": "integer" }, "page": { "type": "integer" }, "perPage": { "type": "integer" } }, "required": [ "sandboxes", "totalCount", "page", "perPage" ] }, "SandboxMemorySnapshotParams": { "type": "object", "properties": { "snapshotName": { "type": "string", "description": "Name for the snapshot. Auto-generated when omitted." } }, "additionalProperties": false }, "SandboxMemorySnapshotResponse": { "type": "object", "properties": { "snapshotName": { "type": "string" }, "snapshotId": { "type": "string", "format": "uuid" }, "namespace": { "type": "string" }, "status": { "type": "string", "description": "Snapshot status (e.g. `creating`, `created`)." }, "imageName": { "type": "string" }, "imageId": { "type": "string", "format": "uuid" }, "imageNamespace": { "type": "string" } }, "required": [ "snapshotName", "snapshotId", "namespace", "status" ] }, "SandboxNetworkUpdateResponse": { "type": "object", "properties": { "network": { "$ref": "#/components/schemas/SandboxNetworkPolicy" } }, "required": [ "network" ] }, "CreateVolumeParams": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "name" ], "additionalProperties": false }, "Volume": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "size": { "type": "number", "description": "Volume size in bytes." }, "transferAmount": { "type": "number", "description": "Data transferred in bytes." } }, "required": [ "id", "name" ] }, "VolumeDeleteResponse": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "id": { "type": "string", "description": "Deleted volume ID." }, "name": { "type": "string", "description": "Deleted volume name." } }, "required": [ "deleted", "id", "name" ] }, "VolumeListResponse": { "type": "object", "properties": { "volumes": { "type": "array", "items": { "$ref": "#/components/schemas/Volume" } }, "totalCount": { "type": "integer" }, "page": { "type": "integer" }, "perPage": { "type": "integer" } }, "required": [ "volumes", "totalCount", "page", "perPage" ] }, "SandboxImage": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "imageName": { "type": "string" }, "namespace": { "type": "string" }, "source": { "type": "string", "enum": [ "public", "team" ] }, "imageInit": { "type": "object", "nullable": true, "description": "Startup configuration derived from the image (entrypoint, env, user)." }, "uploaded": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "imageName", "namespace", "source", "uploaded" ] }, "SandboxImageListResponse": { "type": "object", "properties": { "images": { "type": "array", "items": { "$ref": "#/components/schemas/SandboxImage" } }, "totalCount": { "type": "integer" }, "page": { "type": "integer" }, "perPage": { "type": "integer" } }, "required": [ "images", "totalCount", "page", "perPage" ] }, "SandboxSnapshot": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "snapshotName": { "type": "string" }, "namespace": { "type": "string" }, "imageNamespace": { "type": "string" }, "imageName": { "type": "string" }, "imageId": { "type": "string", "format": "uuid" }, "vcpus": { "type": "integer", "nullable": true }, "memMiB": { "type": "integer", "nullable": true }, "diskSizeMiB": { "type": "integer", "nullable": true }, "status": { "type": "string", "enum": [ "creating", "created", "failed" ] }, "metadata": { "type": "object" }, "uploaded": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "snapshotName", "namespace", "imageName", "status" ] }, "SandboxSnapshotListResponse": { "type": "object", "properties": { "snapshots": { "type": "array", "items": { "$ref": "#/components/schemas/SandboxSnapshot" } }, "totalCount": { "type": "integer" }, "page": { "type": "integer" }, "perPage": { "type": "integer" } }, "required": [ "snapshots", "totalCount", "page", "perPage" ] }, "SandboxSnapshotResponse": { "type": "object", "properties": { "snapshot": { "$ref": "#/components/schemas/SandboxSnapshot" } }, "required": [ "snapshot" ] }, "SandboxSnapshotDeleteResponse": { "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ] }, "SandboxImageDeleteResponse": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "id": { "type": "string", "description": "Deleted image revision ID." }, "imageName": { "type": "string", "description": "Deleted image name." }, "uploaded": { "type": "boolean", "description": "Whether the deleted revision was uploaded. Delete-by-name can target a not-yet-uploaded revision that list endpoints hide." } }, "required": [ "deleted", "id", "imageName", "uploaded" ] }, "CreateImageBuildParams": { "type": "object", "properties": { "imageName": { "type": "string", "maxLength": 64, "pattern": "^[A-Za-z0-9_-]+$", "description": "Name for the resulting image. Letters, numbers, dashes, and underscores only." }, "inputSha256": { "type": "string", "minLength": 64, "maxLength": 64, "pattern": "^[A-Fa-f0-9]{64}$", "description": "SHA-256 of the image archive to upload." }, "inputSizeBytes": { "type": "integer", "minimum": 1 }, "inputFormat": { "type": "string", "enum": [ "rootfs_export_tar_gz", "dockerfile_context_tar_gz", "dockerfile_context_manifest_v1", "docker_image_manifest_v1" ], "default": "rootfs_export_tar_gz", "description": "Input archive or manifest format. GPU publication requires dockerfile_context_tar_gz or dockerfile_context_manifest_v1. Use the CLI to package the context and manage uploads." }, "sourcePlatform": { "type": "string", "enum": [ "linux/amd64" ], "default": "linux/amd64", "description": "Platform of the source image." }, "imageConfigUser": { "type": "string", "description": "Default user from the image config." }, "imageInit": { "type": "object", "description": "Startup defaults to attach to the image.", "properties": { "env": { "type": "object", "maxProperties": 128, "description": "Environment variables. Keys must match `^[A-Za-z_][A-Za-z0-9_]*$`.", "additionalProperties": { "type": "string", "maxLength": 8192 } }, "command": { "type": "string", "minLength": 1, "maxLength": 8192, "description": "Startup command." }, "args": { "type": "array", "maxItems": 256, "items": { "type": "string", "minLength": 1, "maxLength": 8192 }, "description": "Startup argument vector." } }, "additionalProperties": false }, "enableGPUBuilds": { "type": "boolean", "default": false, "description": "Also publish an image for GPU sandboxes. Requires GPU access and a Dockerfile context input format. GPUs are attached only when a sandbox runs, not during image builds. Wait for gpuImageReady before GPU creation." }, "dockerfilePath": { "type": "string", "default": "Dockerfile", "description": "Dockerfile path relative to the build context for remote Dockerfile builds." }, "contextManifest": { "type": "object", "description": "Build context manifest for dockerfile_context_manifest_v1. Generated by the CLI when packaging a remote build context." }, "dockerImageManifest": { "type": "object", "description": "Docker image manifest for docker_image_manifest_v1. Generated by the CLI for local Docker image exports. This format does not support GPU publication." } }, "required": [ "imageName", "inputSha256", "inputSizeBytes" ] }, "CompleteImageBuildParams": { "type": "object", "properties": { "inputSha256": { "type": "string", "minLength": 64, "maxLength": 64, "pattern": "^[A-Fa-f0-9]{64}$" }, "inputSizeBytes": { "type": "integer", "minimum": 1 }, "inputFormat": { "type": "string", "enum": [ "rootfs_export_tar_gz", "dockerfile_context_tar_gz", "dockerfile_context_manifest_v1", "docker_image_manifest_v1" ], "default": "rootfs_export_tar_gz" } }, "required": [ "inputSha256", "inputSizeBytes" ] }, "ImageBuild": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "imageName": { "type": "string" }, "imageId": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string", "enum": [ "awaiting_upload", "upload_verified", "dispatching", "building", "verifying", "completed", "failed", "canceled" ], "description": "Current image-build lifecycle state. For GPU builds, completed does not guarantee GPU publication; also check gpuImageReady." }, "inputSha256": { "type": "string", "nullable": true }, "inputSizeBytes": { "type": "integer", "nullable": true }, "errorCode": { "type": "string", "nullable": true }, "errorMessage": { "type": "string", "nullable": true }, "completedAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "enableGPUBuilds": { "type": "boolean", "description": "True when GPU publication was requested for this build." }, "imageReady": { "type": "boolean", "description": "Whether the image build is completed. This alone does not indicate GPU readiness." }, "uploaded": { "type": "boolean", "description": "Whether the CPU image is uploaded." }, "gpuUploaded": { "type": "boolean", "description": "Whether the GPU image is uploaded. Use gpuImageReady to determine whether it can be launched." }, "gpuImageReady": { "type": "boolean", "description": "Whether the GPU image is uploaded and valid for GPU sandbox creation. Wait for true before launching. Present for GPU-enabled builds." } }, "required": [ "id", "imageName", "status", "completedAt", "createdAt", "updatedAt" ] }, "ImageBuildResponse": { "type": "object", "properties": { "build": { "$ref": "#/components/schemas/ImageBuild" } }, "required": [ "build" ] }, "ImageBuildListResponse": { "type": "object", "properties": { "builds": { "type": "array", "items": { "$ref": "#/components/schemas/ImageBuild" } } }, "required": [ "builds" ] }, "CreateImageBuildResponse": { "type": "object", "properties": { "build": { "$ref": "#/components/schemas/ImageBuild" }, "upload": { "type": "object", "description": "Presigned upload target for the image archive.", "properties": { "url": { "type": "string" }, "method": { "type": "string", "enum": [ "PUT" ] }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "objectKey": { "type": "string" }, "expiresInSeconds": { "type": "integer" }, "maxUploadBytes": { "type": "integer" } }, "required": [ "url", "method", "headers", "objectKey", "expiresInSeconds", "maxUploadBytes" ] } }, "required": [ "build", "upload" ] }, "X402SessionStatus": { "type": "object", "additionalProperties": false, "required": [ "id", "status", "startTime", "endTime", "timeoutMinutes", "expiresAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "active", "closed", "error", "close-error" ] }, "startTime": { "type": "integer", "format": "int64", "nullable": true, "description": "Session start timestamp in Unix milliseconds, when available." }, "endTime": { "type": "integer", "format": "int64", "nullable": true, "description": "Session end timestamp in Unix milliseconds, when available." }, "timeoutMinutes": { "type": "integer", "minimum": 5, "maximum": 60, "description": "Prepaid duration chosen at creation." }, "expiresAt": { "type": "string", "format": "date-time", "description": "Original purchased expiry, unchanged by status checks or an early stop." } } }, "WebMCPAnnotations": { "type": "object", "properties": { "readOnly": { "type": "boolean" }, "untrustedContent": { "type": "boolean" }, "consequential": { "type": "boolean" }, "autosubmit": { "type": "boolean" }, "destructive": { "type": "boolean" }, "idempotent": { "type": "boolean" }, "openWorld": { "type": "boolean" } }, "required": [ "readOnly", "untrustedContent", "consequential", "autosubmit" ], "description": "Page-provided hints, not a security or authorization guarantee. Destructive, idempotent, and openWorld are optional polyfill hints." }, "WebMCPFrame": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "isMainFrame": { "type": "boolean" } }, "required": [ "id", "url", "isMainFrame" ] }, "WebMCPSource": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "native", "polyfill" ] }, "tabId": { "type": "string" }, "pageUrl": { "type": "string" }, "pageTitle": { "type": "string" }, "frame": { "$ref": "#/components/schemas/WebMCPFrame" } }, "required": [ "provider", "tabId", "pageUrl", "pageTitle", "frame" ] }, "WebMCPTool": { "type": "object", "properties": { "toolRef": { "type": "string", "description": "Opaque reference bound to the original document. Rediscover after navigation; do not construct this value." }, "name": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "inputSchema": { "type": "object", "additionalProperties": true, "description": "JSON Schema supplied by the page." }, "outputSchema": { "type": "object", "additionalProperties": true }, "annotations": { "$ref": "#/components/schemas/WebMCPAnnotations" }, "declarative": { "type": "boolean" }, "backendNodeId": { "type": "integer", "description": "Optional native CDP backend node ID. Scoped to the source target/document; absent when unavailable. Use toolRef for invocation." }, "source": { "$ref": "#/components/schemas/WebMCPSource" } }, "required": [ "toolRef", "name", "description", "annotations", "declarative", "source" ] }, "WebMCPToolsResponse": { "type": "object", "properties": { "tools": { "type": "array", "items": { "$ref": "#/components/schemas/WebMCPTool" } }, "nativeSupported": { "type": "boolean" }, "truncated": { "type": "boolean", "description": "True when discovery omitted metadata or tools to stay within limits." } }, "required": [ "tools", "nativeSupported", "truncated" ] }, "WebMCPInvokeParams": { "type": "object", "properties": { "toolRef": { "type": "string", "minLength": 1, "maxLength": 4096 }, "input": { "type": "object", "additionalProperties": true, "default": {}, "description": "Arguments matching the tool inputSchema. At most 1 MiB when JSON encoded. Keys are passed through unchanged." }, "timeoutSeconds": { "type": "integer", "minimum": 1, "maximum": 120, "default": 60, "description": "Tool execution budget in seconds. Expiration requests cancellation; it does not guarantee rollback." } }, "required": [ "toolRef" ], "additionalProperties": false }, "WebMCPStartParams": { "type": "object", "properties": { "toolRef": { "type": "string", "minLength": 1, "maxLength": 4096 }, "input": { "type": "object", "additionalProperties": true, "default": {}, "description": "Arguments matching the tool inputSchema. At most 1 MiB when JSON encoded. Keys are passed through unchanged." }, "timeoutSeconds": { "type": "integer", "minimum": 1, "maximum": 3600, "default": 300, "description": "Tool execution budget in seconds. Expiration requests cancellation; it does not guarantee rollback." } }, "required": [ "toolRef" ], "additionalProperties": false }, "WebMCPInvokeResult": { "type": "object", "properties": { "invocationId": { "type": "string", "description": "Handle for subsequent result reads or cancellation, when provided." }, "status": { "type": "string", "enum": [ "completed", "error", "canceled", "awaiting_submission" ] }, "output": { "description": "Any JSON value returned by the page, including null. Absent if unavailable or withheld for exceeding the output limit." }, "errorText": { "type": "string" }, "outputBytes": { "type": "integer", "minimum": 0, "description": "Byte length of the original JSON output." }, "outputTruncated": { "type": "boolean", "description": "True when output exceeds 1 MiB. Full output is withheld." }, "outputPreview": { "type": "string", "description": "At most 4096 UTF-8 bytes of the oversized output; may be incomplete JSON." }, "untrustedContent": { "type": "boolean" }, "durationMs": { "type": "integer", "minimum": 0 } }, "required": [ "status", "outputBytes", "untrustedContent", "durationMs" ] }, "WebMCPInvocationError": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "WebMCPInvocation": { "type": "object", "properties": { "invocationId": { "type": "string", "pattern": "^[a-f0-9]{24}$" }, "toolRef": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "awaiting_submission", "completed", "error", "canceled", "outcome_unknown" ] }, "cancellationRequested": { "type": "boolean", "description": "Whether cancellation was requested, regardless of the final outcome." }, "createdAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "description": "Nominal terminal-result expiry. Results may be evicted earlier.", "format": "date-time" }, "result": { "$ref": "#/components/schemas/WebMCPInvokeResult" }, "error": { "$ref": "#/components/schemas/WebMCPInvocationError" } }, "required": [ "invocationId", "toolRef", "status", "cancellationRequested", "createdAt" ], "description": "Ephemeral, session-local handle. Pending states have no result or error. A terminal handle may contain a result or an error. Lost on receiver restart, session rebind, or browser shutdown. At most 16 active and 64 retained; terminal results expire after 10 minutes and may be evicted sooner." }, "WebMCPErrorResponse": { "type": "object", "properties": { "message": { "type": "string" }, "error": { "type": "string" }, "code": { "type": "string" }, "invocationId": { "type": "string" } }, "description": "HTTP failure. Structured WebMCP errors include message and code; other session or validation errors may only include error or message. An outcome_unknown error may include an invocationId for later retrieval." }, "SecretType": { "type": "string", "enum": [ "secret", "totp", "op_token" ], "description": "What the value is. Fixed at creation. `secret`: any string, set as an environment variable and, once it has allowed origins, typed into browser pages. `totp`: an authenticator seed (base32, or an `otpauth://totp/` URI); environment variables get the code current when the process starts, and fills type the code current at fill time. `op_token`: a 1Password service account token, used only to read the `onePassword` fields of a sandbox create, process start or browser credential fill; it's never an environment variable, a vault entry or a value typed into a page. Treat types you don't recognize as opaque: more may be added." }, "SecretBrowserMetadata": { "type": "object", "properties": { "allowedOrigins": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "type": "string", "maxLength": 512 }, "description": "Origins a page or frame must be on before anything is typed, as `scheme://host[:port]` with no path, such as `https://github.com`. A leading `*.` matches any subdomain but not the domain itself, and must name at least two labels (`*.example.com`); you can't use a wildcard with an IP address. Origins must use https, except `http://localhost`, `http://127.0.0.1` and `http://[::1]`. Hyperbrowser lowercases origins, drops default ports and removes duplicates. An invalid entry returns 400 SECRET_METADATA_INVALID naming it." } }, "required": [ "allowedOrigins" ], "additionalProperties": false, "description": "Where the secret may be typed into browser pages. Allowed for `secret` and `totp`." }, "SecretMetadata": { "type": "object", "properties": { "browser": { "$ref": "#/components/schemas/SecretBrowserMetadata" } }, "additionalProperties": false, "description": "Settings that aren't secret, returned by the API and editable without uploading a new value. A `secret` or `totp` secret can't be filled into browser pages until `browser.allowedOrigins` is set. An `op_token` secret accepts only `{}` (otherwise 400 SECRET_METADATA_INVALID)." }, "Secret": { "type": "object", "description": "A secret. The API never returns its value.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$", "description": "1-128 letters, digits, `_` or `-`, starting with a letter or digit. Unique within your team." }, "description": { "type": "string", "maxLength": 1024 }, "type": { "$ref": "#/components/schemas/SecretType" }, "metadata": { "$ref": "#/components/schemas/SecretMetadata" }, "encryptionContext": { "type": "string", "description": "Copy this verbatim into the `ctx` header of every envelope you upload for this secret. Don't build it yourself: it includes the secret's type for types other than `secret`, and an envelope sealed with another context returns 400 SECRET_ENVELOPE_INVALID." }, "latestVersion": { "type": "integer", "nullable": true, "description": "The newest version number, or null until a value is uploaded." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "description", "type", "metadata", "encryptionContext", "latestVersion", "createdAt", "updatedAt" ] }, "SecretVersion": { "type": "object", "properties": { "version": { "type": "integer", "minimum": 1 }, "kid": { "type": "string", "description": "ID of the public key the envelope was encrypted to." }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "version", "kid", "createdAt" ] }, "SecretDetail": { "allOf": [ { "$ref": "#/components/schemas/Secret" }, { "type": "object", "properties": { "versions": { "type": "array", "items": { "$ref": "#/components/schemas/SecretVersion" }, "description": "Stored versions, newest first. Values are never returned." } }, "required": [ "versions" ] } ] }, "SecretListResponse": { "type": "object", "properties": { "secrets": { "type": "array", "items": { "$ref": "#/components/schemas/Secret" } }, "totalCount": { "type": "integer" }, "page": { "type": "integer" }, "perPage": { "type": "integer" } }, "required": [ "secrets", "totalCount", "page", "perPage" ] }, "CreateSecretParams": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$", "description": "1-128 letters, digits, `_` or `-`, starting with a letter or digit. Unique within your team." }, "description": { "type": "string", "maxLength": 1024, "default": "", "description": "Trimmed before it's stored." }, "type": { "allOf": [ { "$ref": "#/components/schemas/SecretType" } ], "default": "secret" }, "metadata": { "allOf": [ { "$ref": "#/components/schemas/SecretMetadata" } ], "description": "For `secret` and `totp`, you can set `browser.allowedOrigins` now or later with PATCH /api/secrets/{id}. `op_token` accepts only `{}`." } }, "required": [ "name" ], "additionalProperties": false }, "UpdateSecretParams": { "type": "object", "description": "Provide at least one of `description` and `metadata`.", "properties": { "description": { "type": "string", "maxLength": 1024, "description": "Replaces the description. Trimmed before it's stored." }, "metadata": { "type": "object", "properties": { "browser": { "type": "object", "nullable": true, "description": "Replaces the secret's browser settings, or removes them with `null`, after which the secret can't be filled until origins are set again.", "properties": { "allowedOrigins": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "type": "string", "maxLength": 512 }, "description": "Origins a page or frame must be on before anything is typed, as `scheme://host[:port]`. The same rules as `SecretBrowserMetadata.allowedOrigins` apply." } }, "required": [ "allowedOrigins" ], "additionalProperties": false } }, "additionalProperties": false, "description": "Merged into the stored metadata by top-level member: each member you send replaces the stored one, `null` removes it, and members you don't send are kept. So `{\"browser\": {\"allowedOrigins\": [...]}}` replaces the allowed origins, and `{\"browser\": null}` clears them. `op_token` secrets accept only `{}`." } }, "minProperties": 1, "additionalProperties": false }, "AddSecretVersionParams": { "type": "object", "properties": { "envelope": { "type": "string", "maxLength": 65536, "description": "The value, encrypted on your side as a compact JWE: five canonical, unpadded base64url segments. Wrap the content key with RSA-OAEP-256 using the key from GET /api/secrets/public-key, and encrypt the content with A256GCM. The protected header must hold exactly `alg` (`RSA-OAEP-256`), `enc` (`A256GCM`), `kid` (the public key's `kid`) and `ctx` (the secret's `encryptionContext`, copied verbatim). The plaintext is the value as UTF-8: any string for `secret`; a base32 seed (spaces, hyphens and line breaks are ignored, `=` padding only at the end) or an `otpauth://totp/` URI (with `secret` and optionally `algorithm` SHA1, SHA256 or SHA512, `digits` 6 or 8, and `period` 1-300) for `totp`; a 1Password service account token for `op_token`. The value can be at most 32 KiB, without NUL bytes, and the envelope at most 64 KiB. The API checks the envelope's structure but can't decrypt it, so it can't check the value: an invalid TOTP seed returns 422 SECRET_VALUE_INVALID when it's used. The Hyperbrowser SDKs and CLI validate the value and build the envelope for you, so we recommend using them rather than encrypting by hand." } }, "required": [ "envelope" ], "additionalProperties": false }, "SecretDeleteResponse": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "required": [ "deleted", "id", "name" ] }, "SecretVersionDeleteResponse": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] }, "version": { "type": "integer" } }, "required": [ "deleted", "version" ] }, "VaultStoredEntry": { "type": "object", "description": "A vault entry: a secret, by name.", "properties": { "name": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$", "description": "Name of a `secret` or `totp` secret." }, "version": { "oneOf": [ { "type": "string", "enum": [ "latest" ] }, { "type": "integer", "minimum": 1, "maximum": 2147483647 } ], "description": "A version to pin, or `latest`. Omit to follow the latest version." } }, "required": [ "name" ], "additionalProperties": false }, "VaultEntry": { "description": "An entry as returned: the secret's `name`, `secretId` and pinned `version` (`null` follows the latest).", "type": "object", "properties": { "name": { "type": "string" }, "secretId": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "nullable": true } }, "required": [ "name", "secretId", "version" ] }, "Vault": { "type": "object", "description": "A named set of environment variables. Holds no values.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$", "description": "1-128 letters, digits, `_` or `-`, starting with a letter or digit. Unique within your team." }, "description": { "type": "string", "maxLength": 1024 }, "entries": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/VaultEntry" }, "description": "Environment variable name to entry." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "description", "entries", "createdAt", "updatedAt" ] }, "VaultListResponse": { "type": "object", "properties": { "vaults": { "type": "array", "items": { "$ref": "#/components/schemas/Vault" } }, "totalCount": { "type": "integer" }, "page": { "type": "integer" }, "perPage": { "type": "integer" } }, "required": [ "vaults", "totalCount", "page", "perPage" ] }, "CreateVaultParams": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$", "description": "1-128 letters, digits, `_` or `-`, starting with a letter or digit. Unique within your team." }, "description": { "type": "string", "maxLength": 1024, "default": "", "description": "Trimmed before it's stored." }, "entries": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/VaultStoredEntry" }, "description": "Environment variable name to secret. Keys are environment variable names: letters, digits and `_`, not starting with a digit, at most 256 characters. A vault holds at most 32 entries (otherwise 409 VAULT_ENTRY_LIMIT_REACHED).", "example": { "USERNAME": { "name": "github-username" }, "PASSWORD": { "name": "github-password" } } } }, "required": [ "name" ], "additionalProperties": false }, "UpdateVaultParams": { "type": "object", "description": "Provide `description`, `entries`, or both.", "properties": { "description": { "type": "string", "maxLength": 1024, "description": "Replaces the description. Trimmed before it's stored." }, "entries": { "type": "object", "additionalProperties": { "oneOf": [ { "$ref": "#/components/schemas/VaultStoredEntry" }, { "type": "object", "nullable": true, "enum": [ null ], "description": "`null` removes the variable." } ] }, "description": "Entries to change: each one given replaces that variable, `null` removes it, and variables not given are kept. Keys are environment variable names: letters, digits and `_`, not starting with a digit, at most 256 characters. A vault holds at most 32 entries (otherwise 409 VAULT_ENTRY_LIMIT_REACHED)." } }, "minProperties": 1, "additionalProperties": false }, "VaultDeleteResponse": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "required": [ "deleted", "id", "name" ] }, "SecretsPublicKey": { "type": "object", "properties": { "kid": { "type": "string", "description": "Key ID: the RFC 7638 SHA-256 thumbprint of the key. Put it in the `kid` header of your envelopes." }, "alg": { "type": "string", "enum": [ "RSA-OAEP-256" ] }, "enc": { "type": "string", "enum": [ "A256GCM" ] }, "jwk": { "type": "object", "description": "The RSA public key (at least 3072 bits) as a JWK.", "properties": { "kty": { "type": "string", "enum": [ "RSA" ] }, "n": { "type": "string" }, "e": { "type": "string" }, "kid": { "type": "string" }, "alg": { "type": "string", "enum": [ "RSA-OAEP-256" ] }, "use": { "type": "string", "enum": [ "enc" ] } }, "required": [ "kty", "n", "e", "kid", "alg", "use" ] } }, "required": [ "kid", "alg", "enc", "jwk" ] }, "SecretErrorResponse": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code, such as SECRET_NOT_FOUND." }, "message": { "type": "string" }, "error": { "type": "string", "description": "Set instead of `code` by authentication and API key scope errors (API_KEY_SCOPE_DENIED)." }, "requiredScopes": { "type": "array", "items": { "type": "string" }, "description": "The scope the API key is missing, with API_KEY_SCOPE_DENIED." }, "retryable": { "type": "boolean", "description": "Whether repeating the same request can succeed. Set on delivery errors." }, "details": { "type": "object", "additionalProperties": true, "description": "Extra information for some codes, such as `origin` for CREDENTIAL_ORIGIN_NOT_ALLOWED or `pages` for CREDENTIAL_PAGE_AMBIGUOUS." } }, "description": "HTTP failure. Secret errors include `code` and `message`; request validation errors include only `message`; API key scope errors include `error`, `message` and `requiredScopes`." }, "SecretReference": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$", "description": "Name of a secret of type `secret` or `totp`. A `totp` variable holds the code current when the process starts." }, "version": { "oneOf": [ { "type": "string", "enum": [ "latest" ] }, { "type": "integer", "minimum": 1, "maximum": 2147483647 } ], "description": "A version number, or `latest`. Omit for the latest version." } }, "required": [ "name" ], "additionalProperties": false }, "SecretReferences": { "type": "object", "maxProperties": 32, "additionalProperties": { "$ref": "#/components/schemas/SecretReference" }, "description": "Environment variables to set from secrets, keyed by variable name (letters, digits and `_`, not starting with a digit), at most 32. `{}` is the same as none. An `op_token` secret returns 409 SECRET_TYPE_MISMATCH, an unknown secret 404 SECRET_NOT_FOUND, and a missing version 404 SECRET_VERSION_NOT_FOUND.", "example": { "OPENAI_API_KEY": { "name": "openai-key" } } }, "OnePasswordField": { "type": "object", "description": "A field of an item in the request's 1Password vault (`onePassword.vault`), read as `op:////[
/]`. The whole reference can be at most 512 bytes of UTF-8.", "properties": { "item": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The item. 1-256 characters: a 1Password name or ID without `/` or `?`, control or format characters, and not `.` or `..`." }, "section": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The section, if the field is in one. 1-256 characters: a 1Password name or ID without `/` or `?`, control or format characters, and not `.` or `..`." }, "field": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The field. 1-256 characters: a 1Password name or ID without `/` or `?`, control or format characters, and not `.` or `..`. It may end with one query, such as `?attribute=otp` (a TOTP field's current code) or `?ssh-format=openssh`: keys are lowercase letters and `-`, values are letters, digits, `_` and `-`, and pairs are joined with `&`." } }, "required": [ "item", "field" ], "additionalProperties": false }, "OnePasswordSource": { "type": "object", "description": "Environment variables read from fields of one 1Password vault when the process starts, signed in with a 1Password service account token stored as an `op_token` secret. Nothing is stored: the sandbox's host resolves the references, and values are never returned. A variable set here can't also be set by `vault`, `secrets` or `env` (400 SECRET_SOURCES_INVALID). Browser sessions fill 1Password fields through POST /api/session/{id}/credentials/fill instead.", "properties": { "token": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$", "description": "Name of the `op_token` secret holding the service account token. Its latest version is used. An unknown name returns 404 SECRET_NOT_FOUND, a secret of another type 409 SECRET_TYPE_MISMATCH, and a token without a value 404 SECRET_VERSION_NOT_FOUND." }, "vault": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The 1Password vault's name or ID. 1-256 characters: a 1Password name or ID without `/` or `?`, control or format characters, and not `.` or `..`." }, "fields": { "type": "object", "minProperties": 1, "maxProperties": 32, "additionalProperties": { "$ref": "#/components/schemas/OnePasswordField" }, "description": "Environment variable name (letters, digits and `_`, not starting with a digit) to the field it takes. 1 to 32 fields.", "example": { "SC_USER": { "item": "scrapingcourse login", "field": "username" }, "SC_OTP": { "item": "scrapingcourse login", "section": "Security", "field": "one-time password?attribute=otp" } } } }, "required": [ "token", "vault", "fields" ], "additionalProperties": false }, "StartSandboxSecretProcessParams": { "type": "object", "properties": { "command": { "type": "string", "minLength": 1, "maxLength": 8192, "description": "Shell command to run." }, "cwd": { "type": "string", "maxLength": 4096, "description": "Working directory." }, "env": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 32768 }, "description": "Plain environment variables. A variable that `vault`, `secrets` or `onePassword` sets can't also be in `env` (400 SECRET_SOURCES_INVALID)." }, "timeoutMs": { "type": "integer", "minimum": 0, "maximum": 86400000, "description": "Process timeout in milliseconds." }, "runAs": { "type": "string", "maxLength": 128, "description": "User to run the process as." }, "vault": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$", "description": "Name of a vault whose variables to set. Applied before `secrets`. Together with `secrets` and `onePassword` they set at most 32 variables. A vault without entries returns 400 SECRET_SOURCES_INVALID, and an unknown one 404 VAULT_NOT_FOUND." }, "secrets": { "allOf": [ { "$ref": "#/components/schemas/SecretReferences" } ], "description": "Secrets to set as environment variables for this process only, merged over the vault's variables, so `secrets` wins on a clash. They aren't added to the sandbox's default environment." }, "onePassword": { "allOf": [ { "$ref": "#/components/schemas/OnePasswordSource" } ], "description": "1Password fields to set as environment variables for this process only, read from 1Password when it starts." } }, "required": [ "command" ], "additionalProperties": false, "description": "Provide at least one of `secrets`, `vault` and `onePassword`." }, "SandboxSecretProcess": { "type": "object", "description": "The started process. Its environment is never returned.", "properties": { "id": { "type": "string", "description": "Process ID. Use it with the sandbox process APIs to read output or wait for the process." }, "status": { "type": "string", "enum": [ "queued", "running", "exited", "failed", "killed", "timed_out" ] }, "command": { "type": "string" }, "cwd": { "type": "string" }, "pid": { "type": "integer" }, "exit_code": { "type": "integer" }, "started_at": { "type": "integer", "format": "int64", "description": "Unix time in milliseconds." }, "completed_at": { "type": "integer", "format": "int64", "description": "Unix time in milliseconds." } }, "required": [ "id", "status", "command", "cwd", "started_at" ] }, "SecretSource": { "type": "object", "description": "Where a variable came from: the request's `vault`, its `secrets`, or its `onePassword`.", "properties": { "type": { "type": "string", "enum": [ "vault", "secrets", "onePassword" ] }, "name": { "type": "string", "description": "The vault's name, with `type: vault`." } }, "required": [ "type" ] }, "SandboxSecretBinding": { "type": "object", "description": "One environment variable a process received, never its value. A stored secret has `name`, `secretId` and `version`. A 1Password variable (`source.type` `onePassword`) has `reference` and `tokenSecret` instead, and never `overrides`.", "properties": { "env": { "type": "string", "description": "Environment variable name." }, "name": { "type": "string", "description": "Secret name." }, "secretId": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "description": "The version delivered, with `latest` resolved." }, "secretType": { "type": "string", "enum": [ "totp" ], "description": "Present for `totp` secrets, whose variable holds the code current at process start." }, "reference": { "type": "string", "description": "The `op://` reference the value was read from, for a 1Password variable." }, "tokenSecret": { "type": "string", "description": "Name of the `op_token` secret used to sign in to 1Password, for a 1Password variable." }, "source": { "$ref": "#/components/schemas/SecretSource" }, "overrides": { "type": "array", "items": { "$ref": "#/components/schemas/SecretSource" }, "description": "Earlier sources that set the same variable and were replaced, oldest first. Present only when there were any. Never `onePassword`: a 1Password variable can't be set by another source." } }, "required": [ "env", "source" ] }, "StartSandboxSecretProcessResponse": { "type": "object", "properties": { "process": { "$ref": "#/components/schemas/SandboxSecretProcess" }, "secrets": { "type": "array", "items": { "$ref": "#/components/schemas/SandboxSecretBinding" }, "description": "Each variable the process received, with its source. Never values." } }, "required": [ "process", "secrets" ] }, "CredentialFillField": { "type": "object", "properties": { "field": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$", "maxLength": 256, "description": "With `vault`, the entry to type, such as `PASSWORD`. Required with `vault` and not allowed with `credential` or `onePassword`." }, "selector": { "type": "string", "minLength": 1, "description": "CSS selector of the input to type into, at most 1024 UTF-8 bytes." }, "ref": { "allOf": [ { "$ref": "#/components/schemas/OnePasswordField" } ], "description": "With `onePassword`, the 1Password field to type, read as `op:////[
/]`. Required with `onePassword` and not allowed with `credential` or `vault`. A field such as `one-time password?attribute=otp` types a TOTP field's current code." } }, "required": [ "selector" ], "additionalProperties": false }, "CredentialFillOnePassword": { "type": "object", "description": "Fill fields read from 1Password with an `op_token` secret attached to the session as `{\"onePassword\": name}` in `credentials` (otherwise 403 CREDENTIAL_NOT_ATTACHED). Each field names its 1Password field in `ref`. The session's host reads the fields at fill time; nothing is stored. 1Password errors carry `details.tokenSecretId` and `details.tokenVersion`.", "properties": { "token": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$", "description": "Name of the `op_token` secret holding the service account token. Its latest version is used. An unknown name returns 404 SECRET_NOT_FOUND, a secret of another type 409 SECRET_TYPE_MISMATCH, and a token without a value 404 SECRET_VERSION_NOT_FOUND." }, "vault": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The 1Password vault's name or ID. 1-256 characters: a 1Password name or ID without `/` or `?`, control or format characters, and not `.` or `..`." }, "allowedOrigins": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "type": "string", "maxLength": 512 }, "description": "Origins the values may be typed on, with the same rules as a secret's `metadata.browser.allowedOrigins`: `scheme://host[:port]` with no path, https except for localhost, 127.0.0.1 and [::1], and `*.` only before a registrable domain. Required: nothing stored says where a 1Password value belongs, so the request does. The browser checks the target frame against them as it does a stored secret's, and tab choice uses them. An invalid origin returns 400 SECRET_METADATA_INVALID.", "example": [ "https://www.scrapingcourse.com" ] } }, "required": [ "token", "vault", "allowedOrigins" ], "additionalProperties": false }, "CredentialFillParams": { "type": "object", "properties": { "credential": { "type": "string", "minLength": 1, "maxLength": 255, "description": "A secret's name or ID (names are matched first). It must have been attached to the session when the session was created, directly or through a vault. Each field then has only a `selector`." }, "vault": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$", "description": "A vault's name. Each field's `field` names the entry whose secret is typed; the entry's secret must have been attached when the session was created." }, "onePassword": { "$ref": "#/components/schemas/CredentialFillOnePassword" }, "fields": { "type": "array", "minItems": 1, "maxItems": 16, "items": { "$ref": "#/components/schemas/CredentialFillField" }, "description": "The inputs to type into. Each selector may appear once." }, "pageId": { "type": "string", "minLength": 1, "description": "CDP target ID of the tab to fill, at most 128 UTF-8 bytes. Pass it, or `pageUrl`, when more than one tab could be the target. Not with `pageUrl`." }, "pageUrl": { "type": "string", "minLength": 1, "description": "Fill the tab whose URL starts with this prefix, at most 2048 UTF-8 bytes, instead of naming its `pageId`. Not with `pageId`." }, "frame": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "description": "Fill inside the one frame in the tab whose URL starts with this prefix, at most 2048 UTF-8 bytes." } }, "required": [ "url" ], "additionalProperties": false, "description": "Target an iframe, such as an embedded login form. Without it, the tab's main frame is filled." } }, "required": [ "fields" ], "additionalProperties": false, "description": "Provide exactly one of `credential`, `vault` and `onePassword` (otherwise 400 \"Pass one of credential, vault or onePassword\"). With `vault`, every field has `field`; with `onePassword`, every field has `ref`; with `credential`, fields have only a `selector`." }, "CredentialFillOutcome": { "type": "string", "enum": [ "filled", "not_found", "ambiguous", "not_editable", "not_accepted" ], "description": "`filled`: the input now holds exactly the value. `not_found`: no input matched the selector. `ambiguous`: more than one visible input matched. `not_editable`: the input is disabled, read-only, hidden, or not a text input. `not_accepted`: the page didn't keep the value (for example, because of `maxlength`). Treat outcomes you don't recognize as not filled: more may be added." }, "CredentialFillFieldResult": { "type": "object", "properties": { "selector": { "type": "string" }, "field": { "type": "string", "description": "The vault entry, for vault fills." }, "outcome": { "$ref": "#/components/schemas/CredentialFillOutcome" }, "secretId": { "type": "string", "format": "uuid", "description": "The secret typed into this input, or for a 1Password fill the `op_token` secret the field was read with." }, "version": { "type": "integer", "description": "The secret version typed, or for a 1Password fill the token version used." }, "expiresAt": { "type": "string", "format": "date-time", "description": "For a `totp` secret, when the typed code stops being current. Fill again if you submit after it. Not set for 1Password fills." }, "reference": { "type": "string", "description": "For a 1Password fill, the reference read: `op:////[
/]`.", "example": "op://Dev Vault for Testing/scrapingcourse login/username" } }, "required": [ "selector", "outcome", "secretId", "version" ] }, "CredentialFillResponse": { "type": "object", "description": "What was typed where. Never contains values.", "properties": { "version": { "type": "integer", "description": "The secret version filled, for `credential` fills only. Absent for `vault` and `onePassword` fills, whose fields each report their own." }, "pageId": { "type": "string", "description": "CDP target ID of the tab filled." }, "origin": { "type": "string", "description": "Origin of the frame filled." }, "fields": { "type": "array", "description": "One result per requested field, in request order.", "items": { "$ref": "#/components/schemas/CredentialFillFieldResult" } } }, "required": [ "pageId", "origin", "fields" ] }, "SessionCredential": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "CreateSessionResponse": { "allOf": [ { "$ref": "#/components/schemas/SessionDetail" }, { "type": "object", "properties": { "credentials": { "type": "array", "items": { "$ref": "#/components/schemas/SessionCredential" }, "description": "The secrets attached to the session, including those from vaults. Present only when you requested credentials." } } } ] }, "SandboxCapabilities": { "type": "object", "description": "Capabilities reported for GPU and macOS sandboxes. Inspect these fields before using runtime-specific features. Fields depend on the runtime.", "properties": { "commands": { "type": "boolean" }, "files": { "type": "boolean" }, "pty": { "type": "boolean" }, "gpu": { "type": "boolean" }, "snapshots": { "type": "boolean" }, "volumes": { "type": "boolean" }, "exposedPorts": { "type": "boolean" }, "networkFiltering": { "type": "boolean" }, "liveNetworkUpdates": { "type": "boolean" }, "internetAccess": { "type": "boolean" }, "desktop": { "type": "boolean" }, "persistentDisks": { "type": "boolean" }, "memorySnapshots": { "type": "boolean" }, "writableStorage": { "type": "string", "enum": [ "disk" ], "description": "GPU sandboxes use quota-limited ephemeral disk. Files do not persist after the sandbox stops." } } } }, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key" }, "X402SessionManagement": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The managementToken from the X402 session purchase response. Valid for 24 hours and scoped to that session; no API key or further payment is required." } } }, "paths": { "/api/session": { "post": { "summary": "Create new session", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Create a session", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.sessions.create({\n useStealth: true\n});" }, { "lang": "python", "label": "Create a session", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.sessions.create({\n \"use_stealth\": True\n})" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSessionParams" } } } }, "responses": { "200": { "description": "Session created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSessionResponse" } } } } } } }, "/api/session/{id}": { "get": { "summary": "Get session by ID", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Get a session", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.sessions.get('session-id');" }, { "lang": "python", "label": "Get a session", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.sessions.get('session-id')" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Session details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionDetail" } } } }, "404": { "description": "Session not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/session/{id}/stop": { "put": { "summary": "Stop a session", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Stop a session", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.sessions.stop('session-id');" }, { "lang": "python", "label": "Stop a session", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.sessions.stop('session-id')" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Session stopped successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicResponse" } } } }, "404": { "description": "Session not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/session/{id}/update": { "put": { "summary": "Update a running session", "description": "Update supported settings on an active browser session. Supported update types are profile, proxy, screen, and solveCaptchas.", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Start CAPTCHA solving", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.sessions.startCaptchaSolving('session-id', {\n solverType: 'visual'\n});\n\nawait client.sessions.stopCaptchaSolving('session-id');" }, { "lang": "python", "label": "Start CAPTCHA solving", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.sessions.start_captcha_solving(\n 'session-id',\n {\"solver_type\": \"visual\"}\n)\n\nclient.sessions.stop_captcha_solving('session-id')" }, { "lang": "bash", "label": "Start CAPTCHA solving", "source": "curl -X PUT \"https://api.hyperbrowser.ai/api/session/$SESSION_ID/update\" \\\n -H \"Content-Type: application/json\" \\\n -H \"x-api-key: $HYPERBROWSER_API_KEY\" \\\n -d '{\"type\":\"solveCaptchas\",\"params\":{\"enabled\":true,\"solverType\":\"visual\"}}'" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSessionRequest" }, "examples": { "profilePersistence": { "summary": "Update profile persistence", "value": { "type": "profile", "params": { "persistChanges": true, "persistNetworkCache": true } } }, "managedProxy": { "summary": "Enable managed proxy", "value": { "type": "proxy", "params": { "enabled": true, "location": { "country": "US", "state": "CA", "city": "San Francisco" } } } }, "screenSize": { "summary": "Resize screen", "value": { "type": "screen", "params": { "width": 1280, "height": 720 } } }, "startCaptchaSolving": { "summary": "Start CAPTCHA solving", "value": { "type": "solveCaptchas", "params": { "enabled": true, "solverType": "visual" } } }, "stopCaptchaSolving": { "summary": "Stop CAPTCHA solving", "value": { "type": "solveCaptchas", "params": { "enabled": false } } } } } } }, "responses": { "200": { "description": "Session updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSessionResponse" } } } }, "400": { "description": "Invalid update request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Session not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "CAPTCHA evaluation is already running", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/session/{id}/captcha/evaluate": { "post": { "summary": "Run manual CAPTCHA evaluation", "description": "Trigger a bounded CAPTCHA evaluation on an active browser session. Supported CAPTCHA targets are turnstile, cloudflare-challenge, aliexpress, recaptcha, and amazon.", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Run manual CAPTCHA evaluation", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nconst result = await client.sessions.evaluateCaptcha('session-id', {\n captchaType: 'recaptcha',\n iterations: 2\n});" }, { "lang": "python", "label": "Run manual CAPTCHA evaluation", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nresult = client.sessions.evaluate_captcha(\n 'session-id',\n {\n \"captcha_type\": \"recaptcha\",\n \"iterations\": 2\n }\n)" }, { "lang": "bash", "label": "Run manual CAPTCHA evaluation", "source": "curl -X POST \"https://api.hyperbrowser.ai/api/session/$SESSION_ID/captcha/evaluate\" \\\n -H \"Content-Type: application/json\" \\\n -H \"x-api-key: $HYPERBROWSER_API_KEY\" \\\n -d '{\"captchaType\":\"recaptcha\",\"iterations\":2}'" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaptchaEvaluationParams" }, "examples": { "recaptchaVisual": { "summary": "Evaluate visual reCAPTCHA", "value": { "captchaType": "recaptcha", "iterations": 2 } }, "turnstile": { "summary": "Evaluate Turnstile", "value": { "captcha": "turnstile", "maxIterations": 3 } } } } } }, "responses": { "200": { "description": "CAPTCHA evaluation completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaptchaEvaluationResponse" } } } }, "400": { "description": "Invalid evaluation request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Session not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "CAPTCHA evaluation is already running", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/sessions": { "get": { "summary": "Get list of sessions", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "List sessions", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.sessions.list({\n status: 'active'\n});" }, { "lang": "python", "label": "List sessions", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.sessions.list({\"status\": \"active\"})" } ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "number", "required": [ "false" ], "default": 1 } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "active", "closed", "error", "close-error" ], "required": [ "false" ] } } ], "responses": { "200": { "description": "List of sessions", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessions": { "type": "array", "items": { "$ref": "#/components/schemas/Session" } }, "totalCount": { "type": "number", "example": 100 }, "page": { "type": "number", "example": 1 }, "pageSize": { "type": "number", "example": 10 } } } } } }, "400": { "description": "Invalid query parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/session/{id}/recording-url": { "get": { "summary": "Get session recording URL", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Get recording URL", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.sessions.getRecordingURL('session-id');" }, { "lang": "python", "label": "Get recording URL", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.sessions.get_recording_url('session-id')" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Session recording URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSessionRecordingUrlResponse" } } } }, "404": { "description": "Session not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/session/{id}/video-recording-url": { "get": { "summary": "Get session video recording URL", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Get video recording URL", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.sessions.getVideoRecordingURL('session-id');" }, { "lang": "python", "label": "Get video recording URL", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.sessions.get_video_recording_url('session-id')" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Session video recording URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSessionVideoRecordingUrlResponse" } } } }, "404": { "description": "Session not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/session/{id}/downloads-url": { "get": { "summary": "Get session downloads URL", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Get downloads URL", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.sessions.getDownloadsURL('session-id');" }, { "lang": "python", "label": "Get downloads URL", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.sessions.get_downloads_url('session-id')" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Session downloads URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSessionDownloadsUrlResponse" } } } }, "404": { "description": "Session not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/profile": { "post": { "summary": "Creates a new profile", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Create a profile", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.profiles.create({\n name: 'My Profile'\n});" }, { "lang": "python", "label": "Create a profile", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.profiles.create({\"name\": \"My Profile\"})" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProfileParams" } } } }, "responses": { "200": { "description": "Profile created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProfileResponse" } } } } } } }, "/api/profile/{id}": { "get": { "summary": "Get profile by ID", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Get a profile", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.profiles.get('profile-id');" }, { "lang": "python", "label": "Get a profile", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.profiles.get('profile-id')" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Profile details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileResponse" } } } }, "404": { "description": "Profile not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "summary": "Delete profile by ID", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Delete a profile", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.profiles.delete('profile-id');" }, { "lang": "python", "label": "Delete a profile", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.profiles.delete('profile-id')" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Profile deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicResponse" } } } } } } }, "/api/profiles": { "get": { "summary": "Get list of profiles", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "List profiles", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.profiles.list({\n page: 1\n});" }, { "lang": "python", "label": "List profiles", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.profiles.list({\"page\": 1})" } ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "number", "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "number", "default": 10 } }, { "name": "name", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of profiles", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileListResponse" } } } }, "400": { "description": "Invalid query parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/scrape": { "post": { "summary": "Create new scrape job", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Start scrape job", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.scrape.start({\n url: 'https://example.com',\n scrapeOptions: {\n formats: ['markdown']\n }\n});" }, { "lang": "python", "label": "Start scrape job", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.scrape.start({\n \"url\": \"https://example.com\",\n \"scrape_options\": {\n \"formats\": [\"markdown\"]\n }\n})" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartScrapeJobParams" } } } }, "responses": { "200": { "description": "Scrape job created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartScrapeJobResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/scrape/{id}": { "get": { "summary": "Get scrape job status and result", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Get scrape job", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.scrape.get('job-id');" }, { "lang": "python", "label": "Get scrape job", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.scrape.get('job-id')" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Scrape job details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScrapeJobResponse" } } } }, "404": { "description": "Job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/scrape/{id}/status": { "get": { "summary": "Get scrape job status", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Get scrape job status", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.scrape.getStatus('job-id');" }, { "lang": "python", "label": "Get scrape job status", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.scrape.get_status('job-id')" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Scrape job status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobStatusResponse" } } } }, "404": { "description": "Job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/scrape/batch": { "post": { "summary": "Start a batch scrape job", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Start batch scrape job", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.scrape.batch.start({\n urls: ['https://example.com/page1', 'https://example.com/page2'],\n scrapeOptions: {\n formats: ['markdown']\n }\n});" }, { "lang": "python", "label": "Start batch scrape job", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.scrape.batch.start({\n \"urls\": [\"https://example.com/page1\", \"https://example.com/page2\"],\n \"scrape_options\": {\n \"formats\": [\"markdown\"]\n }\n})" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartBatchScrapeJobParams" } } } }, "responses": { "200": { "description": "Batch scrape job started successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartBatchScrapeJobResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Insufficient plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many concurrent batch scrape jobs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/scrape/batch/{id}": { "get": { "summary": "Get batch scrape job status and results", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Get batch scrape job", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.scrape.batch.get('job-id', {\n page: 1\n});" }, { "lang": "python", "label": "Get batch scrape job", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.scrape.batch.get('job-id', {\"page\": 1})" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Batch scrape job details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchScrapeJobResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Batch scrape job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/scrape/batch/{id}/status": { "get": { "summary": "Get batch scrape job status", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Get batch scrape job status", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.scrape.batch.getStatus('job-id');" }, { "lang": "python", "label": "Get batch scrape job status", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.scrape.batch.get_status('job-id')" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Batch scrape job status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobStatusResponse" } } } }, "404": { "description": "Batch scrape job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/crawl": { "post": { "summary": "Start a crawl job", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Start crawl job", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.crawl.start({\n url: 'https://example.com',\n scrapeOptions: {\n formats: ['markdown']\n }\n});" }, { "lang": "python", "label": "Start crawl job", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.crawl.start({\n \"url\": \"https://example.com\",\n \"scrape_options\": {\n \"formats\": [\"markdown\"]\n }\n})" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string" }, "maxPages": { "type": "integer", "minimum": 1 }, "followLinks": { "type": "boolean", "default": true }, "ignoreSitemap": { "type": "boolean", "default": false }, "excludePatterns": { "type": "array", "items": { "type": "string" } }, "includePatterns": { "type": "array", "items": { "type": "string" } }, "sessionOptions": { "$ref": "#/components/schemas/CreateSessionParams" }, "scrapeOptions": { "$ref": "#/components/schemas/ScrapeOptions" } } } } } }, "responses": { "200": { "description": "Crawl job started successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "jobId" ], "properties": { "jobId": { "type": "string" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/crawl/{id}": { "get": { "summary": "Get crawl job status and results", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Get crawl job", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.crawl.get('job-id', {\n page: 1\n});" }, { "lang": "python", "label": "Get crawl job", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.crawl.get('job-id', {\"page\": 1})" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "batchSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Crawl job details retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "type": "string", "format": "uuid" }, "status": { "$ref": "#/components/schemas/JobStatus" }, "error": { "type": "string", "nullable": true }, "totalCrawledPages": { "type": "integer", "minimum": 0 }, "totalPageBatches": { "type": "integer", "minimum": 0 }, "currentPageBatch": { "type": "integer", "minimum": 0 }, "batchSize": { "type": "integer", "minimum": 1 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CrawledPage" } } }, "required": [ "status", "jobId" ] } } } }, "404": { "description": "Crawl job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/crawl/{id}/status": { "get": { "summary": "Get crawl job status", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Get crawl job status", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.crawl.getStatus('job-id');" }, { "lang": "python", "label": "Get crawl job status", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.crawl.get_status('job-id')" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Crawl job status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobStatusResponse" } } } }, "404": { "description": "Crawl job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/extract": { "post": { "summary": "Start an extract job", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Start extract job", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.extract.start({\n urls: ['https://example.com'],\n prompt: 'Extract the main headline and author'\n});" }, { "lang": "python", "label": "Start extract job", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.extract.start({\n \"urls\": [\"https://example.com\"],\n \"prompt\": \"Extract the main headline and author\"\n})" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartExtractJobParams" } } } }, "responses": { "200": { "description": "Extract job started successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartExtractJobResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/extract/{id}": { "get": { "summary": "Get extract job status and results", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Get extract job", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.extract.get('job-id');" }, { "lang": "python", "label": "Get extract job", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.extract.get('job-id')" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Extract job details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractJobResponse" } } } }, "404": { "description": "Extract job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/extract/{id}/status": { "get": { "summary": "Get extract job status", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Get extract job status", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.extract.getStatus('job-id');" }, { "lang": "python", "label": "Get extract job status", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.extract.get_status('job-id')" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Extract job status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobStatusResponse" } } } }, "404": { "description": "Extract job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/task/hyper-agent": { "post": { "summary": "Start a HyperAgent task", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Start HyperAgent task", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.agents.hyperAgent.start({\n task: 'Find the price of the product',\n maxSteps: 20\n});" }, { "lang": "python", "label": "Start HyperAgent task", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.agents.hyper_agent.start({\n \"task\": \"Find the price of the product\",\n \"max_steps\": 20\n})" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartHyperAgentTaskParams" } } } }, "responses": { "200": { "description": "HyperAgent task started successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartHyperAgentTaskResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/task/hyper-agent/{id}": { "get": { "summary": "Get HyperAgent task status and results", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Get HyperAgent task", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.agents.hyperAgent.get('task-id');" }, { "lang": "python", "label": "Get HyperAgent task", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.agents.hyper_agent.get('task-id')" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HyperAgent task details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HyperAgentTaskResponse" } } } }, "404": { "description": "HyperAgent task not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/task/hyper-agent/{id}/stop": { "put": { "summary": "Stop a HyperAgent task", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Stop HyperAgent task", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.agents.hyperAgent.stop('task-id');" }, { "lang": "python", "label": "Stop HyperAgent task", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.agents.hyper_agent.stop('task-id')" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HyperAgent task stopped successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicResponse" } } } } } } }, "/api/task/hyper-agent/{id}/status": { "get": { "summary": "Get HyperAgent task status", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Get HyperAgent task status", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.agents.hyperAgent.getStatus('task-id');" }, { "lang": "python", "label": "Get HyperAgent task status", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.agents.hyper_agent.get_status('task-id')" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HyperAgent task status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobStatusResponse" } } } }, "404": { "description": "HyperAgent task not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/task/browser-use": { "post": { "summary": "Start a browser use task", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Start BrowserUse task", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.agents.browserUse.start({\n task: 'Find the price of the product',\n llm: 'gemini-2.0-flash',\n maxSteps: 20\n});" }, { "lang": "python", "label": "Start BrowserUse task", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.agents.browser_use.start({\n \"task\": \"Find the price of the product\",\n \"llm\": \"gemini-2.0-flash\",\n \"max_steps\": 20\n})" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartBrowserUseTaskParams" } } } }, "responses": { "200": { "description": "Browser use task started successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartBrowserUseTaskResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/task/browser-use/{id}": { "get": { "summary": "Get browser use task status and results", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Get BrowserUse task", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.agents.browserUse.get('task-id');" }, { "lang": "python", "label": "Get BrowserUse task", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.agents.browser_use.get('task-id')" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Browser use task details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserUseTaskResponse" } } } }, "404": { "description": "Browser use task not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/task/browser-use/{id}/stop": { "put": { "summary": "Stop a browser use task", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Stop BrowserUse task", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.agents.browserUse.stop('task-id');" }, { "lang": "python", "label": "Stop BrowserUse task", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.agents.browser_use.stop('task-id')" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Browser use task stopped successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicResponse" } } } } } } }, "/api/task/browser-use/{id}/status": { "get": { "summary": "Get browser use task status", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Get BrowserUse task status", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.agents.browserUse.getStatus('task-id');" }, { "lang": "python", "label": "Get BrowserUse task status", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.agents.browser_use.get_status('task-id')" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Browser use task status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobStatusResponse" } } } }, "404": { "description": "Browser use task not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/task/claude-computer-use": { "post": { "summary": "Start a claude computer use task", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Start Claude Computer Use task", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.agents.claudeComputerUse.start({\n task: 'Find the price of the product',\n llm: 'claude-sonnet-5-5',\n maxSteps: 20\n});" }, { "lang": "python", "label": "Start Claude Computer Use task", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.agents.claude_computer_use.start({\n \"task\": \"Find the price of the product\",\n \"llm\": \"claude-sonnet-5-5\",\n \"max_steps\": 20\n})" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartClaudeComputerUseTaskParams" } } } }, "responses": { "200": { "description": "Claude computer use task started successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartClaudeComputerUseTaskResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/task/claude-computer-use/{id}": { "get": { "summary": "Get claude computer use task status and results", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Get Claude Computer Use task", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.agents.claudeComputerUse.get('task-id');" }, { "lang": "python", "label": "Get Claude Computer Use task", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.agents.claude_computer_use.get('task-id')" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Claude computer use task details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaudeComputerUseTaskResponse" } } } }, "404": { "description": "Claude computer use task not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/task/claude-computer-use/{id}/stop": { "put": { "summary": "Stop a claude computer use task", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Stop Claude Computer Use task", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.agents.claudeComputerUse.stop('task-id');" }, { "lang": "python", "label": "Stop Claude Computer Use task", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.agents.claude_computer_use.stop('task-id')" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Claude computer use task stopped successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicResponse" } } } } } } }, "/api/task/claude-computer-use/{id}/status": { "get": { "summary": "Get claude computer use task status", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Get Claude Computer Use task status", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.agents.claudeComputerUse.getStatus('task-id');" }, { "lang": "python", "label": "Get Claude Computer Use task status", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.agents.claude_computer_use.get_status('task-id')" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Claude computer use task status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobStatusResponse" } } } }, "404": { "description": "Claude computer use task not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/task/gemini-computer-use": { "post": { "summary": "Start a gemini computer use task", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Start Gemini Computer Use task", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.agents.geminiComputerUse.start({\n task: 'Find the price of the product',\n maxSteps: 20\n});" }, { "lang": "python", "label": "Start Gemini Computer Use task", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.agents.gemini_computer_use.start({\n \"task\": \"Find the price of the product\",\n \"max_steps\": 20\n})" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartGeminiComputerUseTaskParams" } } } }, "responses": { "200": { "description": "Gemini computer use task started successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartGeminiComputerUseTaskResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/task/gemini-computer-use/{id}": { "get": { "summary": "Get gemini computer use task status and results", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Get Gemini Computer Use task", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.agents.geminiComputerUse.get('task-id');" }, { "lang": "python", "label": "Get Gemini Computer Use task", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.agents.gemini_computer_use.get('task-id')" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Gemini computer use task details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiComputerUseTaskResponse" } } } }, "404": { "description": "Gemini computer use task not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/task/gemini-computer-use/{id}/stop": { "put": { "summary": "Stop a gemini computer use task", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Stop Gemini Computer Use task", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.agents.geminiComputerUse.stop('task-id');" }, { "lang": "python", "label": "Stop Gemini Computer Use task", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.agents.gemini_computer_use.stop('task-id')" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Gemini computer use task stopped successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicResponse" } } } } } } }, "/api/task/gemini-computer-use/{id}/status": { "get": { "summary": "Get gemini computer use task status", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Get Gemini Computer Use task status", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.agents.geminiComputerUse.getStatus('task-id');" }, { "lang": "python", "label": "Get Gemini Computer Use task status", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.agents.gemini_computer_use.get_status('task-id')" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Gemini computer use task status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobStatusResponse" } } } }, "404": { "description": "Gemini computer use task not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/task/meta-computer-use": { "post": { "summary": "Start a meta computer use task", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Start Meta Computer Use task", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.agents.metaComputerUse.start({\n task: 'Find the price of the product',\n maxSteps: 20\n});" }, { "lang": "python", "label": "Start Meta Computer Use task", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.agents.meta_computer_use.start({\n \"task\": \"Find the price of the product\",\n \"max_steps\": 20\n})" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartMetaComputerUseTaskParams" } } } }, "responses": { "200": { "description": "Meta computer use task started successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartMetaComputerUseTaskResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/task/meta-computer-use/{id}": { "get": { "summary": "Get meta computer use task status and results", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Get Meta Computer Use task", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.agents.metaComputerUse.get('task-id');" }, { "lang": "python", "label": "Get Meta Computer Use task", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.agents.meta_computer_use.get('task-id')" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Meta computer use task details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetaComputerUseTaskResponse" } } } }, "404": { "description": "Meta computer use task not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/task/meta-computer-use/{id}/stop": { "put": { "summary": "Stop a meta computer use task", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Stop Meta Computer Use task", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.agents.metaComputerUse.stop('task-id');" }, { "lang": "python", "label": "Stop Meta Computer Use task", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.agents.meta_computer_use.stop('task-id')" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Meta computer use task stopped successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicResponse" } } } } } } }, "/api/task/meta-computer-use/{id}/status": { "get": { "summary": "Get meta computer use task status", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Get Meta Computer Use task status", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.agents.metaComputerUse.getStatus('task-id');" }, { "lang": "python", "label": "Get Meta Computer Use task status", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.agents.meta_computer_use.get_status('task-id')" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Meta computer use task status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobStatusResponse" } } } }, "404": { "description": "Meta computer use task not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/task/grok-computer-use": { "post": { "summary": "Start a grok computer use task", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Start Grok Computer Use task", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.agents.grokComputerUse.start({\n task: 'Find the price of the product',\n maxSteps: 20\n});" }, { "lang": "python", "label": "Start Grok Computer Use task", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.agents.grok_computer_use.start({\n \"task\": \"Find the price of the product\",\n \"max_steps\": 20\n})" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartGrokComputerUseTaskParams" } } } }, "responses": { "200": { "description": "Grok computer use task started successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartGrokComputerUseTaskResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/task/grok-computer-use/{id}": { "get": { "summary": "Get grok computer use task status and results", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Get Grok Computer Use task", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.agents.grokComputerUse.get('task-id');" }, { "lang": "python", "label": "Get Grok Computer Use task", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.agents.grok_computer_use.get('task-id')" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Grok computer use task details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrokComputerUseTaskResponse" } } } }, "404": { "description": "Grok computer use task not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/task/grok-computer-use/{id}/stop": { "put": { "summary": "Stop a grok computer use task", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Stop Grok Computer Use task", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.agents.grokComputerUse.stop('task-id');" }, { "lang": "python", "label": "Stop Grok Computer Use task", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.agents.grok_computer_use.stop('task-id')" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Grok computer use task stopped successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicResponse" } } } } } } }, "/api/task/grok-computer-use/{id}/status": { "get": { "summary": "Get grok computer use task status", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Get Grok Computer Use task status", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.agents.grokComputerUse.getStatus('task-id');" }, { "lang": "python", "label": "Get Grok Computer Use task status", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.agents.grok_computer_use.get_status('task-id')" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Grok computer use task status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobStatusResponse" } } } }, "404": { "description": "Grok computer use task not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/task/cua": { "post": { "summary": "Start a CUA task", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Start CUA task", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.agents.cua.start({\n task: 'Find the price of the product',\n maxSteps: 20\n});" }, { "lang": "python", "label": "Start CUA task", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.agents.cua.start({\n \"task\": \"Find the price of the product\",\n \"max_steps\": 20\n})" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartCuaTaskParams" } } } }, "responses": { "200": { "description": "CUA task started successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartCuaTaskResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/task/cua/{id}": { "get": { "summary": "Get CUA task status and results", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Get CUA task", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.agents.cua.get('task-id');" }, { "lang": "python", "label": "Get CUA task", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.agents.cua.get('task-id')" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "CUA task details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CuaTaskResponse" } } } }, "404": { "description": "CUA task not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/task/cua/{id}/stop": { "put": { "summary": "Stop a CUA task", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Stop CUA task", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.agents.cua.stop('task-id');" }, { "lang": "python", "label": "Stop CUA task", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.agents.cua.stop('task-id')" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "CUA task stopped successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicResponse" } } } } } } }, "/api/task/cua/{id}/status": { "get": { "summary": "Get CUA task status", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Get CUA task status", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.agents.cua.getStatus('task-id');" }, { "lang": "python", "label": "Get CUA task status", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.agents.cua.get_status('task-id')" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "CUA task status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobStatusResponse" } } } }, "404": { "description": "CUA task not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/extensions/add": { "post": { "summary": "Add a new extension", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Add an extension", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.extensions.create({\n filePath: '/path/to/extension.zip',\n name: 'My Extension'\n});" }, { "lang": "python", "label": "Add an extension", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.extensions.create({\n \"file_path\": \"/path/to/extension.zip\",\n \"name\": \"My Extension\"\n})" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CreateExtensionParams" } } } }, "responses": { "200": { "description": "Extension added successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtensionResponse" } } } } } } }, "/api/extensions/list": { "get": { "summary": "List all extensions", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "List extensions", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.extensions.list();" }, { "lang": "python", "label": "List extensions", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.extensions.list()" } ], "responses": { "200": { "description": "Extension added successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ExtensionResponse" } } } } } } } }, "/api/web/fetch": { "post": { "summary": "Fetch a web page", "description": "Fetches a web page and returns the content in various formats (HTML, Markdown, JSON, screenshot, etc.)", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Fetch a page", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nconst response = await client.web.fetch({\n url: 'https://example.com',\n outputs: {\n formats: ['markdown', 'screenshot']\n }\n});" }, { "lang": "python", "label": "Fetch a page", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nresponse = client.web.fetch({\n \"url\": \"https://example.com\",\n \"outputs\": {\n \"formats\": [\"markdown\", \"screenshot\"]\n }\n})" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FetchParams" } } } }, "responses": { "200": { "description": "Page fetched successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FetchResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/web/search": { "post": { "summary": "Search the web", "description": "Performs a web search and returns search results with titles, URLs, and descriptions", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Search the web", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nconst response = await client.web.search({\n query: 'hyperbrowser api',\n filters: {\n site: 'hyperbrowser.ai'\n }\n});" }, { "lang": "python", "label": "Search the web", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nresponse = client.web.search({\n \"query\": \"hyperbrowser api\",\n \"filters\": {\n \"site\": \"hyperbrowser.ai\"\n }\n})" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebSearchParams" } } } }, "responses": { "200": { "description": "Search completed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebSearchResponse" } } } }, "400": { "description": "Invalid search parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/web/crawl": { "post": { "summary": "Start a web crawl job", "description": "Starts an asynchronous crawl job that follows links from a starting URL and returns content from each page in the specified formats.", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Start a web crawl", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nconst response = await client.web.crawl.start({\n url: 'https://example.com',\n outputs: {\n formats: ['markdown']\n },\n crawlOptions: {\n maxPages: 10,\n followLinks: true\n }\n});" }, { "lang": "python", "label": "Start a web crawl", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nresponse = client.web.crawl.start({\n \"url\": \"https://example.com\",\n \"outputs\": {\n \"formats\": [\"markdown\"]\n },\n \"crawl_options\": {\n \"max_pages\": 10,\n \"follow_links\": True\n }\n})" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartWebCrawlJobParams" } } } }, "responses": { "200": { "description": "Crawl job started successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "jobId" ], "properties": { "jobId": { "type": "string" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/web/crawl/{id}": { "get": { "summary": "Get web crawl job results", "description": "Retrieves the status and results of a web crawl job. Results are paginated.", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Get web crawl job", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nconst response = await client.web.crawl.get('job-id', {\n page: 0,\n batchSize: 10\n});" }, { "lang": "python", "label": "Get web crawl job", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nresponse = client.web.crawl.get(\n 'job-id',\n {\"page\": 0, \"batch_size\": 10}\n)" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "batchSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Web crawl job details retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebCrawlJobResponse" } } } }, "404": { "description": "Crawl job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/web/crawl/{id}/status": { "get": { "summary": "Get web crawl job status", "description": "Retrieves just the status of a web crawl job without the full results.", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Get web crawl job status", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nconst response = await client.web.crawl.getStatus('job-id');" }, { "lang": "python", "label": "Get web crawl job status", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nresponse = client.web.crawl.get_status('job-id')" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Web crawl job status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobStatusResponse" } } } }, "404": { "description": "Crawl job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/x402/session": { "post": { "summary": "Create a session with X402 payment", "description": "Purchase one browser session at 0.10 USDC per hour, paid upfront for timeoutMinutes (5–60, default 30). No Hyperbrowser account or API key is required. A valid unpaid request returns 402 with payment requirements. Retry with a signed PAYMENT-SIGNATURE authorization. Payment is settled before connection credentials and a managementToken are returned. One authorization can create only one session. Invalid options are rejected before payment verification. See /integrations/x402/sessions for connection examples and lifetime behavior.", "security": [], "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "description": "Base64-encoded payment authorization generated by an X402 client from the advertised PAYMENT-REQUIRED requirements. Omit on the initial request to obtain a quote.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402SessionParams" }, "examples": { "defaults": { "summary": "Default 30-minute browser session", "value": {} }, "customized": { "summary": "Five-minute session with browser preferences", "value": { "screen": { "width": 1920, "height": 1080 }, "viewOnlyLiveView": true, "timeoutMinutes": 5 } } } } } }, "responses": { "200": { "description": "Browser created and payment settled. Use the returned connection details to control it without further X402 payments.", "headers": { "PAYMENT-RESPONSE": { "description": "Base64-encoded JSON with settlement information.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402SessionResponse" } } } }, "400": { "description": "Invalid or unsupported request parameters or malformed payment proof. Invalid options are rejected before payment verification or reservation of the proof.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Payment is missing or invalid, or settlement failed. Connection credentials are not returned. On settlement failure, the server attempts to stop the browser.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64-encoded JSON with payment requirements, including accepted networks, assets, amounts, and recipients. Returned with the initial payment challenge.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "This payment authorization is already reserved or used, including by a request still in progress. No additional session is launched.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Session capacity is currently unavailable. A request rejected before settlement can be retried with the same unexpired authorization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Session creation or payment processing failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The service or payment facilitator is temporarily unavailable. If settlement was attempted, the authorization stays reserved; an error response alone does not establish that payment was not settled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/x402/web/fetch": { "post": { "summary": "Fetch a web page with X402 payment", "description": "X402 payment endpoint. First request returns 402 with payment requirements. Retry with PAYMENT-SIGNATURE header containing cryptographic proof to get the actual data. See https://x402.gitbook.io/x402 for protocol details.", "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "description": "Base64-encoded JSON containing payment proof (x402Version, resource, accepted payment method, and cryptographic payload with signature and payer address)", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FetchParams" } } } }, "responses": { "200": { "description": "Page fetched successfully (after valid payment)", "headers": { "PAYMENT-RESPONSE": { "description": "Base64-encoded JSON with settlement information", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FetchResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Payment Required - returned on first request without PAYMENT-SIGNATURE header", "headers": { "PAYMENT-REQUIRED": { "description": "Base64-encoded JSON containing X402 payment requirements (x402Version, resource info, and array of accepted payment methods with network, asset, amount, payTo address, and timeout)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/x402/web/search": { "post": { "summary": "Search the web with X402 payment", "description": "X402 payment endpoint. First request returns 402 with payment requirements. Retry with PAYMENT-SIGNATURE header containing cryptographic proof to get search results. See https://x402.gitbook.io/x402 for protocol details.", "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "description": "Base64-encoded JSON containing payment proof (x402Version, resource, accepted payment method, and cryptographic payload with signature and payer address)", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebSearchParams" } } } }, "responses": { "200": { "description": "Search completed successfully (after valid payment)", "headers": { "PAYMENT-RESPONSE": { "description": "Base64-encoded JSON with settlement information", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebSearchResponse" } } } }, "400": { "description": "Invalid search parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Payment Required - returned on first request without PAYMENT-SIGNATURE header", "headers": { "PAYMENT-REQUIRED": { "description": "Base64-encoded JSON containing X402 payment requirements (x402Version, resource info, and array of accepted payment methods with network, asset, amount, payTo address, and timeout)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/sandbox": { "post": { "summary": "Create new sandbox", "tags": [ "Sandboxes" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSandboxParams" }, "examples": { "linux": { "summary": "CPU sandbox", "value": { "imageName": "node" } }, "macos": { "summary": "macOS sandbox (Beta)", "value": { "runtimeClass": "macos", "imageName": "macos-base", "region": "us", "vcpus": 8, "memMiB": 8192, "timeoutMinutes": 60 } }, "gpu": { "summary": "GPU sandbox (requires a GPU-ready team image)", "value": { "imageName": "gpu-python", "region": "us", "gpu": "L4", "gpuCount": 1, "vcpus": 2, "memMiB": 4096, "diskSizeMiB": 12288, "timeoutMinutes": 10 } } } } } }, "responses": { "200": { "description": "Sandbox created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSandboxResponse" } } } }, "202": { "description": "GPU provisioning accepted. Save the sandbox ID and poll GET /api/sandbox/{id}. The runtime and token are null until status is active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSandboxResponse" } } } }, "400": { "description": "Invalid creation parameters or unsupported resource combination." }, "403": { "description": "Access is not enabled for the requested sandbox type, or the request is not permitted." }, "404": { "description": "Requested image or start source was not found. GPU images must belong to your team." }, "409": { "description": "Image or start source is not ready. For GPU images, wait for gpuImageReady on the image build." }, "429": { "description": "Capacity, concurrency, or quota limit reached. Read the error message before retrying." } }, "description": "Create a CPU, GPU, or macOS sandbox. For GPU creation, set gpu and use a GPU-ready team image with region us. GPU access must be enabled for your team; contact info@hyperbrowser.ai. GPU requests return HTTP 202 with status provisioning and null runtime and token. Poll GET /api/sandbox/{id} until active. A stopped or failed sandbox has a terminal status; inspect closeReason. macOS is in beta; see its guide for desktop access and persistent disk reuse." } }, "/api/sandbox/{id}": { "get": { "summary": "Get sandbox by ID", "tags": [ "Sandboxes" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Sandbox ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sandbox details, including a runtime session token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxDetail" } } } } } } }, "/api/sandboxes": { "get": { "summary": "Get list of sandboxes", "tags": [ "Sandboxes" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number", "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Page size (max 100)", "schema": { "type": "integer", "default": 10 } }, { "name": "status", "in": "query", "required": false, "description": "Filter by stored sandbox status. The active filter also includes GPU sandboxes that are provisioning; inspect each returned status. Provisioning is not accepted as a filter value.", "schema": { "type": "string", "enum": [ "active", "stopping", "closed", "close-error", "error" ] } }, { "name": "start", "in": "query", "required": false, "description": "Filter by creation time (epoch milliseconds, inclusive lower bound)", "schema": { "type": "number" } }, { "name": "end", "in": "query", "required": false, "description": "Filter by creation time (epoch milliseconds, inclusive upper bound)", "schema": { "type": "number" } }, { "name": "search", "in": "query", "required": false, "description": "Search by sandbox ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of sandboxes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxListResponse" } } } } } } }, "/api/sandbox/{id}/stop": { "put": { "summary": "Stop a sandbox", "tags": [ "Sandboxes" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Sandbox ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sandbox stop requested", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicResponse" } } } } } } }, "/api/sandbox/{id}/expose": { "post": { "summary": "Expose a sandbox port", "tags": [ "Sandboxes" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Sandbox ID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxExposePortParams" } } } }, "responses": { "200": { "description": "Port exposed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxExposedPort" } } } } } } }, "/api/sandbox/{id}/unexpose": { "post": { "summary": "Remove an exposed sandbox port", "tags": [ "Sandboxes" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Sandbox ID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxUnexposePortParams" } } } }, "responses": { "200": { "description": "Port exposure removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxUnexposePortResponse" } } } } } } }, "/api/sandbox/{id}/snapshot": { "post": { "summary": "Create a sandbox memory snapshot", "tags": [ "Sandboxes" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Sandbox ID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxMemorySnapshotParams" } } } }, "responses": { "200": { "description": "Snapshot creation started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxMemorySnapshotResponse" } } } } } } }, "/api/sandbox/{id}/network": { "put": { "summary": "Update sandbox network policy", "tags": [ "Sandboxes" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Sandbox ID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxNetworkPolicyPatch" } } } }, "responses": { "200": { "description": "Updated effective network policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxNetworkUpdateResponse" } } } } } } }, "/api/volume": { "post": { "summary": "Create a volume", "tags": [ "Volumes" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVolumeParams" } } } }, "responses": { "200": { "description": "Volume created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Volume" } } } } } }, "get": { "summary": "Get list of volumes", "tags": [ "Volumes" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number", "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Page size (max 100)", "schema": { "type": "integer", "default": 20 } }, { "name": "search", "in": "query", "required": false, "description": "Search by volume name or ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of volumes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VolumeListResponse" } } } } } } }, "/api/volume/{id}": { "get": { "summary": "Get volume by ID", "tags": [ "Volumes" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Volume ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Volume details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Volume" } } } } } } }, "/api/volume/{key}": { "delete": { "summary": "Delete a volume", "tags": [ "Volumes" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "key", "in": "path", "required": true, "description": "Volume ID or name. Name lookup is case-insensitive. Multiple volumes that share a name return 409 and require an id. Active sandboxes that still mount the volume also return 409.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Volume deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VolumeDeleteResponse" } } } } } } }, "/api/images": { "get": { "summary": "Get list of sandbox images", "tags": [ "Images" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number", "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Page size (max 100)", "schema": { "type": "integer", "default": 20 } }, { "name": "source", "in": "query", "required": false, "description": "Filter by image source. Repeat to include multiple sources.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "public", "team" ] } } }, { "name": "search", "in": "query", "required": false, "description": "Search by image name", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of images", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxImageListResponse" } } } } } } }, "/api/images/{key}": { "delete": { "summary": "Delete sandbox image", "tags": [ "Images" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "key", "in": "path", "required": true, "description": "Team image name or ID. Names resolve to the newest launch-target revision (release_channel unset), including not-yet-uploaded rows. Public images cannot be deleted. In-flight builds, snapshots, and sandbox mappings that still reference the image return 409.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Image deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxImageDeleteResponse" } } } } } } }, "/api/snapshots": { "get": { "summary": "Get list of sandbox snapshots", "tags": [ "Snapshots" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "imageName", "in": "query", "required": false, "description": "Filter by source image name", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by snapshot status. Repeat to include multiple statuses.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "creating", "created", "failed" ] } } }, { "name": "search", "in": "query", "required": false, "description": "Search by snapshot name", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Page number", "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Page size (max 100)", "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "Paginated list of snapshots", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxSnapshotListResponse" } } } } } } }, "/api/snapshots/{key}": { "get": { "summary": "Get sandbox snapshot", "tags": [ "Snapshots" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "key", "in": "path", "required": true, "description": "Snapshot name or ID. Names resolve to the newest created revision.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Snapshot details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxSnapshotResponse" } } } } } }, "delete": { "summary": "Delete sandbox snapshot", "tags": [ "Snapshots" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "key", "in": "path", "required": true, "description": "Snapshot name or ID. Names resolve to the newest created revision.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Snapshot deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxSnapshotDeleteResponse" } } } } } } }, "/api/images/builds": { "post": { "summary": "Create an image build", "tags": [ "Images" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateImageBuildParams" } } } }, "responses": { "200": { "description": "Image build created with a presigned upload target", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateImageBuildResponse" } } } } } }, "get": { "summary": "Get list of image builds", "tags": [ "Images" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Filter by build status", "schema": { "type": "string", "enum": [ "awaiting_upload", "upload_verified", "dispatching", "building", "verifying", "completed", "failed", "canceled" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of builds to return", "schema": { "type": "integer", "default": 50 } } ], "responses": { "200": { "description": "List of image builds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageBuildListResponse" } } } } } } }, "/api/images/builds/{buildId}": { "get": { "summary": "Get image build by ID", "tags": [ "Images" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "buildId", "in": "path", "required": true, "description": "Image build ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Image build details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageBuildResponse" } } } } } } }, "/api/images/builds/{buildId}/complete": { "post": { "summary": "Complete an image build upload", "tags": [ "Images" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "buildId", "in": "path", "required": true, "description": "Image build ID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteImageBuildParams" } } } }, "responses": { "200": { "description": "Upload confirmed; build queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageBuildResponse" } } } } } } }, "/api/images/builds/{buildId}/cancel": { "post": { "summary": "Cancel an image build", "tags": [ "Images" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "buildId", "in": "path", "required": true, "description": "Image build ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Image build canceled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageBuildResponse" } } } } } } }, "/api/task/jev": { "post": { "summary": "Start a jev computer use task", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Start Jev Computer Use task", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.agents.jevComputerUse.start({\n task: 'Find the price of the product',\n maxSteps: 20\n});" }, { "lang": "python", "label": "Start Jev Computer Use task", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.agents.jev_computer_use.start({\n \"task\": \"Find the price of the product\",\n \"max_steps\": 20\n})" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartJevComputerUseTaskParams" } } } }, "responses": { "200": { "description": "Jev computer use task started successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartJevComputerUseTaskResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/task/jev/{id}": { "get": { "summary": "Get jev computer use task status and results", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Get Jev Computer Use task", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.agents.jevComputerUse.get('task-id');" }, { "lang": "python", "label": "Get Jev Computer Use task", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.agents.jev_computer_use.get('task-id')" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Jev computer use task details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JevComputerUseTaskResponse" } } } }, "404": { "description": "Jev computer use task not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/task/jev/{id}/stop": { "put": { "summary": "Stop a jev computer use task", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Stop Jev Computer Use task", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.agents.jevComputerUse.stop('task-id');" }, { "lang": "python", "label": "Stop Jev Computer Use task", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.agents.jev_computer_use.stop('task-id')" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Jev computer use task stopped successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicResponse" } } } } } } }, "/api/task/jev/{id}/status": { "get": { "summary": "Get jev computer use task status", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "javascript", "label": "Get Jev Computer Use task status", "source": "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nawait client.agents.jevComputerUse.getStatus('task-id');" }, { "lang": "python", "label": "Get Jev Computer Use task status", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nclient.agents.jev_computer_use.get_status('task-id')" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Jev computer use task status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobStatusResponse" } } } }, "404": { "description": "Jev computer use task not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/x402/session/{id}": { "get": { "summary": "Get an X402 session", "description": "Get the purchased session's status and original expiry without another payment. Authenticate with managementToken, not the browser token. Connection credentials are not reissued.", "security": [ { "X402SessionManagement": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Purchased session ID." } ], "responses": { "200": { "description": "Success. No payment is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402SessionStatus" } } } }, "400": { "description": "Invalid session ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid, expired, or incorrectly scoped management token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The token authorizes a different session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Session not found for the token's session and team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Session lookup or stop failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/x402/session/{id}/stop": { "put": { "summary": "Stop an X402 session", "description": "Stop the purchased browser without another payment. Authenticate with managementToken, not the browser token. An already closed or errored session also succeeds.", "security": [ { "X402SessionManagement": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Purchased session ID." } ], "responses": { "200": { "description": "Success. No payment is required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean", "enum": [ true ] } } } } } }, "400": { "description": "Invalid session ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid, expired, or incorrectly scoped management token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The token authorizes a different session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Session not found for the token's session and team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Session lookup or stop failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/session/{id}/webmcp/tools": { "get": { "summary": "List WebMCP tools", "operationId": "listWebmcpTools", "description": "Discover tools across open tabs and frames. Inspect source information as tool names can repeat. Tool references are bound to their original document. Requires an active session created with enableWebMcp: true and an API key with browser.sessions.update permission.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Session ID." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebMCPToolsResponse" } } } }, "400": { "description": "Invalid request or tool reference.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebMCPErrorResponse" } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebMCPErrorResponse" } } } }, "403": { "description": "Insufficient API key permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebMCPErrorResponse" } } } }, "404": { "description": "Session, tool, or invocation not found. Expired handles return invocation_not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebMCPErrorResponse" } } } }, "409": { "description": "Session is stopped, unavailable, or was not created with WebMCP enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebMCPErrorResponse" } } } }, "429": { "description": "Rate limit reached; too_many_invocations indicates 16 active invocations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebMCPErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebMCPErrorResponse" } } } }, "502": { "description": "WebMCP service unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebMCPErrorResponse" } } } }, "504": { "description": "Request timed out. For invocation requests, outcome_unknown means the tool may have acted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebMCPErrorResponse" } } } } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js", "source": "import { Hyperbrowser } from \"@hyperbrowser/sdk\";\n\nconst client = new Hyperbrowser();\n\nconst discovery = await client.sessions.webmcp.listTools(\"session-id\");" }, { "lang": "python", "label": "Python", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser()\n\ndiscovery = client.sessions.webmcp.list_tools(\"session-id\")" } ] } }, "/api/session/{id}/webmcp/invoke": { "post": { "summary": "Invoke a WebMCP tool", "operationId": "invokeWebmcpTool", "description": "Invoke once and wait for the result. A form may return awaiting_submission with an invocationId. Do not blindly retry if the response is lost; the tool may already have acted. Requires an active session created with enableWebMcp: true and an API key with browser.sessions.update permission.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Session ID." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebMCPInvokeResult" } } } }, "400": { "description": "Invalid request or tool reference.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebMCPErrorResponse" } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebMCPErrorResponse" } } } }, "403": { "description": "Insufficient API key permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebMCPErrorResponse" } } } }, "404": { "description": "Session, tool, or invocation not found. Expired handles return invocation_not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebMCPErrorResponse" } } } }, "409": { "description": "Session is stopped, unavailable, or was not created with WebMCP enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebMCPErrorResponse" } } } }, "429": { "description": "Rate limit reached; too_many_invocations indicates 16 active invocations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebMCPErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebMCPErrorResponse" } } } }, "502": { "description": "WebMCP service unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebMCPErrorResponse" } } } }, "504": { "description": "Request timed out. For invocation requests, outcome_unknown means the tool may have acted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebMCPErrorResponse" } } } }, "413": { "description": "Tool input exceeds 1 MiB (input_too_large).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebMCPErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebMCPInvokeParams" } } } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js", "source": "import { Hyperbrowser } from \"@hyperbrowser/sdk\";\n\nconst client = new Hyperbrowser();\n\nconst result = await client.sessions.webmcp.invoke(\"session-id\", {\n toolRef: \"tool-ref-from-discovery\",\n input: {}, // Match the selected tool inputSchema.\n timeoutSeconds: 60,\n});" }, { "lang": "python", "label": "Python", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser()\n\nresult = client.sessions.webmcp.invoke(\"session-id\", {\n \"tool_ref\": \"tool-ref-from-discovery\",\n \"input\": {}, # Match the selected tool input_schema.\n \"timeout_seconds\": 60,\n})" } ] } }, "/api/session/{id}/webmcp/invocations": { "post": { "summary": "Start a WebMCP invocation", "operationId": "startWebmcpInvocation", "description": "Start once and return a handle without waiting for completion. Acceptance does not guarantee success; inspect the handle later. A lost response may mean losing the handle to a tool that already acted. Do not blindly retry. Requires an active session created with enableWebMcp: true and an API key with browser.sessions.update permission.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Session ID." } ], "responses": { "202": { "description": "Invocation accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebMCPInvocation" } } } }, "400": { "description": "Invalid request or tool reference.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebMCPErrorResponse" } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebMCPErrorResponse" } } } }, "403": { "description": "Insufficient API key permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebMCPErrorResponse" } } } }, "404": { "description": "Session, tool, or invocation not found. Expired handles return invocation_not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebMCPErrorResponse" } } } }, "409": { "description": "Session is stopped, unavailable, or was not created with WebMCP enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebMCPErrorResponse" } } } }, "429": { "description": "Rate limit reached; too_many_invocations indicates 16 active invocations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebMCPErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebMCPErrorResponse" } } } }, "502": { "description": "WebMCP service unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebMCPErrorResponse" } } } }, "504": { "description": "Request timed out. For invocation requests, outcome_unknown means the tool may have acted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebMCPErrorResponse" } } } }, "413": { "description": "Tool input exceeds 1 MiB (input_too_large).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebMCPErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebMCPStartParams" } } } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js", "source": "import { Hyperbrowser } from \"@hyperbrowser/sdk\";\n\nconst client = new Hyperbrowser();\n\nconst result = await client.sessions.webmcp.start(\"session-id\", {\n toolRef: \"tool-ref-from-discovery\",\n input: {}, // Match the selected tool inputSchema.\n timeoutSeconds: 300,\n});" }, { "lang": "python", "label": "Python", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser()\n\nresult = client.sessions.webmcp.start(\"session-id\", {\n \"tool_ref\": \"tool-ref-from-discovery\",\n \"input\": {}, # Match the selected tool input_schema.\n \"timeout_seconds\": 300,\n})" } ] } }, "/api/session/{id}/webmcp/invocations/{invocationId}": { "get": { "summary": "Get a WebMCP invocation result", "operationId": "getWebmcpInvocationResult", "description": "Read or long-poll a handle without re-invoking the tool. A running or awaiting_submission response is still pending. A waitSeconds timeout does not cancel the invocation. Requires an active session created with enableWebMcp: true and an API key with browser.sessions.update permission.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Session ID." }, { "name": "invocationId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{24}$" } }, { "name": "waitSeconds", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 30, "default": 0 }, "description": "Maximum wait for completion, in seconds. Returns the current pending state if the wait expires." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebMCPInvocation" } } } }, "400": { "description": "Invalid request or tool reference.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebMCPErrorResponse" } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebMCPErrorResponse" } } } }, "403": { "description": "Insufficient API key permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebMCPErrorResponse" } } } }, "404": { "description": "Session, tool, or invocation not found. Expired handles return invocation_not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebMCPErrorResponse" } } } }, "409": { "description": "Session is stopped, unavailable, or was not created with WebMCP enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebMCPErrorResponse" } } } }, "429": { "description": "Rate limit reached; too_many_invocations indicates 16 active invocations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebMCPErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebMCPErrorResponse" } } } }, "502": { "description": "WebMCP service unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebMCPErrorResponse" } } } }, "504": { "description": "Request timed out. For invocation requests, outcome_unknown means the tool may have acted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebMCPErrorResponse" } } } } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js", "source": "import { Hyperbrowser } from \"@hyperbrowser/sdk\";\n\nconst client = new Hyperbrowser();\n\nconst invocation = await client.sessions.webmcp.getResult(\n \"session-id\", \"invocation-id\", { waitSeconds: 30 }\n);" }, { "lang": "python", "label": "Python", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser()\n\ninvocation = client.sessions.webmcp.get_result(\n \"session-id\", \"invocation-id\", {\"wait_seconds\": 30}\n)" } ] } }, "/api/session/{id}/webmcp/invocations/{invocationId}/cancel": { "post": { "summary": "Cancel a WebMCP invocation", "operationId": "cancelWebmcpInvocation", "description": "Request best-effort cancellation and return the current handle. Completion can win the race. This does not roll back page side effects. Continue result reads if still pending. Requires an active session created with enableWebMcp: true and an API key with browser.sessions.update permission.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Session ID." }, { "name": "invocationId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{24}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebMCPInvocation" } } } }, "400": { "description": "Invalid request or tool reference.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebMCPErrorResponse" } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebMCPErrorResponse" } } } }, "403": { "description": "Insufficient API key permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebMCPErrorResponse" } } } }, "404": { "description": "Session, tool, or invocation not found. Expired handles return invocation_not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebMCPErrorResponse" } } } }, "409": { "description": "Session is stopped, unavailable, or was not created with WebMCP enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebMCPErrorResponse" } } } }, "429": { "description": "Rate limit reached; too_many_invocations indicates 16 active invocations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebMCPErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebMCPErrorResponse" } } } }, "502": { "description": "WebMCP service unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebMCPErrorResponse" } } } }, "504": { "description": "Request timed out. For invocation requests, outcome_unknown means the tool may have acted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebMCPErrorResponse" } } } } }, "x-codeSamples": [ { "lang": "javascript", "label": "Node.js", "source": "import { Hyperbrowser } from \"@hyperbrowser/sdk\";\n\nconst client = new Hyperbrowser();\n\nconst invocation = await client.sessions.webmcp.cancel(\n \"session-id\", \"invocation-id\"\n);" }, { "lang": "python", "label": "Python", "source": "from hyperbrowser import Hyperbrowser\n\nclient = Hyperbrowser()\n\ninvocation = client.sessions.webmcp.cancel(\"session-id\", \"invocation-id\")" } ] } }, "/api/secrets/public-key": { "get": { "summary": "Get the secrets public key", "operationId": "getSecretsPublicKey", "description": "Returns the RSA public key that you encrypt secret values to before uploading them with POST /api/secrets/{id}/versions. Doesn't require authentication. Don't cache the key: after a key rotation, uploads encrypted to the old key return 409 SECRET_KEY_OUTDATED, and you fetch the key again.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretsPublicKey" } } } }, "503": { "description": "SECRETS_NOT_CONFIGURED: secrets aren't available on this deployment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } } } } }, "/api/secrets": { "get": { "summary": "List secrets", "operationId": "listSecrets", "description": "Lists your team's secrets, sorted by name. Values are never returned. Secrets are enabled for teams on request; please contact support to enable them (otherwise 403 SECRETS_FEATURE_DISABLED). Restricted API keys need the secrets.read scope. When you're signed in rather than using an API key, you must be a team owner or admin (otherwise 403 SECRETS_ADMIN_REQUIRED).", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Secrets per page." }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 256 }, "description": "Only secrets whose name contains this text, ignoring case." }, { "name": "type", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/SecretType" }, "description": "Only secrets of this type." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretListResponse" } } } }, "400": { "description": "Invalid query parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "403": { "description": "API_KEY_SCOPE_DENIED (the API key lacks a required scope), SECRETS_FEATURE_DISABLED, or SECRETS_ADMIN_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } } } }, "post": { "summary": "Create a secret", "operationId": "createSecret", "description": "Creates a secret without a value. Then upload its value with POST /api/secrets/{id}/versions, encrypted with the `encryptionContext` this returns. A team can have at most 100 secrets. Secrets are enabled for teams on request; please contact support to enable them (otherwise 403 SECRETS_FEATURE_DISABLED). Restricted API keys need the secrets.manage scope. When you're signed in rather than using an API key, you must be a team owner or admin (otherwise 403 SECRETS_ADMIN_REQUIRED).", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSecretParams" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Secret" } } } }, "400": { "description": "Invalid request body, or SECRET_METADATA_INVALID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "403": { "description": "API_KEY_SCOPE_DENIED (the API key lacks a required scope), SECRETS_FEATURE_DISABLED, or SECRETS_ADMIN_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "409": { "description": "SECRET_NAME_TAKEN: a secret with this name exists. SECRET_LIMIT_REACHED: your team has 100 secrets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } } } } }, "/api/secrets/{id}": { "get": { "summary": "Get a secret", "operationId": "getSecret", "description": "Returns a secret and its stored versions. Values are never returned. Secrets are enabled for teams on request; please contact support to enable them (otherwise 403 SECRETS_FEATURE_DISABLED). Restricted API keys need the secrets.read scope. When you're signed in rather than using an API key, you must be a team owner or admin (otherwise 403 SECRETS_ADMIN_REQUIRED).", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Secret ID." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretDetail" } } } }, "400": { "description": "Invalid secret ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "403": { "description": "API_KEY_SCOPE_DENIED (the API key lacks a required scope), SECRETS_FEATURE_DISABLED, or SECRETS_ADMIN_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "404": { "description": "SECRET_NOT_FOUND: no secret with this ID in your team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } } } }, "patch": { "summary": "Update a secret", "operationId": "updateSecret", "description": "Updates a secret's description or metadata, such as its allowed origins, without uploading a new value. Metadata is merged by top-level member: each member you send replaces the stored one, and `null` removes it. Secrets are enabled for teams on request; please contact support to enable them (otherwise 403 SECRETS_FEATURE_DISABLED). Restricted API keys need the secrets.manage scope. When you're signed in rather than using an API key, you must be a team owner or admin (otherwise 403 SECRETS_ADMIN_REQUIRED).", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Secret ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSecretParams" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Secret" } } } }, "400": { "description": "Invalid request body, neither description nor metadata given, or SECRET_METADATA_INVALID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "403": { "description": "API_KEY_SCOPE_DENIED (the API key lacks a required scope), SECRETS_FEATURE_DISABLED, or SECRETS_ADMIN_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "404": { "description": "SECRET_NOT_FOUND: no secret with this ID in your team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } } } }, "delete": { "summary": "Delete a secret", "operationId": "deleteSecret", "description": "Permanently deletes a secret and all its versions. A secret that a vault uses as an entry can't be deleted. Secrets are enabled for teams on request; please contact support to enable them (otherwise 403 SECRETS_FEATURE_DISABLED). Restricted API keys need the secrets.manage scope. When you're signed in rather than using an API key, you must be a team owner or admin (otherwise 403 SECRETS_ADMIN_REQUIRED).", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Secret ID." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretDeleteResponse" } } } }, "400": { "description": "Invalid secret ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "403": { "description": "API_KEY_SCOPE_DENIED (the API key lacks a required scope), SECRETS_FEATURE_DISABLED, or SECRETS_ADMIN_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "404": { "description": "SECRET_NOT_FOUND: no secret with this ID in your team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "409": { "description": "SECRET_IN_USE: a vault uses this secret; change or delete the vault first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } } } } }, "/api/secrets/{id}/versions": { "post": { "summary": "Add a secret version", "operationId": "addSecretVersion", "description": "Uploads a new value as the secret's next version. Encrypt the value on your side as a compact JWE (RSA-OAEP-256 and A256GCM) to the key from GET /api/secrets/public-key, with the protected header `{alg, enc, kid, ctx}`, where `ctx` is the secret's `encryptionContext`. The SDKs and CLI do this for you. A secret keeps at most 10 versions. Secrets are enabled for teams on request; please contact support to enable them (otherwise 403 SECRETS_FEATURE_DISABLED). Restricted API keys need the secrets.manage scope. When you're signed in rather than using an API key, you must be a team owner or admin (otherwise 403 SECRETS_ADMIN_REQUIRED).", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Secret ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddSecretVersionParams" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretVersion" } } } }, "400": { "description": "Invalid request body, or SECRET_ENVELOPE_INVALID: the envelope isn't a valid compact JWE for this secret (for example, a different `ctx`) or the value exceeds 32 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "403": { "description": "API_KEY_SCOPE_DENIED (the API key lacks a required scope), SECRETS_FEATURE_DISABLED, or SECRETS_ADMIN_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "404": { "description": "SECRET_NOT_FOUND: no secret with this ID in your team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "409": { "description": "SECRET_KEY_OUTDATED: the envelope was encrypted to an old public key; fetch the current key and encrypt again. SECRET_LIMIT_REACHED: the secret has 10 versions; delete an old one first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "503": { "description": "SECRETS_NOT_CONFIGURED: secrets aren't available on this deployment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } } } } }, "/api/secrets/{id}/versions/{version}": { "delete": { "summary": "Delete a secret version", "operationId": "deleteSecretVersion", "description": "Permanently deletes an older version of a secret. You can't delete the latest version: add a new version or delete the secret instead. Secrets are enabled for teams on request; please contact support to enable them (otherwise 403 SECRETS_FEATURE_DISABLED). Restricted API keys need the secrets.manage scope. When you're signed in rather than using an API key, you must be a team owner or admin (otherwise 403 SECRETS_ADMIN_REQUIRED).", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Secret ID." }, { "name": "version", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "description": "Version number." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretVersionDeleteResponse" } } } }, "400": { "description": "Invalid secret ID or version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "403": { "description": "API_KEY_SCOPE_DENIED (the API key lacks a required scope), SECRETS_FEATURE_DISABLED, or SECRETS_ADMIN_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "404": { "description": "SECRET_NOT_FOUND or SECRET_VERSION_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "409": { "description": "SECRET_VERSION_IS_LATEST: the latest version can't be deleted. SECRET_VERSION_IN_USE: a vault pins this version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } } } } }, "/api/vaults": { "get": { "summary": "List vaults", "operationId": "listVaults", "description": "Lists your team's vaults, sorted by name, with their entries. Secrets are enabled for teams on request; please contact support to enable them (otherwise 403 SECRETS_FEATURE_DISABLED). Restricted API keys need the secrets.read scope. When you're signed in rather than using an API key, you must be a team owner or admin (otherwise 403 SECRETS_ADMIN_REQUIRED).", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Vaults per page." }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 256 }, "description": "Only vaults whose name contains this text, ignoring case." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaultListResponse" } } } }, "400": { "description": "Invalid query parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "403": { "description": "API_KEY_SCOPE_DENIED (the API key lacks a required scope), SECRETS_FEATURE_DISABLED, or SECRETS_ADMIN_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } } } }, "post": { "summary": "Create a vault", "operationId": "createVault", "description": "Creates a vault: a set of environment variables that point at your secrets. Pass the vault by name as `vault` to POST /api/sandbox and POST /api/sandbox/{id}/processes, or as `{\"vault\": name}` in a browser session's `credentials`. A team can have at most 100 vaults. Secrets are enabled for teams on request; please contact support to enable them (otherwise 403 SECRETS_FEATURE_DISABLED). Restricted API keys need the secrets.manage scope. When you're signed in rather than using an API key, you must be a team owner or admin (otherwise 403 SECRETS_ADMIN_REQUIRED).", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVaultParams" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Vault" } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "403": { "description": "API_KEY_SCOPE_DENIED (the API key lacks a required scope), SECRETS_FEATURE_DISABLED, or SECRETS_ADMIN_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "404": { "description": "SECRET_NOT_FOUND or SECRET_VERSION_NOT_FOUND: an entry or the token names a missing secret or version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "409": { "description": "VAULT_NAME_TAKEN, VAULT_LIMIT_REACHED, VAULT_ENTRY_LIMIT_REACHED, or SECRET_TYPE_MISMATCH (an `op_token` secret as an entry).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } } } } }, "/api/vaults/{id}": { "get": { "summary": "Get a vault", "operationId": "getVault", "description": "Returns a vault and its entries. Secrets are enabled for teams on request; please contact support to enable them (otherwise 403 SECRETS_FEATURE_DISABLED). Restricted API keys need the secrets.read scope. When you're signed in rather than using an API key, you must be a team owner or admin (otherwise 403 SECRETS_ADMIN_REQUIRED).", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Vault ID." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Vault" } } } }, "400": { "description": "Invalid vault ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "403": { "description": "API_KEY_SCOPE_DENIED (the API key lacks a required scope), SECRETS_FEATURE_DISABLED, or SECRETS_ADMIN_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "404": { "description": "VAULT_NOT_FOUND: no vault with this ID in your team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } } } }, "patch": { "summary": "Update a vault", "operationId": "updateVault", "description": "Changes a vault's description or entries. Entries you pass replace those variables and `null` removes one; others are kept. Processes that already started keep the values they received. Secrets are enabled for teams on request; please contact support to enable them (otherwise 403 SECRETS_FEATURE_DISABLED). Restricted API keys need the secrets.manage scope. When you're signed in rather than using an API key, you must be a team owner or admin (otherwise 403 SECRETS_ADMIN_REQUIRED).", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Vault ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateVaultParams" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Vault" } } } }, "400": { "description": "Invalid request body, or nothing to change.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "403": { "description": "API_KEY_SCOPE_DENIED (the API key lacks a required scope), SECRETS_FEATURE_DISABLED, or SECRETS_ADMIN_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "404": { "description": "VAULT_NOT_FOUND, SECRET_NOT_FOUND, or SECRET_VERSION_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "409": { "description": "VAULT_ENTRY_LIMIT_REACHED or SECRET_TYPE_MISMATCH.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } } } }, "delete": { "summary": "Delete a vault", "operationId": "deleteVault", "description": "Permanently deletes a vault. The secrets it points at are kept. Secrets are enabled for teams on request; please contact support to enable them (otherwise 403 SECRETS_FEATURE_DISABLED). Restricted API keys need the secrets.manage scope. When you're signed in rather than using an API key, you must be a team owner or admin (otherwise 403 SECRETS_ADMIN_REQUIRED).", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Vault ID." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaultDeleteResponse" } } } }, "400": { "description": "Invalid vault ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "403": { "description": "API_KEY_SCOPE_DENIED (the API key lacks a required scope), SECRETS_FEATURE_DISABLED, or SECRETS_ADMIN_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "404": { "description": "VAULT_NOT_FOUND: no vault with this ID in your team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } } } } }, "/api/session/{id}/credentials/fill": { "post": { "summary": "Fill a credential", "operationId": "fillSessionCredential", "description": "Types a secret, a vault's entries, or fields read from 1Password into inputs on a page in the session. The values are decrypted on the session's host; neither the request nor the response contains them. Fill only types: it never submits, so click the submit button or press Enter afterwards. Nothing is typed unless the target frame is on an allowed origin of every secret being filled, or for `onePassword` on one of the request's `allowedOrigins`. A `totp` secret types the code current at fill time. A fill is safe to retry. Without `pageId`, Hyperbrowser considers the tabs whose URL starts with `pageUrl` (if given). If one is left, it's the target. If several are left, it prefers the tabs on an origin every secret (or `onePassword.allowedOrigins`) allows, unless `frame` is given, then the visible one among them; if more than one still qualifies, it returns 409 CREDENTIAL_PAGE_AMBIGUOUS listing the tabs. The chosen tab's origin is then checked, and a tab outside the allowed origins gets 403 CREDENTIAL_ORIGIN_NOT_ALLOWED with nothing typed. Requires an active Firecracker browser session created with these secrets, or the `onePassword` token, in `credentials`. Secrets are enabled for teams on request; please contact support to enable them (otherwise 403 SECRETS_FEATURE_DISABLED). Restricted API keys need both the browser.sessions.update and secrets.use scopes. A fill can take up to about 18 seconds, so set your client timeout to at least 30 seconds. Fills and refusals are recorded in the session's event logs as `credential_filled` and `credential_fill_refused`, with `credential`, `vault`, or for 1Password the token's name as `onePasswordToken`, and never values.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Session ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialFillParams" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialFillResponse" } } } }, "400": { "description": "Invalid request body, SECRET_METADATA_INVALID (an invalid `onePassword.allowedOrigins` entry), or CREDENTIALS_UNSUPPORTED_RUNTIME (the session isn't a Firecracker browser session).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "403": { "description": "API_KEY_SCOPE_DENIED, SECRETS_FEATURE_DISABLED, CREDENTIAL_NOT_ATTACHED (the secret or `onePassword` token wasn't attached when the session was created, or a vault entry now points at another secret), or CREDENTIAL_ORIGIN_NOT_ALLOWED (the frame isn't on an allowed origin; `details.origin` names it, and nothing was typed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "404": { "description": "Session not found, SECRET_NOT_FOUND, VAULT_NOT_FOUND, VAULT_ENTRY_NOT_FOUND, SECRET_VERSION_NOT_FOUND, CREDENTIAL_PAGE_NOT_FOUND (no tab with this `pageId` or `pageUrl`, or no open tab), or CREDENTIAL_FRAME_NOT_FOUND (no frame URL starts with `frame.url`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "409": { "description": "SECRET_TYPE_MISMATCH (the secret can't be filled, such as an `op_token` named as `credential`, or `onePassword.token` isn't an `op_token`), CREDENTIAL_NOT_READY (no allowed origins or no value uploaded), SESSION_NOT_ACTIVE, CREDENTIAL_PAGE_AMBIGUOUS (pass `pageId` or `pageUrl`; `details.pages` lists each tab's `pageId`, `url` and `title`), CREDENTIAL_FRAME_AMBIGUOUS (more than one frame URL starts with `frame.url`), or the session's runtime isn't ready.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "422": { "description": "SECRET_VALUE_INVALID: the stored value can't be used, such as an invalid TOTP seed; upload a new version. SECRET_ONEPASSWORD_REFERENCE_FAILED: 1Password couldn't resolve a field; `details.selectors` and `details.reasons` (by selector) name the inputs, and nothing was typed. SECRET_ONEPASSWORD_AUTH_FAILED: 1Password rejected the token, or the token is malformed or signs in outside 1password.com, 1password.ca and 1password.eu (or their subdomains), so it wasn't sent. Both carry `details.tokenSecretId` and `details.tokenVersion`. Other SECRET_* codes mean the stored envelope couldn't be opened.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "429": { "description": "SECRET_ONEPASSWORD_RATE_LIMITED: 1Password is rate limiting the service account (retryable; `details.tokenSecretId` and `details.tokenVersion`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "500": { "description": "CREDENTIAL_FILL_FAILED or an internal server error. Check `retryable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "501": { "description": "CREDENTIAL_FILL_UNSUPPORTED: the session's browser predates credential fill.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "502": { "description": "CREDENTIAL_FILL_FAILED: the browser couldn't complete the fill. SECRET_ONEPASSWORD_FAILED: 1Password couldn't be reached (retryable; `details.tokenSecretId` and `details.tokenVersion`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "503": { "description": "CREDENTIAL_FILL_TIMEOUT: the session's host couldn't be reached and nothing was filled (retryable). SECRETS_NOT_CONFIGURED or SECRET_KEY_UNAVAILABLE: the session's host can't decrypt secrets. SECRET_ONEPASSWORD_FAILED: 1Password isn't available on the session's host, and nothing was typed (retryable; `details.tokenSecretId` and `details.tokenVersion`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "504": { "description": "CREDENTIAL_FILL_TIMEOUT: the fill wasn't confirmed in time (retryable).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } } } } }, "/api/sandbox/{id}/processes": { "post": { "summary": "Start a sandbox process with secrets", "operationId": "startSandboxSecretProcess", "tags": [ "Sandboxes" ], "description": "Starts a process in a running sandbox with secrets as environment variables for that process only. Pass `secrets`, a `vault`, `onePassword` fields, or any of them together: the vault's variables come first and `secrets` is merged over them, while a 1Password variable can't also come from another source. Values are decrypted on the sandbox's host and never returned; a `totp` secret sets the code current when the process starts, and `onePassword` fields are read from 1Password at that moment. Not supported on GPU sandboxes. Secrets are enabled for teams on request; please contact support to enable them (otherwise 403 SECRETS_FEATURE_DISABLED). Restricted API keys need both the sandboxes.read and secrets.use scopes. Don't retry blindly after a 502 SECRET_PROCESS_OUTCOME_UNKNOWN: the process may have started, so check the sandbox's process list first.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Sandbox ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartSandboxSecretProcessParams" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartSandboxSecretProcessResponse" } } } }, "400": { "description": "Invalid request body, the sandbox is a GPU sandbox, or SECRET_SOURCES_INVALID (`env` sets a variable the vault or `secrets` also sets, a 1Password variable is also set by another source, the vault has no entries, or they set more than 32 variables).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "403": { "description": "API_KEY_SCOPE_DENIED or SECRETS_FEATURE_DISABLED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "404": { "description": "Sandbox not found, SECRET_NOT_FOUND, SECRET_VERSION_NOT_FOUND (also when the `onePassword` token has no value), or VAULT_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "409": { "description": "The sandbox is stopped or its runtime isn't ready, or SECRET_TYPE_MISMATCH (an `op_token` secret in `secrets` or the vault, or a `onePassword` token that isn't an `op_token`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "422": { "description": "The sandbox couldn't use a value. SECRET_VALUE_INVALID: a stored value can't be used, such as an invalid TOTP seed; upload a new version. SECRET_ONEPASSWORD_REFERENCE_FAILED: 1Password couldn't resolve a field (`details.envs` and `details.reasons` name the variables). SECRET_ONEPASSWORD_AUTH_FAILED: 1Password rejected the token, or the token is malformed or its sign-in address isn't on 1password.com, 1password.ca, 1password.eu or their subdomains, so it wasn't sent. Other codes, such as SECRET_ENVELOPE_INVALID, mean a stored envelope couldn't be opened; `details` names the variable, secret and version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "429": { "description": "SECRET_ONEPASSWORD_RATE_LIMITED: 1Password is rate limiting the service account (retryable).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "501": { "description": "The sandbox's runner doesn't support secrets. SECRET_TOTP_UNSUPPORTED: the sandbox's host can't deliver TOTP secrets yet, and nothing started (not retryable on this route; a new sandbox may run on an upgraded host).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "502": { "description": "SECRET_PROCESS_OUTCOME_UNKNOWN: the start wasn't confirmed and the process may be running. Not retryable. SECRET_ONEPASSWORD_FAILED: 1Password couldn't be reached and nothing started (retryable).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "503": { "description": "SECRET_PROCESS_NOT_STARTED: the sandbox's host couldn't be reached and no process was started (retryable). SECRET_ONEPASSWORD_FAILED (retryable). SECRETS_NOT_CONFIGURED or SECRET_KEY_UNAVAILABLE: the sandbox's host can't decrypt secrets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } }, "504": { "description": "SECRET_PROCESS_TIMEOUT: timed out before the process was started (retryable).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretErrorResponse" } } } } } } } } }