Automate browser based workflows with AI
Python aiapiautomationbrowserbrowser-automationcomputergptllmplaywrightpowerautomatepuppeteerpythonrpaseleniumvisionworkflow
fix: credential selectors stuck on skeleton during background refetch (#5151)
Celal Zamanoğlud80938dcfdf9
diff --git a/docs/cloud/managing-credentials/totp-setup.mdx b/docs/cloud/managing-credentials/totp-setup.mdxindex 30ac9f1a5..f4ccfd5d2 100644--- a/docs/cloud/managing-credentials/totp-setup.mdx+++ b/docs/cloud/managing-credentials/totp-setup.mdx@@ -156,85 +156,12 @@ This turns email-based 2FA into something nearly as automated as an authenticato----## Server-fetched codes (totp_url)--Instead of pushing codes to Skyvern, you can have Skyvern pull them from your server. Pass `totp_url` when running a [task](/running-automations/extract-structured-data) or [workflow](/multi-step-automations/build-a-workflow), and Skyvern will call your endpoint when it needs a verification code.--Your endpoint must accept a POST request with `task_id`, `workflow_run_id`, and `workflow_permanent_id` in the body, and return:--```json-{- "verification_code": "123456"-}-```--Validate the `x-skyvern-signature` header to confirm the request came from Skyvern:--```python-import hashlib, hmac--def validate_skyvern_request(request) -> bool:- signature = request.headers["x-skyvern-signature"]- payload = request.body() # bytes- expected = hmac.new(- SKYVERN_API_KEY.encode("utf-8"),- msg=payload,- digestmod=hashlib.sha256,- ).hexdigest()- return signature == expected-```-------## Magic links (one-time login links)--Some sites use one-time login links instead of numeric codes. Skyvern supports these by splitting the flow into two steps:--1. **Trigger the magic link** — Run a task that initiates the login. The site emails a one-time link.-2. **Use the link** — Monitor the inbox (e.g., via Zapier), extract the URL, then start a new task with that URL as the starting point.--```python-# Step 1: Trigger the magic link email-await client.run_task(- prompt="Click 'Sign in with email link' and enter [email protected]",- url="https://app.example.com/login",- wait_for_completion=True,-)--# Step 2: Your email monitor extracts the magic link URL, then:-await client.run_task(- prompt="Complete the onboarding form after login",- url=magic_link_url, # The one-time URL from the email- wait_for_completion=True,-)-```--The magic link URL becomes the `url` parameter for the second task — Skyvern opens it directly, which logs the user in, and then continues with the rest of the automation.------## Viewing past codesThe table below the push form shows all 2FA codes your organization has received: identifier, extracted code, source type, associated workflow run, and timestamps. Filter by identifier, OTP type (numeric code vs. magic link), and number of results per page.Use this for auditing and debugging: confirming that a code was received and delivered to the right run.-### Listing codes via API--```bash-curl -X GET "https://api.skyvern.com/v1/credentials/[email protected]&limit=10" \- -H "x-api-key: $SKYVERN_API_KEY"-```--| Parameter | Description |-|-----------|-------------|-| `totp_identifier` | Filter by identifier (email, phone, etc.) |-| `workflow_run_id` | Restrict to a specific workflow run |-| `otp_type` | Filter by `totp` or `magic_link` |-| `limit` | Number of records (default 50, max 200) |--Returns a list ordered newest first. Only codes created within the last 10 minutes (configurable via `TOTP_LIFESPAN_MINUTES`) are returned.-<CardGroup cols={2}><Cardtitle="Password Credentials"diff --git a/docs/debugging/observability-with-laminar.mdx b/docs/debugging/observability-with-laminar.mdxindex 1d0e876e5..953b82eee 100644--- a/docs/debugging/observability-with-laminar.mdx+++ b/docs/debugging/observability-with-laminar.mdx@@ -34,7 +34,7 @@ npm install @skyvern/client @lmnr-ai/lmnr</CodeGroup>You will also need:-- A **Skyvern API key** — get one at [app.skyvern.com/settings](https://app.skyvern.com/settings/)+- A **Skyvern API key** — get one at [app.skyvern.com/settings](https://app.skyvern.com/settings/api-keys)- A **Laminar API key** — sign up at [lmnr.ai](https://www.lmnr.ai/) and create a project---diff --git a/docs/docs.json b/docs/docs.jsonindex 2bdad86c1..39d848a0e 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -27,7 +27,7 @@}},"logo": {- "light": "/images/skyvern_logo_blackbg.png",+ "light": "/logo/light.png","dark": "/logo/dark.png","href": "https://skyvern.com"},@@ -236,7 +236,7 @@"primary": {"type": "button","label": "Get API Key",- "href": "https://app.skyvern.com/settings/"+ "href": "https://app.skyvern.com/settings/api-keys"}},"footer": {diff --git a/docs/integrations/cli.mdx b/docs/integrations/cli.mdxindex 525e1ee39..ede1058a9 100644--- a/docs/integrations/cli.mdx+++ b/docs/integrations/cli.mdx@@ -258,7 +258,7 @@ You can also pass it directly:skyvern credentials add --api-key YOUR_KEY```-Get an API key from [Settings](https://app.skyvern.com/settings/) in the Skyvern dashboard.+Get an API key from [Settings](https://app.skyvern.com/settings/api-keys) in the Skyvern dashboard.</Accordion><Accordion title="No active browser session">diff --git a/docs/integrations/make.mdx b/docs/integrations/make.mdxindex 5ca9432e2..0d479161a 100644--- a/docs/integrations/make.mdx+++ b/docs/integrations/make.mdx@@ -35,7 +35,7 @@ Connect Skyvern to 2,000+ apps through Make. Trigger browser automations from an</Step><Step title="Connect your account">- Click **Create a connection** and paste your API key from [Settings](https://app.skyvern.com/settings/).+ Click **Create a connection** and paste your API key from [Settings](https://app.skyvern.com/settings/api-keys).<Frame><videodiff --git a/docs/integrations/n8n.mdx b/docs/integrations/n8n.mdxindex 66274e3e1..5a64ccebe 100644--- a/docs/integrations/n8n.mdx+++ b/docs/integrations/n8n.mdx@@ -32,7 +32,7 @@ Connect Skyvern to n8n's open-source automation platform. Trigger browser automa</Step><Step title="Connect your account">- Click *Select credential* → "Create new credential" and paste your API key from [Settings](https://app.skyvern.com/settings/).+ Click *Select credential* → "Create new credential" and paste your API key from [Settings](https://app.skyvern.com/settings/api-keys).</Step><Step title="Configure">diff --git a/docs/integrations/workato.mdx b/docs/integrations/workato.mdxindex 2a9df200b..c1180083b 100644--- a/docs/integrations/workato.mdx+++ b/docs/integrations/workato.mdx@@ -40,7 +40,7 @@ Connect Skyvern to Workato's enterprise automation platform. Trigger browser aut</Step><Step title="Connect your account">- Paste your API key from [Settings](https://app.skyvern.com/settings/) and save the connection.+ Paste your API key from [Settings](https://app.skyvern.com/settings/api-keys) and save the connection.<Frame><img src="/images/workato/s1img7.png" alt="Connect Skyvern account in Workato" />diff --git a/docs/integrations/zapier.mdx b/docs/integrations/zapier.mdxindex 249af0445..24f04319b 100644--- a/docs/integrations/zapier.mdx+++ b/docs/integrations/zapier.mdx@@ -37,7 +37,7 @@ Connect Skyvern to 7,000+ apps through Zapier. Trigger browser automations from</Step><Step title="Connect your account">- Click *Sign in* on the left panel and paste your API key from [Settings](https://app.skyvern.com/settings/).+ Click *Sign in* on the left panel and paste your API key from [Settings](https://app.skyvern.com/settings/api-keys).<Frame><videodiff --git a/docs/sdk-reference/complete-reference.mdx b/docs/sdk-reference/complete-reference.mdxindex 8f6e43311..53224569c 100644--- a/docs/sdk-reference/complete-reference.mdx+++ b/docs/sdk-reference/complete-reference.mdx@@ -47,264 +47,6 @@ All methods are async. Use `await` inside `async def`, with `asyncio.run()` as e----## Browser control--The SDK can launch and connect to browsers directly, giving you a Playwright-compatible page with AI capabilities layered on top. This is separate from the API-level browser session methods — here you get a live `SkyvernBrowser` and `SkyvernBrowserPage` you can script against.--### `launch_local_browser`--Launch a local Chromium browser with CDP enabled. Requires local mode (`Skyvern.local()`).--```python-browser = await client.launch_local_browser(- headless: bool = False, # Run headless or with a visible window.- port: int = 9222, # CDP port.- args: list[str] | None = None, # Extra Chromium flags.- user_data_dir: str | None = None,# Persistent profile directory.-) -> SkyvernBrowser-```--### `connect_to_browser_over_cdp`--Connect to any running browser via Chrome DevTools Protocol.--```python-browser = await client.connect_to_browser_over_cdp(- cdp_url: str, # e.g. "http://localhost:9222"-) -> SkyvernBrowser-```--### `connect_to_cloud_browser_session`--Connect to an existing cloud browser session by ID.--```python-browser = await client.connect_to_cloud_browser_session(- browser_session_id: str,-) -> SkyvernBrowser-```--### `launch_cloud_browser`--Create a new cloud browser session and connect to it.--```python-browser = await client.launch_cloud_browser(- timeout: int | None = None, # Minutes (5-1440). Default 60.- proxy_location: ProxyLocation | None = None,-) -> SkyvernBrowser-```--### `use_cloud_browser`--Reuse the most recent available cloud session, or create a new one if none exists.--```python-browser = await client.use_cloud_browser(- timeout: int | None = None,- proxy_location: ProxyLocation | None = None,-) -> SkyvernBrowser-```--### Getting a page--```python-page = await browser.get_working_page() # Most recent page, or creates one-page = await browser.new_page() # Always creates a new tab-```--Both return a `SkyvernBrowserPage` — a Playwright `Page` with AI methods added.-------## Page-level AI methods--`SkyvernBrowserPage` extends Playwright's `Page`. You can use all standard Playwright methods (`goto`, `fill`, `locator`, `screenshot`, etc.) plus these AI-powered methods.--### `page.act`--Perform an action described in natural language.--```python-await page.act(prompt: str) -> None-```--```python-await page.act("Click the login button")-await page.act("Select 'United States' from the country dropdown")-```--### `page.click` (AI-enhanced)--Click an element using a CSS selector, an AI prompt, or both with fallback.--```python-await page.click(- selector: str | None = None, # CSS selector.- prompt: str | None = None, # Natural language target description.- ai: str | None = "fallback", # "fallback" (try selector, then AI) or None.- **kwargs, # Standard Playwright click options.-) -> str | None-```--```python-# Selector only-await page.click("#submit-btn")--# AI only-await page.click(prompt="Click the 'Submit Order' button")--# Selector with AI fallback-await page.click("#submit-btn", prompt="Click the submit button")-```--### `page.extract`--Extract structured data from the current page using AI.--```python-result = await page.extract(- prompt: str, # What to extract.- schema: dict | list | str | None = None, # JSON Schema for the output.- error_code_mapping: dict[str, str] | None = None,-) -> dict | list | str | None-```--```python-products = await page.extract(- prompt="Extract all products with name and price",- schema={- "type": "array",- "items": {- "type": "object",- "properties": {- "name": {"type": "string"},- "price": {"type": "number"},- },- },- },-)-```--### `page.agent.run_task`--Run an AI task in the context of the current page. Always waits for completion.--```python-result = await page.agent.run_task(- prompt: str,- engine: RunEngine = RunEngine.skyvern_v2,- url: str | None = None, # Defaults to current page URL.- data_extraction_schema: dict | str | None = None,- max_steps: int | None = None,- timeout: float = 1800,- # Plus: model, webhook_url, totp_identifier, totp_url, title, error_code_mapping, user_agent-) -> TaskRunResponse-```--### `page.agent.login`--Run a login workflow in the context of the current page. Supports all credential types.--```python-# Skyvern credentials-await page.agent.login(- credential_type=CredentialType.skyvern,- credential_id="cred_123",-)--# Bitwarden-await page.agent.login(- credential_type=CredentialType.bitwarden,- bitwarden_item_id="item_id",-)--# 1Password-await page.agent.login(- credential_type=CredentialType.onepassword,- onepassword_vault_id="vault_id",- onepassword_item_id="item_id",-)--# Azure Key Vault-await page.agent.login(- credential_type=CredentialType.azure_vault,- azure_vault_name="vault_name",- azure_vault_username_key="username_key",- azure_vault_password_key="password_key",-)-```--### `page.agent.download_files`--Download files using AI navigation, in the context of the current page.--```python-result = await page.agent.download_files(- prompt: str,- url: str | None = None,- download_suffix: str | None = None,- download_timeout: float | None = None,- max_steps_per_run: int | None = None,- timeout: float = 1800,-) -> WorkflowRunResponse-```--### `page.agent.run_workflow`--Run a workflow in the context of the current page.--```python-result = await page.agent.run_workflow(- workflow_id: str,- parameters: dict | None = None,- timeout: float = 1800,-) -> WorkflowRunResponse-```--### Full example--```python-from skyvern import Skyvern-from skyvern.schemas.run_blocks import CredentialType--async def main():- client = Skyvern(api_key="YOUR_API_KEY")- browser = await client.launch_cloud_browser()- page = await browser.get_working_page()-- # Navigate and log in with AI- await page.goto("https://app.example.com")- await page.agent.login(- credential_type=CredentialType.skyvern,- credential_id="cred_123",- )-- # Mix Playwright and AI- await page.click("#invoices-tab")- data = await page.extract(- prompt="Extract all invoice numbers and amounts",- schema={- "type": "array",- "items": {- "type": "object",- "properties": {- "invoice_number": {"type": "string"},- "amount": {"type": "number"},- },- },- },- )- print(data)-- await browser.close()--import asyncio-asyncio.run(main())-```------## Imports```python@@ -849,6 +591,3 @@ print(run.output)- Only workflow runs with `persist_browser_session=True` produce archives for profile creation.- Session archiving is async — profile creation may need a short retry delay after a run completes.- `engine` accepts `RunEngine` enum values: `skyvern_v1`, `skyvern_v2`, `openai_cua`, `anthropic_cua`, `ui_tars`.-- `launch_local_browser` only works in local mode (`Skyvern.local()`). Cloud browser methods (`launch_cloud_browser`, `use_cloud_browser`, `connect_to_cloud_browser_session`) require cloud environment.-- `page.agent` methods always wait for completion — they don't support `wait_for_completion=False`.-- TypeScript SDK does not support browser control (local or cloud) — use the Python SDK for browser automation.diff --git a/docs/sdk-reference/overview.mdx b/docs/sdk-reference/overview.mdxindex 1bd5f3b59..a70112178 100644--- a/docs/sdk-reference/overview.mdx+++ b/docs/sdk-reference/overview.mdx@@ -43,7 +43,7 @@ If you're inside a framework that already runs an event loop (FastAPI, Django AS| Parameter | Type | Default | Description ||-----------|------|---------|-------------|-| `api_key` | `str` | — | **Required.** Your Skyvern API key. Get one at [app.skyvern.com/settings](https://app.skyvern.com/settings/). |+| `api_key` | `str` | — | **Required.** Your Skyvern API key. Get one at [app.skyvern.com/settings](https://app.skyvern.com/settings/api-keys). || `environment` | `SkyvernEnvironment` | `CLOUD` | Target environment. Options: `CLOUD`, `STAGING`, `LOCAL`. || `base_url` | `str \| None` | `None` | Override the API base URL. Use this for self-hosted deployments. || `timeout` | `float \| None` | `None` | HTTP request timeout in seconds. |diff --git a/docs/ts-sdk-reference/overview.mdx b/docs/ts-sdk-reference/overview.mdxindex 6285190e7..47d324955 100644--- a/docs/ts-sdk-reference/overview.mdx+++ b/docs/ts-sdk-reference/overview.mdx@@ -39,7 +39,7 @@ console.log(result.output);| Parameter | Type | Default | Description ||-----------|------|---------|-------------|-| `apiKey` | `string` | — | **Required.** Your Skyvern API key. Get one at [app.skyvern.com/settings](https://app.skyvern.com/settings/). |+| `apiKey` | `string` | — | **Required.** Your Skyvern API key. Get one at [app.skyvern.com/settings](https://app.skyvern.com/settings/api-keys). || `environment` | `SkyvernEnvironment \| string` | `Cloud` | Target environment. Options: `Cloud`, `Staging`, `Local`. || `baseUrl` | `string` | `undefined` | Override the API base URL. Use this for self-hosted deployments. || `timeoutInSeconds` | `number` | `60` | HTTP request timeout in seconds. |