---
title: "Add Labels to Tests"
method: PATCH
path: "/test/journeys/addLabels"
tags: ["Test"]
---

# Add Labels to Tests

`PATCH /test/journeys/addLabels`

Update tests to contain new labels

## Query parameters

- `ids` string[], required

## Request body

- Label[]
  - `name` string, required — name
  - `color` string — color

## Response `200`

Array of updated tests

- TestQueryResult — result envelope for test query results
  - `journeys` Test[] — All tess that matched the query
    - `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
    - `enabled` boolean — If test is enabled to execute
    - `name` string — The display name of the test
    - `description` string — Brief description the test
    - `device_emulation` DeviceEmulation — Emulation configuration
      - `device_config` DeviceEmulationConfiguration, required — Emulation configuration
        - `name` string, required — Emulation configuration display name
        - `preset_type` 'blackberry_playbook' | 'blackberry_z30' | 'galaxy_fold' | 'galaxy_note_3' | 'galaxy_note_ii' | 'galaxy_s5' | 'galaxy_s6' | 'galaxy_s8' | 'galaxy_s21' | 'galaxy_s22' | 'galaxy_s23' | 'galaxy_s_iii' | 'galaxy_tab_s7' | 'ipad' | 'ipad_air_2020' | 'ipad_mini' | 'ipad_mini_4' | 'ipad_pro' | 'ipad_ten_point_two' | 'iphone_11_pro_max' | 'iphone_11' | 'iphone_12' | 'iphone_12_pro_max' | 'iphone_13_mini' | 'iphone_13' | 'iphone_13_pro' | 'iphone_13_pro_max' | 'iphone_14' | 'iphone_14_pro' | 'iphone_14_plus' | 'iphone_14_pro_max' | 'iphone_15' | 'iphone_15_plus' | 'iphone_15_pro' | 'iphone_15_pro_max' | 'iphone_4' | 'iphone_5_se' | 'iphone_6_7_8' | 'iphone_6_7_8_plus' | 'iphone_x' | 'jiophone_2' | 'kindle_fire_hdx' | 'laptop_with_hidpi_screen' | 'laptop_with_mdpi_screen' | 'laptop_with_touch' | 'lg_optimus_l70' | 'microsoft_lumia_550' | 'microsoft_lumia_950' | 'moto_g4' | 'nexus_4' | 'nexus_5' | 'nexus_5x' | 'nexus_6' | 'nexus_6p' | 'nexus_7' | 'nexus_10' | 'nokia_lumia_520' | 'nokia_n9' | 'pixel_2' | 'pixel_2_xl' | 'pixel_6' | 'surface_duo' — Preset device configuration (optional)
        - `user_agent` string — Client User Agent string
        - `type` 'phone' | 'tablet' | 'notebook' — General device type
        - `capabilities` string[] — Optional device capabilities
        - `screen` object — Screen configuration
          - `device_pixel_ratio` number, double — Device pixel ratio (may be decimal)
          - `horizontal` DeviceScreenDimensions
            - `height` integer, required — Height (pixels)
            - `width` integer, required — Width (pixels)
          - `vertical` DeviceScreenDimensions
            - `height` integer, required — Height (pixels)
            - `width` integer, required — Width (pixels)
      - `orientation` 'portrait_primary' | 'portrait_secondary' | 'landscape_primary' | 'landscape_secondary', required — Fixed device orientation
    - `device_emulations` DeviceEmulation[] — List of browser device emulation configurations. Empty list means configured for desktop
      - `device_config` DeviceEmulationConfiguration, required — Emulation configuration
        - `name` string, required — Emulation configuration display name
        - `preset_type` 'blackberry_playbook' | 'blackberry_z30' | 'galaxy_fold' | 'galaxy_note_3' | 'galaxy_note_ii' | 'galaxy_s5' | 'galaxy_s6' | 'galaxy_s8' | 'galaxy_s21' | 'galaxy_s22' | 'galaxy_s23' | 'galaxy_s_iii' | 'galaxy_tab_s7' | 'ipad' | 'ipad_air_2020' | 'ipad_mini' | 'ipad_mini_4' | 'ipad_pro' | 'ipad_ten_point_two' | 'iphone_11_pro_max' | 'iphone_11' | 'iphone_12' | 'iphone_12_pro_max' | 'iphone_13_mini' | 'iphone_13' | 'iphone_13_pro' | 'iphone_13_pro_max' | 'iphone_14' | 'iphone_14_pro' | 'iphone_14_plus' | 'iphone_14_pro_max' | 'iphone_15' | 'iphone_15_plus' | 'iphone_15_pro' | 'iphone_15_pro_max' | 'iphone_4' | 'iphone_5_se' | 'iphone_6_7_8' | 'iphone_6_7_8_plus' | 'iphone_x' | 'jiophone_2' | 'kindle_fire_hdx' | 'laptop_with_hidpi_screen' | 'laptop_with_mdpi_screen' | 'laptop_with_touch' | 'lg_optimus_l70' | 'microsoft_lumia_550' | 'microsoft_lumia_950' | 'moto_g4' | 'nexus_4' | 'nexus_5' | 'nexus_5x' | 'nexus_6' | 'nexus_6p' | 'nexus_7' | 'nexus_10' | 'nokia_lumia_520' | 'nokia_n9' | 'pixel_2' | 'pixel_2_xl' | 'pixel_6' | 'surface_duo' — Preset device configuration (optional)
        - `user_agent` string — Client User Agent string
        - `type` 'phone' | 'tablet' | 'notebook' — General device type
        - `capabilities` string[] — Optional device capabilities
        - `screen` object — Screen configuration
          - `device_pixel_ratio` number, double — Device pixel ratio (may be decimal)
          - `horizontal` DeviceScreenDimensions
            - `height` integer, required — Height (pixels)
            - `width` integer, required — Width (pixels)
          - `vertical` DeviceScreenDimensions
            - `height` integer, required — Height (pixels)
            - `width` integer, required — Width (pixels)
      - `orientation` 'portrait_primary' | 'portrait_secondary' | 'landscape_primary' | 'landscape_secondary', required — Fixed device orientation
    - `tags` Tag[] — Tag objects associated with this test
      - `name` string, required — tag name
      - `values` string[]
    - `default` boolean — Whether this test is a default test generated for all customers from a template
    - `labels` Label[] — User provided labels
      - `name` string, required — name
      - `color` string — color
    - `datatables` string[] — Array of datatable IDs for datatables that satisfy the parameter requirements of the test
    - `export_variables` boolean — Whether this test should export variables
    - `source_control_tags` object — (deprecated, use versionTags) mapping of source control tags to version numbers the tag is currently applied to
    - `ref_id` string — Reference id to this test in another system
    - `test_type` 'api' | 'browser' | 'performance' | 'mobile' — Type of test
    - `test_source` 'mabl_cloud' | 'external' | 'mabl_local' | 'mabl_agent' — Where the test lives
    - `test_cases` ExternalTestCase[] — User provided external test cases (limit 20)
      - `id` string — Id associated with this test case
    - `send_mabl_header` boolean — Controls whether or not the x-mabl-agent header is sent on requests
    - `execution_runner_size` 'x1' | 'x2' | 'x3' | 'x4' | 'x5' | 'x6' | 'small' | 'medium' | 'large' | 'inherit' — available runner sizes
    - `mobile_platform` 'android' | 'ios' — The mobile platform associated with this object
    - `intent` string — The intent of the test as natural language
    - `test_case_id` string — Unique identifier of the associated TestCase
    - `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
    - `manual_steps` string — Test steps outline, used for manual tests
    - `flows` string[] — Array of flow IDs for flows to execute during test
    - `flow_configuration` object — Configuration for specific flow instances
    - `iterations` object — Iteration configurations keyed by flow index (as string)
    - `performance_configuration` PerformanceConfiguration — Configuration of the performance test type.
      - `runtime` object — Overall duration of the performance test.
        - `duration_mins` integer — Test duration in minutes
        - `ramp_up_seconds` integer — Test ramp up time in seconds
      - `workloads` WorkloadConfiguration[] — Workloads included in this performance test
        - `test_invariant_id` string — The invariant id of the test (tes) used to generate the workload
        - `test_variant_id` string — The variant id of the test (tes) used to generate the workload. Only populated in test runs and can be found in TestRun.tes.performance_configuration.workloads. It is never populated in Test.performance_configuration.workloads.
        - `concurrency` integer — Number of threads/users to use for this test
        - `failure_criteria` PerformanceFailureCriteria[] — The failure criteria associated with this workload
          - `metric_comparator` 'greater_than' | 'less_than' — The comparator determining the failure case
          - `metric_threshold` number, double — The cutoff value determining the failure case
          - `metric_type` 'response_time' | 'http_error_rate' | 'functional_test_failure_rate' | 'core_web_vitals' | 'step_duration' — The type of metric determining failure case
          - `metric_optional_parameters` PerformanceFailureCriteriaOptionalParameters — Optional parameters related to specific failure criteria
            - `metric_aggregation` 'average' | 'percentile' — The aggregation level of the metric determining failure case
            - `metric_percentile` integer — The percentile for the metric we are considering
            - `metric_error_codes` string[] — Response codes that count as errors for error rate
            - `metric_step_ids` string[] — IDs of steps to include in metric calculations
            - `metric_cwv_measurements` PerformanceFailureCriteriaCWVMeasurement[] — Individual CWV measurements' failure criteria configuration
              - …
        - `failure_criteria_evaluate` 'any' | 'all' — How to combine failure criteria
        - `datatables` string[] — IDs of data tables to be used for this workload
        - `credentials_id` string — Optional ID of the credentials object to use with this test
        - `http_auth_credentials_id` string — Optional ID of credentials to pass in the HTTP request (as opposed to interactive login credentials)
    - `api_url` string — the API URL associated with the test
    - `api_configuration` ApiConfiguration — Configuration of the API test type.
      - `authentication` ApiAuthentication — Configuration for API authentication
        - `type` 'apikey' | 'basic' | 'bearer' | 'noauth' | 'oauth1' | 'oauth2', required — The authentication type to use
        - `api_key` ApiKeyAuthentication — Configuration for API key authentication
          - `location` 'header' | 'query' — The location of the API key
          - `key` string — The key to use for authentication
          - `value` string — The value to use for authentication
        - `basic` BasicAuthentication — Configuration for basic authentication
          - `username` string — The username to use for authentication
          - `password` string — The password to use for authentication
        - `bearer` BearerAuthentication — Configuration for bearer authentication
          - `token` string — The token to use for authentication
        - `oauth1` OAuth1Authentication — Configuration for OAuth 1.0 authentication
          - `add_parameters_to_header` boolean
          - `add_empty_parameters_to_signature` boolean
          - `callback_url` string
          - `consumer_key` string
          - `consumer_secret` string
          - `include_body_hash` boolean
          - `nonce` string
          - `realm` string
          - `signature_method` 'HMAC-SHA1' | 'HMAC-SHA256' | 'HMAC-SHA512' | 'RSA-SHA1' | 'RSA-SHA256' | 'RSA-SHA512' | 'PLAINTEXT'
          - `timestamp` string
          - `token` string
          - `token_secret` string
          - `verifier` string
          - `version` string
        - `oauth2` OAuth2Authentication — Configuration for OAuth 2.0 authentication
          - `access_token_url` string, required
          - `client_credentials_location` 'basic_auth_header' | 'body', required
          - `client_id` string, required
          - `client_secret` string, required
          - `grant_type` 'client_credentials', required
          - `scope` string
          - `token_variable` string, required — The OAuth token will be stored to this variable
      - `pre_request_snippets` ExecutableSnippet[] — Snippets to execute before the request
        - `invariant_id` string — Object ID for the parent type. Set by system.
        - `description` string — Summary of the Snippet
        - `name` string — The display name of the Snippet
        - `body` string — the base64 encoded body of the Snippet
        - `snippet_type` 'css' | 'javascript' | 'xpath' | 'sql' | 'postman'
        - `reusable` boolean — Indicates whether the snippet is reusable
        - `workspace_id` string — The ID of the workspace that this Snippet belongs to
      - `post_request_snippets` ExecutableSnippet[] — Snippets to execute after the request
        - `invariant_id` string — Object ID for the parent type. Set by system.
        - `description` string — Summary of the Snippet
        - `name` string — The display name of the Snippet
        - `body` string — the base64 encoded body of the Snippet
        - `snippet_type` 'css' | 'javascript' | 'xpath' | 'sql' | 'postman'
        - `reusable` boolean — Indicates whether the snippet is reusable
        - `workspace_id` string — The ID of the workspace that this Snippet belongs to
    - `url` string — the URL used when creating the test version
    - `credentials_id` string — the id of the credentials used when creating the test version
    - `application_id` string — the id of the application used when creating the test version
    - `environment_id` string — the id of the environment used when creating the test version
    - `datatable_row_id` string — the id of the DataTable row used when creating the test version
    - `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
    - `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)
    - `training_session_id` string — the id of the training session used when creating the test version
    - `agent_session_id` string — the id of the agent session that authored this test 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.
  - `cursor` string — Cursor used for pagination

## Other responses

- `400` — Invalid or missing parameter
- `401` — User not authenticated
- `403` — User not authorized
- `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)