Automate browser based workflows with AI
Python aiapiautomationbrowserbrowser-automationcomputergptllmplaywrightpowerautomatepuppeteerpythonrpaseleniumvisionworkflow
docs/fix: update TOTP docs, SDK reference, light mode logo, and broken API key links (#5150)
Ritik Sahnid57ced394f48
diff --git a/docs/cloud/managing-credentials/totp-setup.mdx b/docs/cloud/managing-credentials/totp-setup.mdxindex f4ccfd5d2..30ac9f1a5 100644--- a/docs/cloud/managing-credentials/totp-setup.mdx+++ b/docs/cloud/managing-credentials/totp-setup.mdx@@ -156,12 +156,85 @@ 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 953b82eee..1d0e876e5 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/api-keys)+- A **Skyvern API key** — get one at [app.skyvern.com/settings](https://app.skyvern.com/settings/)- 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 39d848a0e..2bdad86c1 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -27,7 +27,7 @@}},"logo": {- "light": "/logo/light.png",+ "light": "/images/skyvern_logo_blackbg.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/api-keys"+ "href": "https://app.skyvern.com/settings/"}},"footer": {diff --git a/docs/integrations/cli.mdx b/docs/integrations/cli.mdxindex ede1058a9..525e1ee39 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/api-keys) in the Skyvern dashboard.+Get an API key from [Settings](https://app.skyvern.com/settings/) in the Skyvern dashboard.</Accordion><Accordion title="No active browser session">diff --git a/docs/integrations/make.mdx b/docs/integrations/make.mdxindex 0d479161a..5ca9432e2 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/api-keys).+ Click **Create a connection** and paste your API key from [Settings](https://app.skyvern.com/settings/).<Frame><videodiff --git a/docs/integrations/n8n.mdx b/docs/integrations/n8n.mdxindex 5a64ccebe..66274e3e1 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/api-keys).+ Click *Select credential* → "Create new credential" and paste your API key from [Settings](https://app.skyvern.com/settings/).</Step><Step title="Configure">diff --git a/docs/integrations/workato.mdx b/docs/integrations/workato.mdxindex c1180083b..2a9df200b 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/api-keys) and save the connection.+ Paste your API key from [Settings](https://app.skyvern.com/settings/) 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 24f04319b..249af0445 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/api-keys).+ Click *Sign in* on the left panel and paste your API key from [Settings](https://app.skyvern.com/settings/).<Frame><videodiff --git a/docs/sdk-reference/complete-reference.mdx b/docs/sdk-reference/complete-reference.mdxindex 53224569c..8f6e43311 100644--- a/docs/sdk-reference/complete-reference.mdx+++ b/docs/sdk-reference/complete-reference.mdx@@ -47,6 +47,264 @@ 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@@ -591,3 +849,6 @@ 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 a70112178..1bd5f3b59 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-keys). |+| `api_key` | `str` | — | **Required.** Your Skyvern API key. Get one at [app.skyvern.com/settings](https://app.skyvern.com/settings/). || `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 47d324955..6285190e7 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/api-keys). |+| `apiKey` | `string` | — | **Required.** Your Skyvern API key. Get one at [app.skyvern.com/settings](https://app.skyvern.com/settings/). || `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. |