---
title: "Create Flow"
method: POST
path: "/flows"
tags: ["Flow"]
---

# Create Flow

`POST /flows`

Used to create new Flows

## Query parameters

- `branch` string

## Request body

- Flow — A Flow represents a set of steps in a Test
  - `id` string — Unique identifier
  - `created_by_id` string — The ID of the user who created this test
  - `last_updated_time` integer — Time the test was last updated in epoch milliseconds
  - `last_updated_by_id` string — The ID of the user who last updated this test
  - `created_time` integer — Time the test was created in epoch milliseconds
  - `revision_history` string — Serialized graph describing the test's version history. Managed by mabl API only.
  - `version_tags` object — Mapping of version tags to version numbers that the tag is currently applied to
  - `latest_version` integer — The latest numeric version of this test
  - `organization_id` string — (deprecated) The ID of the organization that this journey belongs to
  - `workspace_id` string — Workspace Id
  - `flow_type` 'validate_page' | 'login' | 'verify_url' | 'mablscript' | 'check_links' | 'visual_page_validation' | 'api' | 'mobile' — the type of flow
  - `reusable` boolean — Indicates whether this can be used by multiple tests
  - `name` string — The display name of the flow. Required (non-blank) for reusable flows. When absent on older reusable data, the API serves the description value here; non-reusable flows are never given a name they did not have.
  - `description` string — Usage notes and considerations for the flow. Historically this field held the flow's display name; that role has moved to `name`. To rename a flow, write `name` — writing this field edits the description only. When a flow has no description, the API serves the flow's name here for backwards compatibility.
  - `labels` Label[] — User provided labels
    - `name` string, required — name
    - `color` string — color
  - `source_control_tags` object — mapping of tags to version numbers the tag is currently applied to
  - `import_source_id` 'postman' | 'selenium_node_proxy' | 'selenium_java_agent'
  - `import_source_version` string — Version of the import tool used to import this flow
  - `mobile_platform` 'android' | 'ios' — The mobile platform associated with this object
  - `minimize_execution_overhead` boolean — When enabled, mabl will not capture screenshots, network logs, DOM snapshots, or other test artifacts in order to report the most accurate flow execution time
  - `reuse_browser_state_in_plan_run` boolean — Shares the browser state this flow produces with the rest of a cloud plan run. Tests that reach the flow before any state has been stored each run it and store their own result. The tests in a plan stage start together, so that is the common case; a test that starts once state already exists for the same application and credentials begins from that stored state instead. To sign in once per plan run, put a test that runs this flow in an earlier plan stage, against the same application URL and with the same credentials. Stages run in order, so the tests of later stages all start from the state that test stored. A marked flow still runs every time. It is not skipped, so it must decide for itself whether there is anything left to do — a login flow, for example, should wrap its sign-in steps in a condition that only holds when the login page is actually showing. A marked flow that unconditionally repeats its work will do so on a browser that already carries the session. The stored state lasts only for the plan run. Has no effect on local CLI runs.
  - `is_latest` boolean — Indicates whether this was the latest variant when retrieved
  - `version` integer — The generation number of this variant
  - `previous_version` integer — The generation number of the variant that was edited to create this variant (if applicable)
  - `merged_version` integer — The generation number of the variant that was merged with the previous version to create this variant (if applicable)
  - `merged_from_branch` string — Name of the source branch whose version was merged to create this variant (if applicable)
  - `created_on_branch` string — Branch name the test was created on
  - `change_description` string — Description of the change between this variant and the previous variant
  - `variant_last_updated_by_app_version` string — The version of the desktop app used to create this version.
  - `script` string — The flow's script
  - `script_description` string — Description of what the script does
  - `step_annotations` object — Step descriptions and notes keyed by the step index
  - `selectors` string[] — the selectors from mablscript
  - `file_references` FileReference[] — the file references from mablscript
    - `id` string, required — The ID of the uploaded file
    - `name` string — the base file name
    - `size` integer — the size of the file
    - `type` string — the type of the file, i.e., the extension
  - `flow_references` FlowReference[] — reusable flows referenced by steps in this flow
    - `invariantId` string, required — The ID of a referenced flow
    - `flowType` 'validate_page' | 'login' | 'verify_url' | 'mablscript' | 'check_links' | 'visual_page_validation' | 'api' | 'mobile' — the type of flow
    - `flow` Flow — recursive
  - `snippet_references` SnippetReference[] — this snippets referenced by this Flow
    - `id` string, required — The ID of the snippet invariant used
    - `snippetType` 'css' | 'javascript' | 'xpath' | 'sql' | 'postman'
  - `variables` UserDefinedVariables
    - `inputs` UserDefinedInputVariable[] — the input variables for the flow/test (used before they are defined) with set semantics on name
      - `name` string, required — the fully qualified symbol name of the variable
      - `default_value` string — the value to use when the variable is not otherwise defined
      - `value_type` 'string' | 'file' — The kind of value this variable carries. Absent implies `string` for backward compatibility; existing string variables are unaffected.
      - `file_value` FileValue — A typed file value for a file-typed variable, reconciling field-for-field with the runtime FileValue (mabl-cli mablscript-find). `origin` selects which reference is populated: `upload` uses file_upload_id, `download` uses download_ref. This one-of invariant is NOT enforced by the schema (a oneOf/discriminator would make the generated Java/TS clients polymorphic and diverge from the flat runtime FileValue); it must be enforced by validation on the Flow/Test write path, tracked in MABL-20387, before file variables are consumed (first reader: MABL-20718). Until then a malformed file_value is accepted but unused. The run-local localUri from the runtime shape is intentionally omitted (ephemeral, never persisted).
        - `origin` 'upload' | 'download', required — Provenance of the file. `upload` is a durable, reusable FileUpload (see file_upload_id). `download` is a transient file produced by a test run (see download_ref).
        - `name` string, required — the base file name
        - `mime_type` string, required — the true MIME type (e.g. application/pdf), not a file extension
        - `size` integer, required — the size of the file in bytes
        - `checksum` string — optional content checksum
        - `file_upload_id` string — Set when origin == upload; the id of a durable FileUpload (FileUpload.id). This is how a persisted or authored file variable references its file.
        - `download_ref` FileDownloadReference — Run-scoped coordinates locating a file downloaded during a test run. The backend derives the workspace from test_run_id and reconstructs the artifact location from object_key server-side; the bucket name is never stored here or returned to clients. Valid only within the producing run's artifact-retention window.
          - `id` string — stable logical handle for this downloaded file within the producing run
          - `test_run_id` string, required — the id of the test run that produced this download
          - `object_key` string, required — Bucket-relative storage key (e.g. execution-output/<nonce>/downloads/<run>/<step>/<name>). Excludes the bucket name; the backend prepends the workspace bucket at resolution time.
    - `outputs` UserDefinedOutputVariable[] — the variables defined by this script with set semantics. this is not used by the test.
      - `name` string, required — the fully qualified symbol name of the variable
  - `parameters` UserDefinedInputVariable[] — Configurable parameters mapping parameter name to a default value for that parameter
    - `name` string, required — the fully qualified symbol name of the variable
    - `default_value` string — the value to use when the variable is not otherwise defined
    - `value_type` 'string' | 'file' — The kind of value this variable carries. Absent implies `string` for backward compatibility; existing string variables are unaffected.
    - `file_value` FileValue — A typed file value for a file-typed variable, reconciling field-for-field with the runtime FileValue (mabl-cli mablscript-find). `origin` selects which reference is populated: `upload` uses file_upload_id, `download` uses download_ref. This one-of invariant is NOT enforced by the schema (a oneOf/discriminator would make the generated Java/TS clients polymorphic and diverge from the flat runtime FileValue); it must be enforced by validation on the Flow/Test write path, tracked in MABL-20387, before file variables are consumed (first reader: MABL-20718). Until then a malformed file_value is accepted but unused. The run-local localUri from the runtime shape is intentionally omitted (ephemeral, never persisted).
      - `origin` 'upload' | 'download', required — Provenance of the file. `upload` is a durable, reusable FileUpload (see file_upload_id). `download` is a transient file produced by a test run (see download_ref).
      - `name` string, required — the base file name
      - `mime_type` string, required — the true MIME type (e.g. application/pdf), not a file extension
      - `size` integer, required — the size of the file in bytes
      - `checksum` string — optional content checksum
      - `file_upload_id` string — Set when origin == upload; the id of a durable FileUpload (FileUpload.id). This is how a persisted or authored file variable references its file.
      - `download_ref` FileDownloadReference — Run-scoped coordinates locating a file downloaded during a test run. The backend derives the workspace from test_run_id and reconstructs the artifact location from object_key server-side; the bucket name is never stored here or returned to clients. Valid only within the producing run's artifact-retention window.
        - `id` string — stable logical handle for this downloaded file within the producing run
        - `test_run_id` string, required — the id of the test run that produced this download
        - `object_key` string, required — Bucket-relative storage key (e.g. execution-output/<nonce>/downloads/<run>/<step>/<name>). Excludes the bucket name; the backend prepends the workspace bucket at resolution time.
  - `step_features` StepFeature[] — Steps that are associated with specific features
    - `step_index` integer — Index of the step
    - `nested_step_index` integer[] — Array of indices representing the path to nested steps within StepGroups. Empty for top-level steps.
    - `feature_id` string — Id of the Feature is that is associated with this particular step.
  - `page_urls` string[] — URLs that should be visited for a visual page checker test
  - `api_steps` object — API steps for API only flow (stored in postman collection format)
  - `json_steps` object — Steps in the new json format that replaces mablscript
  - `mobile_training_info` MobileTrainingInfo
    - `device_name` string — The name of the mobile device
    - `device_api_level` string — The API level of the mobile device
    - `device_os_version` string — The OS version of the mobile device
    - `screen_dimensions` DeviceScreenDimensions
      - `height` integer, required — Height (pixels)
      - `width` integer, required — Width (pixels)
    - `is_cloud_training` boolean — Whether the training took place on a cloud device or local device
    - `is_real_device` boolean — Whether the training took place on a real device or an emulator/simulator
    - `app_file_name` string — The mobile app file name (only present for local training)
    - `app_file_id` string — The file id of the mobile app (only present for cloud training)
  - `created_by_app_version` string — The version of the desktop app used to create this version.
  - `url` string — the URL used when creating the flow
  - `agent_session_id` string — the id of the agent session that authored this flow version, if any
  - `variant_last_updated_time` integer — Time the variant was last updated
  - `variant_last_updated_by_id` string — ID of the user who last updated the variant
  - `cloud_safe_invariant_id` string — Cloud safe ID representation (e.g. GCP/email/Kubernetes safe)
  - `invariant_id` string — Object ID for the parent type. Set by system.

## Response `201`

The Flow that was created

- Flow — A Flow represents a set of steps in a Test
  - `id` string — Unique identifier
  - `created_by_id` string — The ID of the user who created this test
  - `last_updated_time` integer — Time the test was last updated in epoch milliseconds
  - `last_updated_by_id` string — The ID of the user who last updated this test
  - `created_time` integer — Time the test was created in epoch milliseconds
  - `revision_history` string — Serialized graph describing the test's version history. Managed by mabl API only.
  - `version_tags` object — Mapping of version tags to version numbers that the tag is currently applied to
  - `latest_version` integer — The latest numeric version of this test
  - `organization_id` string — (deprecated) The ID of the organization that this journey belongs to
  - `workspace_id` string — Workspace Id
  - `flow_type` 'validate_page' | 'login' | 'verify_url' | 'mablscript' | 'check_links' | 'visual_page_validation' | 'api' | 'mobile' — the type of flow
  - `reusable` boolean — Indicates whether this can be used by multiple tests
  - `name` string — The display name of the flow. Required (non-blank) for reusable flows. When absent on older reusable data, the API serves the description value here; non-reusable flows are never given a name they did not have.
  - `description` string — Usage notes and considerations for the flow. Historically this field held the flow's display name; that role has moved to `name`. To rename a flow, write `name` — writing this field edits the description only. When a flow has no description, the API serves the flow's name here for backwards compatibility.
  - `labels` Label[] — User provided labels
    - `name` string, required — name
    - `color` string — color
  - `source_control_tags` object — mapping of tags to version numbers the tag is currently applied to
  - `import_source_id` 'postman' | 'selenium_node_proxy' | 'selenium_java_agent'
  - `import_source_version` string — Version of the import tool used to import this flow
  - `mobile_platform` 'android' | 'ios' — The mobile platform associated with this object
  - `minimize_execution_overhead` boolean — When enabled, mabl will not capture screenshots, network logs, DOM snapshots, or other test artifacts in order to report the most accurate flow execution time
  - `reuse_browser_state_in_plan_run` boolean — Shares the browser state this flow produces with the rest of a cloud plan run. Tests that reach the flow before any state has been stored each run it and store their own result. The tests in a plan stage start together, so that is the common case; a test that starts once state already exists for the same application and credentials begins from that stored state instead. To sign in once per plan run, put a test that runs this flow in an earlier plan stage, against the same application URL and with the same credentials. Stages run in order, so the tests of later stages all start from the state that test stored. A marked flow still runs every time. It is not skipped, so it must decide for itself whether there is anything left to do — a login flow, for example, should wrap its sign-in steps in a condition that only holds when the login page is actually showing. A marked flow that unconditionally repeats its work will do so on a browser that already carries the session. The stored state lasts only for the plan run. Has no effect on local CLI runs.
  - `is_latest` boolean — Indicates whether this was the latest variant when retrieved
  - `version` integer — The generation number of this variant
  - `previous_version` integer — The generation number of the variant that was edited to create this variant (if applicable)
  - `merged_version` integer — The generation number of the variant that was merged with the previous version to create this variant (if applicable)
  - `merged_from_branch` string — Name of the source branch whose version was merged to create this variant (if applicable)
  - `created_on_branch` string — Branch name the test was created on
  - `change_description` string — Description of the change between this variant and the previous variant
  - `variant_last_updated_by_app_version` string — The version of the desktop app used to create this version.
  - `script` string — The flow's script
  - `script_description` string — Description of what the script does
  - `step_annotations` object — Step descriptions and notes keyed by the step index
  - `selectors` string[] — the selectors from mablscript
  - `file_references` FileReference[] — the file references from mablscript
    - `id` string, required — The ID of the uploaded file
    - `name` string — the base file name
    - `size` integer — the size of the file
    - `type` string — the type of the file, i.e., the extension
  - `flow_references` FlowReference[] — reusable flows referenced by steps in this flow
    - `invariantId` string, required — The ID of a referenced flow
    - `flowType` 'validate_page' | 'login' | 'verify_url' | 'mablscript' | 'check_links' | 'visual_page_validation' | 'api' | 'mobile' — the type of flow
    - `flow` Flow — recursive
  - `snippet_references` SnippetReference[] — this snippets referenced by this Flow
    - `id` string, required — The ID of the snippet invariant used
    - `snippetType` 'css' | 'javascript' | 'xpath' | 'sql' | 'postman'
  - `variables` UserDefinedVariables
    - `inputs` UserDefinedInputVariable[] — the input variables for the flow/test (used before they are defined) with set semantics on name
      - `name` string, required — the fully qualified symbol name of the variable
      - `default_value` string — the value to use when the variable is not otherwise defined
      - `value_type` 'string' | 'file' — The kind of value this variable carries. Absent implies `string` for backward compatibility; existing string variables are unaffected.
      - `file_value` FileValue — A typed file value for a file-typed variable, reconciling field-for-field with the runtime FileValue (mabl-cli mablscript-find). `origin` selects which reference is populated: `upload` uses file_upload_id, `download` uses download_ref. This one-of invariant is NOT enforced by the schema (a oneOf/discriminator would make the generated Java/TS clients polymorphic and diverge from the flat runtime FileValue); it must be enforced by validation on the Flow/Test write path, tracked in MABL-20387, before file variables are consumed (first reader: MABL-20718). Until then a malformed file_value is accepted but unused. The run-local localUri from the runtime shape is intentionally omitted (ephemeral, never persisted).
        - `origin` 'upload' | 'download', required — Provenance of the file. `upload` is a durable, reusable FileUpload (see file_upload_id). `download` is a transient file produced by a test run (see download_ref).
        - `name` string, required — the base file name
        - `mime_type` string, required — the true MIME type (e.g. application/pdf), not a file extension
        - `size` integer, required — the size of the file in bytes
        - `checksum` string — optional content checksum
        - `file_upload_id` string — Set when origin == upload; the id of a durable FileUpload (FileUpload.id). This is how a persisted or authored file variable references its file.
        - `download_ref` FileDownloadReference — Run-scoped coordinates locating a file downloaded during a test run. The backend derives the workspace from test_run_id and reconstructs the artifact location from object_key server-side; the bucket name is never stored here or returned to clients. Valid only within the producing run's artifact-retention window.
          - `id` string — stable logical handle for this downloaded file within the producing run
          - `test_run_id` string, required — the id of the test run that produced this download
          - `object_key` string, required — Bucket-relative storage key (e.g. execution-output/<nonce>/downloads/<run>/<step>/<name>). Excludes the bucket name; the backend prepends the workspace bucket at resolution time.
    - `outputs` UserDefinedOutputVariable[] — the variables defined by this script with set semantics. this is not used by the test.
      - `name` string, required — the fully qualified symbol name of the variable
  - `parameters` UserDefinedInputVariable[] — Configurable parameters mapping parameter name to a default value for that parameter
    - `name` string, required — the fully qualified symbol name of the variable
    - `default_value` string — the value to use when the variable is not otherwise defined
    - `value_type` 'string' | 'file' — The kind of value this variable carries. Absent implies `string` for backward compatibility; existing string variables are unaffected.
    - `file_value` FileValue — A typed file value for a file-typed variable, reconciling field-for-field with the runtime FileValue (mabl-cli mablscript-find). `origin` selects which reference is populated: `upload` uses file_upload_id, `download` uses download_ref. This one-of invariant is NOT enforced by the schema (a oneOf/discriminator would make the generated Java/TS clients polymorphic and diverge from the flat runtime FileValue); it must be enforced by validation on the Flow/Test write path, tracked in MABL-20387, before file variables are consumed (first reader: MABL-20718). Until then a malformed file_value is accepted but unused. The run-local localUri from the runtime shape is intentionally omitted (ephemeral, never persisted).
      - `origin` 'upload' | 'download', required — Provenance of the file. `upload` is a durable, reusable FileUpload (see file_upload_id). `download` is a transient file produced by a test run (see download_ref).
      - `name` string, required — the base file name
      - `mime_type` string, required — the true MIME type (e.g. application/pdf), not a file extension
      - `size` integer, required — the size of the file in bytes
      - `checksum` string — optional content checksum
      - `file_upload_id` string — Set when origin == upload; the id of a durable FileUpload (FileUpload.id). This is how a persisted or authored file variable references its file.
      - `download_ref` FileDownloadReference — Run-scoped coordinates locating a file downloaded during a test run. The backend derives the workspace from test_run_id and reconstructs the artifact location from object_key server-side; the bucket name is never stored here or returned to clients. Valid only within the producing run's artifact-retention window.
        - `id` string — stable logical handle for this downloaded file within the producing run
        - `test_run_id` string, required — the id of the test run that produced this download
        - `object_key` string, required — Bucket-relative storage key (e.g. execution-output/<nonce>/downloads/<run>/<step>/<name>). Excludes the bucket name; the backend prepends the workspace bucket at resolution time.
  - `step_features` StepFeature[] — Steps that are associated with specific features
    - `step_index` integer — Index of the step
    - `nested_step_index` integer[] — Array of indices representing the path to nested steps within StepGroups. Empty for top-level steps.
    - `feature_id` string — Id of the Feature is that is associated with this particular step.
  - `page_urls` string[] — URLs that should be visited for a visual page checker test
  - `api_steps` object — API steps for API only flow (stored in postman collection format)
  - `json_steps` object — Steps in the new json format that replaces mablscript
  - `mobile_training_info` MobileTrainingInfo
    - `device_name` string — The name of the mobile device
    - `device_api_level` string — The API level of the mobile device
    - `device_os_version` string — The OS version of the mobile device
    - `screen_dimensions` DeviceScreenDimensions
      - `height` integer, required — Height (pixels)
      - `width` integer, required — Width (pixels)
    - `is_cloud_training` boolean — Whether the training took place on a cloud device or local device
    - `is_real_device` boolean — Whether the training took place on a real device or an emulator/simulator
    - `app_file_name` string — The mobile app file name (only present for local training)
    - `app_file_id` string — The file id of the mobile app (only present for cloud training)
  - `created_by_app_version` string — The version of the desktop app used to create this version.
  - `url` string — the URL used when creating the flow
  - `agent_session_id` string — the id of the agent session that authored this flow version, if any
  - `variant_last_updated_time` integer — Time the variant was last updated
  - `variant_last_updated_by_id` string — ID of the user who last updated the variant
  - `cloud_safe_invariant_id` string — Cloud safe ID representation (e.g. GCP/email/Kubernetes safe)
  - `invariant_id` string — Object ID for the parent type. Set by system.

## Other responses

- `400` — Invalid or missing parameter
- `401` — User not authenticated
- `403` — User not authorized
- `default` — Unknown error

---

[API](https://skmtc.dev/mabl/apis/mabl-api.md) · [All operations](https://skmtc.dev/mabl/apis/mabl-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/mabl/mabl-api/revisions/213a66c2bc25/schema)