create_workflow

Create a new workflow from a JSON or YAML definition.

Retry policy

Add retry_policy inside workflow_definition to retry eligible top-level runs. Omit the field, or set it to null, to disable retries.

Field	Default	Description
`max_retries`	`1`	Maximum retries after the initial attempt. Allowed range: `1` to `5`.
`delay_seconds`	`0`	Fixed delay before the next attempt. Allowed range: `0` to `3600`.
`webhook_on_retry`	`final_only`	Use `final_only` for one webhook after the final attempt. Use `every_attempt` for one webhook after each attempt.
`retry_on`	—	One or more rules. Each rule has a terminal `status` and an optional `error_codes` list. The `canceled` status is accepted for forward compatibility.

A rule matches when the run status matches and any listed error code matches. Omit error_codes, or use an empty list, to match any error code for that status. Rules use OR logic. Canceled runs never retry in the current runtime, including explicit API/UI cancels. The policy applies only to top-level runs. Each retry keeps the same workflow_run_id. Each attempt uses credits. The maximum elapsed time limit resets for each attempt, so the total run duration can exceed that limit.

title: Extract Products
workflow_definition:
  parameters: []
  retry_policy:
    max_retries: 2
    delay_seconds: 10
    webhook_on_retry: final_only
    retry_on:
      - status: terminated
        error_codes: [portal_timeout, mfa_failed]
      - status: failed
  blocks:
    - block_type: navigation
      label: extract_products
      url: https://example.com/products
      navigation_goal: Extract the top three products.

workflow = await client.create_workflow(
    json_definition={
        "title": "Extract Products",
        "workflow_definition": {
            "parameters": [
                {
                    "key": "target_url",
                    "parameter_type": "workflow",
                    "workflow_parameter_type": "string",
                    "description": "URL to scrape",
                }
            ],
            "blocks": [
                {
                    "block_type": "task",
                    "label": "extract_data",
                    "prompt": "Extract the top 3 products",
                    "url": "{{ target_url }}",
                }
            ],
        },
    },
)
print(workflow.workflow_permanent_id)

const workflow = await skyvern.createWorkflow({
  body: {
    json_definition: {
      title: "Extract Products",
      workflow_definition: {
        parameters: [
          {
            key: "target_url",
            parameter_type: "workflow",
            workflow_parameter_type: "string",
            description: "URL to scrape",
          },
        ],
        blocks: [
          {
            block_type: "task",
            label: "extract",
            prompt: "Extract the top 3 products with name and price",
            url: "{{ target_url }}",
          },
        ],
      },
    },
  },
});
console.log(workflow.workflow_permanent_id);

Parameters

Parameter	Type	Required	Description
`json_definition`	`WorkflowCreateYamlRequest`	No	Workflow definition as a JSON object.
`yaml_definition`	`str`	No	Workflow definition as a YAML string.
`folder_id`	`str`	No	Folder to organize the workflow in.
`request_options`	`RequestOptions`	No	Per-request configuration (see below).

You must provide either json_definition or yaml_definition.

Returns `Workflow`

Field	Type	Description
`workflow_id`	`str`	Unique ID for this version.
`workflow_permanent_id`	`str`	Stable ID across all versions. Use this to run workflows.
`version`	`int`	Version number.
`title`	`str`	Workflow title.
`workflow_definition`	`WorkflowDefinition`	The full definition including blocks and parameters.
`status`	`str \| None`	Workflow status.
`created_at`	`datetime`	When the workflow was created.

Request options

Override timeout, retries, or headers for this call by passing request_options (Python) or a second options argument (TypeScript).

from skyvern.client.core import RequestOptions

request_options=RequestOptions(
    timeout_in_seconds=120,
    max_retries=3,
    additional_headers={"x-custom-header": "value"},
)

// Pass as second argument to any method
{
  timeoutInSeconds: 120,
  maxRetries: 3,
  headers: { "x-custom-header": "value" },
}

Option (Python)	Option (TypeScript)	Type	Description
`timeout_in_seconds`	`timeoutInSeconds`	`int` / `number`	HTTP timeout in seconds.
`max_retries`	`maxRetries`	`int` / `number`	Retry count.
`additional_headers`	`headers`	`dict` / `Record<string, string>`	Extra headers.
`additional_query_parameters`	-	`dict`	Extra query parameters.
`additional_body_parameters`	-	`dict`	Extra body parameters.
-	`abortSignal`	`AbortSignal`	Signal to cancel the request.
-	`apiKey`	`string`	Override API key.

SDK

Browser Automation

Tasks

Agents

Browser Sessions

Browser Profiles

Credentials

Helpers

create_workflow

Retry policy

Parameters

Returns `Workflow`

Request options

​Retry policy

​Parameters

​Returns Workflow

​Request options

Retry policy

Parameters

Returns `Workflow`

Request options