vodorod/Dorod-Sky
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

feat: new workflows docs (#4565)

Browse Source 
Co-authored-by: Kunal Mishra <kunalm2345@gmail.com>
Co-authored-by: Suchintan <suchintan@users.noreply.github.com>
This commit is contained in:
Naman
2026-02-05 03:34:57 +05:30
committed by GitHub
parent 54bab314ce
commit 734e0e6398
16 changed files with 21972 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1115
docs/multi-step-automations/build-a-workflow.mdx Normal file
View File

File diff suppressed because it is too large Load Diff

2074
docs/multi-step-automations/file-operations.mdx Normal file
View File

File diff suppressed because it is too large Load Diff

1194
docs/multi-step-automations/workflow-blocks-reference.mdx Normal file
View File

File diff suppressed because it is too large Load Diff

818
docs/multi-step-automations/workflow-parameters.mdx Normal file
View File

@@ -0,0 +1,818 @@
---
title: Workflow Parameters
subtitle: Configure how your workflow runs
slug: multi-step-automations/workflow-parameters
---
This page covers all parameters you can pass when creating and running workflows.
---
## Quick reference: Creating a workflow
| Parameter | Type | Use this to |
|-----------|------|-------------|
| [`title`](#title) **(Required)** | string | Name the workflow for identification |
| [`workflow_definition`](#workflow_definition) **(Required)** | object | Define blocks, parameters, and logic |
| [`description`](#description) | string | Document what the workflow does |
| [`proxy_location`](#proxy_location-create) | string or object | Set default proxy for all blocks |
| [`webhook_callback_url`](#webhook_callback_url) | string | Get notified when any run of this workflow completes |
| [`persist_browser_session`](#persist_browser_session) | boolean | Keep the browser session alive across blocks |
---
## Quick reference: Running a workflow
| Parameter | Type | Use this to |
|-----------|------|-------------|
| [`workflow_id`](#workflow_id) **(Required)** | string | Specify which workflow to run |
| [`parameters`](#parameters) | object | Pass values for workflow input parameters |
| [`title`](#title-run) | string | Name this specific workflow run |
| [`proxy_location`](#proxy_location-run) | string or object | Override the default proxy location |
| [`webhook_url`](#webhook_url) | string | Get notified when the workflow completes |
| [`browser_session_id`](#browser_session_id) | string | Reuse a persistent browser session |
| [`browser_profile_id`](#browser_profile_id) | string | Reuse a browser profile (cookies, storage) |
---
## Creating a workflow
<Info>
All create parameters (`title`, `workflow_definition`, `description`, `proxy_location`, etc.) are nested inside a **`json_definition`** object — not passed at the top level. You can alternatively use `yaml_definition` (a YAML string) instead.
</Info>
<CodeGroup>
```python Python
workflow = await client.create_workflow(
json_definition={
"title": "...",
"workflow_definition": {...}
}
)
```
```typescript TypeScript
const workflow = await client.createWorkflow({
body: {
json_definition: {
title: "...",
workflow_definition: {...},
},
},
});
```
```bash cURL
curl -X POST "https://api.skyvern.com/v1/workflows" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"json_definition": {
"title": "...",
"workflow_definition": {...}
}
}'
```
</CodeGroup>
### `title`
**Required.** Display name for the workflow. This field goes inside the `json_definition` object.
<CodeGroup>
```python Python
workflow = await client.create_workflow(
json_definition={
"title": "Invoice Downloader",
"workflow_definition": {...}
}
)
```
```typescript TypeScript
const workflow = await client.createWorkflow({
body: {
json_definition: {
title: "Invoice Downloader",
workflow_definition: {...},
},
},
});
```
```bash cURL
curl -X POST "https://api.skyvern.com/v1/workflows" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"json_definition": {
"title": "Invoice Downloader",
"workflow_definition": {...}
}
}'
```
</CodeGroup>
---
### `workflow_definition`
**Required.** The workflow structure containing parameters and blocks.
```json
{
"workflow_definition": {
"parameters": [...],
"blocks": [...]
}
}
```
#### `parameters`
Input parameters the workflow accepts. Each parameter has:
| Field | Type | Description |
|-------|------|-------------|
| `key` | string | Parameter name, used to reference via `{{ key }}` |
| `parameter_type` | string | Always `"workflow"` for input parameters |
| `workflow_parameter_type` | string | Data type: `string`, `integer`, `float`, `boolean`, `json`, `file_url`, `credential_id` |
| `default_value` | any | Optional default value |
| `description` | string | Optional description |
<CodeGroup>
```python Python
workflow = await client.create_workflow(
json_definition={
"title": "Job Application Workflow",
"workflow_definition": {
"parameters": [
{
"key": "resume",
"parameter_type": "workflow",
"workflow_parameter_type": "file_url",
"description": "URL to the resume PDF"
},
{
"key": "job_urls",
"parameter_type": "workflow",
"workflow_parameter_type": "json",
"default_value": []
},
{
"key": "cover_letter",
"parameter_type": "workflow",
"workflow_parameter_type": "string",
"default_value": ""
}
],
"blocks": [...]
}
}
)
```
```typescript TypeScript
const workflow = await client.createWorkflow({
body: {
json_definition: {
title: "Job Application Workflow",
workflow_definition: {
parameters: [
{
key: "resume",
parameter_type: "workflow",
workflow_parameter_type: "file_url",
description: "URL to the resume PDF",
},
{
key: "job_urls",
parameter_type: "workflow",
workflow_parameter_type: "json",
default_value: [],
},
{
key: "cover_letter",
parameter_type: "workflow",
workflow_parameter_type: "string",
default_value: "",
},
],
blocks: [...],
},
},
},
});
```
```bash cURL
curl -X POST "https://api.skyvern.com/v1/workflows" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"json_definition": {
"title": "Job Application Workflow",
"workflow_definition": {
"parameters": [
{
"key": "resume",
"parameter_type": "workflow",
"workflow_parameter_type": "file_url",
"description": "URL to the resume PDF"
},
{
"key": "job_urls",
"parameter_type": "workflow",
"workflow_parameter_type": "json",
"default_value": []
},
{
"key": "cover_letter",
"parameter_type": "workflow",
"workflow_parameter_type": "string",
"default_value": ""
}
],
"blocks": [...]
}
}
}'
```
</CodeGroup>
**Parameter types:**
| Type | Description | Example |
|------|-------------|---------|
| `string` | Text value | `"John Smith"` |
| `integer` | Whole number | `42` |
| `float` | Decimal number | `99.99` |
| `boolean` | True/false | `true` |
| `json` | JSON object or array | `{"key": "value"}` or `["a", "b"]` |
| `file_url` | URL to a file | `"https://example.com/resume.pdf"` |
| `credential_id` | Reference to a stored credential | `"cred_abc123"` |
#### `blocks`
Array of blocks that execute in sequence. See [Workflow Blocks Reference](/multi-step-automations/workflow-blocks-reference) for all block types.
---
### `description`
Optional description of what the workflow does.
<CodeGroup>
```python Python
workflow = await client.create_workflow(
json_definition={
"title": "Invoice Downloader",
"description": "Downloads all invoices from the vendor portal since a given date",
"workflow_definition": {...}
}
)
```
```typescript TypeScript
const workflow = await client.createWorkflow({
body: {
json_definition: {
title: "Invoice Downloader",
description: "Downloads all invoices from the vendor portal since a given date",
workflow_definition: {...},
},
},
});
```
```bash cURL
curl -X POST "https://api.skyvern.com/v1/workflows" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"json_definition": {
"title": "Invoice Downloader",
"description": "Downloads all invoices from the vendor portal since a given date",
"workflow_definition": {...}
}
}'
```
</CodeGroup>
---
### `proxy_location` (create)
Default proxy location for all blocks in the workflow. Individual blocks can override this.
See [Proxy & Geo Targeting](/going-to-production/proxy-geolocation) for all available locations.
<CodeGroup>
```python Python
workflow = await client.create_workflow(
json_definition={
"title": "UK Price Checker",
"proxy_location": "RESIDENTIAL_GB",
"workflow_definition": {...}
}
)
```
```typescript TypeScript
const workflow = await client.createWorkflow({
body: {
json_definition: {
title: "UK Price Checker",
proxy_location: "RESIDENTIAL_GB",
workflow_definition: {...},
},
},
});
```
```bash cURL
curl -X POST "https://api.skyvern.com/v1/workflows" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"json_definition": {
"title": "UK Price Checker",
"proxy_location": "RESIDENTIAL_GB",
"workflow_definition": {...}
}
}'
```
</CodeGroup>
---
### `webhook_callback_url`
URL to receive a POST request whenever any run of this workflow completes. This is set at the workflow level and applies to all runs. To set a webhook for a single run instead, use [`webhook_url`](#webhook_url) when running the workflow.
<CodeGroup>
```python Python
workflow = await client.create_workflow(
json_definition={
"title": "Invoice Downloader",
"webhook_callback_url": "https://your-server.com/webhook",
"workflow_definition": {...}
}
)
```
```typescript TypeScript
const workflow = await client.createWorkflow({
body: {
json_definition: {
title: "Invoice Downloader",
webhook_callback_url: "https://your-server.com/webhook",
workflow_definition: {...},
},
},
});
```
```bash cURL
curl -X POST "https://api.skyvern.com/v1/workflows" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"json_definition": {
"title": "Invoice Downloader",
"webhook_callback_url": "https://your-server.com/webhook",
"workflow_definition": {...}
}
}'
```
</CodeGroup>
---
### `persist_browser_session`
If `true`, the browser session is kept alive across all blocks in the workflow. This means blocks share the same browser context including cookies, local storage, and login state.
Defaults to `false`.
<CodeGroup>
```python Python
workflow = await client.create_workflow(
json_definition={
"title": "Multi-Step Portal Scraper",
"persist_browser_session": True,
"workflow_definition": {...}
}
)
```
```typescript TypeScript
const workflow = await client.createWorkflow({
body: {
json_definition: {
title: "Multi-Step Portal Scraper",
persist_browser_session: true,
workflow_definition: {...},
},
},
});
```
```bash cURL
curl -X POST "https://api.skyvern.com/v1/workflows" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"json_definition": {
"title": "Multi-Step Portal Scraper",
"persist_browser_session": true,
"workflow_definition": {...}
}
}'
```
</CodeGroup>
<Info>
Additional advanced parameters are available when creating a workflow, including `totp_verification_url`, `totp_identifier`, `model`, and `extra_http_headers`. See the [API Reference](/api-reference) for the full list.
</Info>
---
## Running a workflow
### `workflow_id`
**Required.** The ID of the workflow to run. This is the `workflow_permanent_id` returned when creating the workflow.
<CodeGroup>
```python Python
run = await client.run_workflow(
workflow_id="wpid_123456789",
parameters={...}
)
```
```typescript TypeScript
const run = await client.runWorkflow({
body: {
workflow_id: "wpid_123456789",
parameters: {...},
},
});
```
```bash cURL
curl -X POST "https://api.skyvern.com/v1/run/workflows" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workflow_id": "wpid_123456789",
"parameters": {...}
}'
```
</CodeGroup>
---
### `parameters`
Values for the workflow's input parameters. Keys must match the `key` field in the workflow's parameter definitions.
<CodeGroup>
```python Python
run = await client.run_workflow(
workflow_id="wpid_123456789",
parameters={
"resume": "https://example.com/resume.pdf",
"job_urls": [
"https://jobs.lever.co/company/position-1",
"https://jobs.lever.co/company/position-2"
],
"cover_letter": "I am excited to apply for this position..."
}
)
```
```typescript TypeScript
const run = await client.runWorkflow({
body: {
workflow_id: "wpid_123456789",
parameters: {
resume: "https://example.com/resume.pdf",
job_urls: [
"https://jobs.lever.co/company/position-1",
"https://jobs.lever.co/company/position-2",
],
cover_letter: "I am excited to apply for this position...",
},
},
});
```
```bash cURL
curl -X POST "https://api.skyvern.com/v1/run/workflows" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workflow_id": "wpid_123456789",
"parameters": {
"resume": "https://example.com/resume.pdf",
"job_urls": [
"https://jobs.lever.co/company/position-1",
"https://jobs.lever.co/company/position-2"
],
"cover_letter": "I am excited to apply for this position..."
}
}'
```
</CodeGroup>
Parameters with `default_value` in the workflow definition are optional. Parameters without defaults are required.
---
### `proxy_location` (run)
Override the workflow's default proxy location for this run.
<CodeGroup>
```python Python
run = await client.run_workflow(
workflow_id="wpid_123456789",
parameters={...},
proxy_location="RESIDENTIAL_CA"
)
```
```typescript TypeScript
const run = await client.runWorkflow({
body: {
workflow_id: "wpid_123456789",
parameters: {...},
proxy_location: "RESIDENTIAL_CA",
},
});
```
```bash cURL
curl -X POST "https://api.skyvern.com/v1/run/workflows" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workflow_id": "wpid_123456789",
"parameters": {...},
"proxy_location": "RESIDENTIAL_CA"
}'
```
</CodeGroup>
**Proxy locations:**
| Value | Location |
|-------|----------|
| `RESIDENTIAL` | United States **(default)** |
| `RESIDENTIAL_ISP` | United States (static ISP IPs) |
| `RESIDENTIAL_AR` | Argentina |
| `RESIDENTIAL_AU` | Australia |
| `RESIDENTIAL_BR` | Brazil |
| `RESIDENTIAL_CA` | Canada |
| `RESIDENTIAL_DE` | Germany |
| `RESIDENTIAL_ES` | Spain |
| `RESIDENTIAL_FR` | France |
| `RESIDENTIAL_GB` | United Kingdom |
| `RESIDENTIAL_IE` | Ireland |
| `RESIDENTIAL_IN` | India |
| `RESIDENTIAL_IT` | Italy |
| `RESIDENTIAL_JP` | Japan |
| `RESIDENTIAL_MX` | Mexico |
| `RESIDENTIAL_NL` | Netherlands |
| `RESIDENTIAL_NZ` | New Zealand |
| `RESIDENTIAL_TR` | Türkiye |
| `RESIDENTIAL_ZA` | South Africa |
| `NONE` | No proxy |
For US state or city-level targeting, pass a `GeoTarget` object instead:
```json
{
"proxy_location": {
"country": "US",
"subdivision": "CA",
"city": "San Francisco"
}
}
```
`country` is required (ISO 3166-1 alpha-2 code). `subdivision` and `city` are optional.
See [Proxy & Geo Targeting](/going-to-production/proxy-geolocation) for more details.
---
### `webhook_url`
URL to receive a POST request when the workflow completes.
<CodeGroup>
```python Python
run = await client.run_workflow(
workflow_id="wpid_123456789",
parameters={...},
webhook_url="https://your-server.com/webhook"
)
```
```typescript TypeScript
const run = await client.runWorkflow({
body: {
workflow_id: "wpid_123456789",
parameters: {...},
webhook_url: "https://your-server.com/webhook",
},
});
```
```bash cURL
curl -X POST "https://api.skyvern.com/v1/run/workflows" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workflow_id": "wpid_123456789",
"parameters": {...},
"webhook_url": "https://your-server.com/webhook"
}'
```
</CodeGroup>
The webhook payload contains the same data as the polling response. See [Webhooks](/going-to-production/webhooks) for authentication and retry options.
---
### `title` (run)
Optional display name for this specific workflow run. Useful for distinguishing runs in the UI and API responses.
<CodeGroup>
```python Python
run = await client.run_workflow(
workflow_id="wpid_123456789",
title="January 2025 Invoice Batch",
parameters={...}
)
```
```typescript TypeScript
const run = await client.runWorkflow({
body: {
workflow_id: "wpid_123456789",
title: "January 2025 Invoice Batch",
parameters: {...},
},
});
```
```bash cURL
curl -X POST "https://api.skyvern.com/v1/run/workflows" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workflow_id": "wpid_123456789",
"title": "January 2025 Invoice Batch",
"parameters": {...}
}'
```
</CodeGroup>
---
### `browser_session_id`
ID of an existing Skyvern browser session to reuse. The workflow run continues from the current screen state of that session. Browser session IDs start with `pbs_`.
<CodeGroup>
```python Python
run = await client.run_workflow(
workflow_id="wpid_123456789",
browser_session_id="pbs_abc123",
parameters={...}
)
```
```typescript TypeScript
const run = await client.runWorkflow({
body: {
workflow_id: "wpid_123456789",
browser_session_id: "pbs_abc123",
parameters: {...},
},
});
```
```bash cURL
curl -X POST "https://api.skyvern.com/v1/run/workflows" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workflow_id": "wpid_123456789",
"browser_session_id": "pbs_abc123",
"parameters": {...}
}'
```
</CodeGroup>
---
### `browser_profile_id`
ID of a browser profile to reuse. Browser profiles persist cookies, local storage, and other browser state across runs. Profile IDs start with `bp_`.
<CodeGroup>
```python Python
run = await client.run_workflow(
workflow_id="wpid_123456789",
browser_profile_id="bp_xyz789",
parameters={...}
)
```
```typescript TypeScript
const run = await client.runWorkflow({
body: {
workflow_id: "wpid_123456789",
browser_profile_id: "bp_xyz789",
parameters: {...},
},
});
```
```bash cURL
curl -X POST "https://api.skyvern.com/v1/run/workflows" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workflow_id": "wpid_123456789",
"browser_profile_id": "bp_xyz789",
"parameters": {...}
}'
```
</CodeGroup>
<Info>
Additional advanced parameters are available when running a workflow, including `totp_url`, `totp_identifier`, `browser_address`, `extra_http_headers`, and `max_screenshot_scrolls`. See the [API Reference](/api-reference) for the full list.
</Info>
---
## Run response
When you run a workflow, the response contains:
| Field | Type | Description |
|-------|------|-------------|
| `run_id` | string | Unique ID for this run (starts with `wr_`). |
| `status` | string | One of: `created`, `queued`, `running`, `completed`, `failed`, `terminated`, `timed_out`, `canceled`. |
| `output` | object/array/string/null | Extracted data from the workflow, if any. |
| `failure_reason` | string/null | Why the run failed, if applicable. |
| `errors` | array/null | List of errors encountered during the run. |
| `downloaded_files` | array/null | Files downloaded during the run. |
| `recording_url` | string/null | URL to the browser recording. |
| `screenshot_urls` | array/null | Latest screenshots in reverse chronological order. |
| `app_url` | string/null | Link to view this run in the Skyvern UI. |
| `created_at` | datetime | When the run was created. |
| `started_at` | datetime/null | When execution started. |
| `finished_at` | datetime/null | When execution finished. |
---
## Next steps
<CardGroup cols={2}>
<Card
title="Build a Workflow"
icon="hammer"
href="/multi-step-automations/build-a-workflow"
>
Create and run your first workflow
</Card>
<Card
title="Workflow Blocks Reference"
icon="cube"
href="/multi-step-automations/workflow-blocks-reference"
>
Detailed documentation for all block types
</Card>
<Card
title="Proxy & Geo Targeting"
icon="globe"
href="/going-to-production/proxy-geolocation"
>
Full list of proxy locations
</Card>
<Card
title="Webhooks"
icon="webhook"
href="/going-to-production/webhooks"
>
Handle webhook authentication and retries
</Card>
</CardGroup>