---
title: "Batch update and create flows"
method: PUT
path: "/flows"
tags: ["Flow"]
---

# Batch update and create flows

`PUT /flows`

Supports updating and creating a batch of flows, such as those associated with a single test

## Query parameters

- `branch` string
- `force` boolean

## Request body

- FlowUpdate — A container for a set of flow updates
  - `flows` FlowUpdateFlows[]
    - `update_type` 'create' | 'update'
    - `e_tag` string — ETag value according to http/1.1 spec section 14.19. If used in the request body this will be treated as a If-Match header according to section 14.24
    - `flow` 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
      - `description` string — Summary of the flow
      - `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
      - `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.
              - …
        - `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.
    - `tracking_id` string — A tracking id for a given flow update or create. If set, the api will respond with the same id in the response for this flow. Used for tracking creates where there is no initial flow id.

## Response `200`

The updated test and flows

- FlowUpdate — A container for a set of flow updates
  - `flows` FlowUpdateFlows[]
    - `update_type` 'create' | 'update'
    - `e_tag` string — ETag value according to http/1.1 spec section 14.19. If used in the request body this will be treated as a If-Match header according to section 14.24
    - `flow` 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
      - `description` string — Summary of the flow
      - `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
      - `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.
              - …
        - `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.
    - `tracking_id` string — A tracking id for a given flow update or create. If set, the api will respond with the same id in the response for this flow. Used for tracking creates where there is no initial flow id.

## Other responses

- `400` — Bad Request
- `default` — Unknown error

---

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