--- title: "Add a recording example" method: POST path: "/api/v1/add_example" tags: ["add_example"] --- # Add a recording example `POST /api/v1/add_example` Creates a new recording/automation example under the authenticated user. ## Headers - `x-api-key` string, required ## Request body - BodyAddExampleApiV1AddExamplePost - `automation` Automation, required - `browser_channel` 'chromium' | 'chrome' | 'cloakbrowser' | 'browser-use' | 'rdp' - `backend` 'browser-use' | 'computer-vision' - `os_emulation` 'windows' | 'linux', nullable - `allow_cookies` boolean - `max_retries` integer - `expected_downloads` integer - `remove_empty_nodes_in_axtree` boolean - `url` string, required - `reuse_page_if_already_on_url` boolean - `take_final_screenshot` boolean - `parameters` Parameters, required - `input_parameters` object, required - `secure_parameters` object - `generated_parameters` object, required - `nodes` union[], required - union - ActionNode - `type` 'action_node', required - `interaction_action` InteractionAction — unresolved $ref - `assertion_action` AssertionAction - `network_call` NetworkCallAssertion - … - `llm` LLMAssertion - … - `python_script` PythonScriptAssertion - … - `extraction_action` ExtractionAction - `unique_identifier` string, nullable - `allow_none` boolean - `network_call` NetworkCallExtraction - … - `llm` LLMExtraction - … - `python_script` PythonScriptExtraction - … - `screenshot` ScreenshotExtraction - … - `state` StateExtraction - `two_fa_action` TwoFAAction - … - `pdf` PDFExtraction - … - `ocr_coordinates` OCRCoordinatesExtraction - … - `locator` LocatorExtraction - … - `vision` VisionExtraction - … - `api_call` APICallExtraction - … - `python_script_action` PythonScriptAction - `execution_code` string, required - `powershell_action` PowerShellAction — Run a list of PowerShell commands on the current RDP Windows machine. Opens PowerShell via Win+R, executes all commands sequentially, and closes the session (sends 'exit' automatically). - `commands` string[], required - `exit_after_commands` boolean - `sleep_action` SleepAction - `sleep_time` number, required - `fail_state_action` FailStateAction - `failure_message` string - `captcha_action` CaptchaAction - `locator` string, required - `secondary_locator` string, nullable - `wait_time` number - `llm_provider` string, nullable - `llm_model_name` string - `config` object - `misc_action` MiscAction — Container for miscellaneous actions (set_variable, llm_query, etc.). Exactly one sub-action must be provided. - `set_variable` SetVariableAction — Set a value in generated_variables. Use `value` for a static value, or `expression` for a computed value (evaluated after variable replacement, e.g. "{counter[0]} + 1"). When `output_variable_name` is set, the value is also appended to ``output_data`` under that key. - … - `llm_query` LLMQueryAction - … - `count_locator` CountLocatorAction — Count how many elements a Playwright locator matches on the current page. The integer count is stored in generated_variables under `name` as a single-element list (same wrapping as set_variable). When `output_variable_name` is set, the count is also appended to ``output_data`` under that key. - … - `human_in_loop_action` HumanInLoopAction - `max_wait_time` number, required - `dynamic_form_mapping_action` DynamicFormMappingAction — Extract form field keys from the current page, POST them to a customer endpoint, and store the returned mapping for later nodes (typically ``agentic_task``). - `llm_provider` string, nullable - `llm_model_name` string, nullable - `extraction_instructions` string, required - `extraction_format` object, required - `source` string[] - `callback_url` FormMappingCallbackUrl, required - … - `include_screenshot` boolean - `full_page_screenshot` boolean - `include_axtree` boolean - `include_live_stream_url` boolean - `max_wait_time` number - `output_variable_name` string - `before_sleep_time` number - `end_sleep_time` number - `expect_new_tab` boolean - `max_new_tab_wait_time` number - `localized_axtree_string` string, nullable - ForLoopNode - `type` 'for_loop_node', required - `variable_name` string, nullable — Name of the list variable to iterate over; its length is the iteration count. Comma-separated names iterate in parallel, with the first one setting the length. Reference values in the loop body as {variable_name[]}. Mutually exclusive with locator: exactly one of the two must be set. - `locator` string, nullable — Playwright locator command evaluated against `page` (same grammar as assert_locator_node.locator), e.g. 'get_by_role("row")'. The number of matched elements is the iteration count, so use this to loop over rows/items whose count is not known when authoring. Reference the current match in the loop body as {locator[]}, which expands to .nth() and can be chained: '{locator[row]}.locator("td.NameCell")'. Mutually exclusive with variable_name: exactly one of the two must be set. - `index_variable_name` string — Placeholder name bound to the current iteration's number, used as {var[]} / {locator[]} and bare {}. Defaults to "index" for backward compatibility. Use distinct names when nesting loops so the outer index remains addressable inside the inner loop. Must not be 'index_of', must not be 'locator' in locator mode, and must not match a name listed in variable_name. - `locator_timeout` number — Locator loops only: seconds to wait for the first match to attach before counting (Playwright's count() does not auto-wait, so without this a table that renders asynchronously counts as empty and the loop body never runs). After the first match, the runtime also waits until the match count stays unchanged for 1s so rows that stream in shortly after the first paint are included. A locator that never attaches yields zero iterations (with a warning) rather than an error, so an empty result table is handled without failing the run. - `max_iterations` integer, nullable — Cap on the number of iterations; extra items are skipped with a warning. Null means iterate over everything the source provides. - `nodes` union[], required - union - … - `reset_nodes` union[] - union - … - `on_error_in_loop` 'continue' | 'break' | 'raise' - IfElseNode - `type` 'if_else_node', required - `condition` string, required - `if_nodes` union[], required - union - … - `else_nodes` union[] - union - … - AssertLocatorNode — Evaluate a Playwright locator assertion and store the boolean result. The locator is evaluated against `page` via Browser.get_locator_from_command (same `eval("page." + command)` style used by interaction actions). If the assertion holds within `timeout` seconds the result is True, otherwise False. The boolean is stored in generated_variables under `output_variable_name` (as a single-element list, e.g. {output_variable_name: [True]}) so it can be referenced later via `{output_variable_name[0]}`, e.g. in an if_else_node condition. When `output_variable_name` is omitted, the result is stored under `node{index}_output`, where index is the node's step index resolved at runtime. - `type` 'assert_locator_node', required - `locator` string, required - `assertion` 'to_be_visible' | 'to_be_hidden', required - `output_variable_name` string, nullable - `timeout` number - PrivateNode — Calls a handler contributed by an installed plugin package. ``handler`` and ``inputs`` are deliberately untyped here: the public schema cannot know what a closed-source distribution provides, so the registry resolves the name and the handler's own model validates the inputs at execution time. See ``optexity.private_nodes``. - `type` 'private_node', required - `handler` string, required - `inputs` object - `output_variable_names` string[], nullable - `before_sleep_time` number - `end_sleep_time` number - `automation_description` string, nullable - `automation_endpoint` string, nullable - `post_processing_nodes` union[] - union - ActionNode - `type` 'action_node', required - `interaction_action` InteractionAction — unresolved $ref - `assertion_action` AssertionAction - `network_call` NetworkCallAssertion - … - `llm` LLMAssertion - … - `python_script` PythonScriptAssertion - … - `extraction_action` ExtractionAction - `unique_identifier` string, nullable - `allow_none` boolean - `network_call` NetworkCallExtraction - … - `llm` LLMExtraction - … - `python_script` PythonScriptExtraction - … - `screenshot` ScreenshotExtraction - … - `state` StateExtraction - `two_fa_action` TwoFAAction - … - `pdf` PDFExtraction - … - `ocr_coordinates` OCRCoordinatesExtraction - … - `locator` LocatorExtraction - … - `vision` VisionExtraction - … - `api_call` APICallExtraction - … - `python_script_action` PythonScriptAction - `execution_code` string, required - `powershell_action` PowerShellAction — Run a list of PowerShell commands on the current RDP Windows machine. Opens PowerShell via Win+R, executes all commands sequentially, and closes the session (sends 'exit' automatically). - `commands` string[], required - `exit_after_commands` boolean - `sleep_action` SleepAction - `sleep_time` number, required - `fail_state_action` FailStateAction - `failure_message` string - `captcha_action` CaptchaAction - `locator` string, required - `secondary_locator` string, nullable - `wait_time` number - `llm_provider` string, nullable - `llm_model_name` string - `config` object - `misc_action` MiscAction — Container for miscellaneous actions (set_variable, llm_query, etc.). Exactly one sub-action must be provided. - `set_variable` SetVariableAction — Set a value in generated_variables. Use `value` for a static value, or `expression` for a computed value (evaluated after variable replacement, e.g. "{counter[0]} + 1"). When `output_variable_name` is set, the value is also appended to ``output_data`` under that key. - … - `llm_query` LLMQueryAction - … - `count_locator` CountLocatorAction — Count how many elements a Playwright locator matches on the current page. The integer count is stored in generated_variables under `name` as a single-element list (same wrapping as set_variable). When `output_variable_name` is set, the count is also appended to ``output_data`` under that key. - … - `human_in_loop_action` HumanInLoopAction - `max_wait_time` number, required - `dynamic_form_mapping_action` DynamicFormMappingAction — Extract form field keys from the current page, POST them to a customer endpoint, and store the returned mapping for later nodes (typically ``agentic_task``). - `llm_provider` string, nullable - `llm_model_name` string, nullable - `extraction_instructions` string, required - `extraction_format` object, required - `source` string[] - `callback_url` FormMappingCallbackUrl, required - … - `include_screenshot` boolean - `full_page_screenshot` boolean - `include_axtree` boolean - `include_live_stream_url` boolean - `max_wait_time` number - `output_variable_name` string - `before_sleep_time` number - `end_sleep_time` number - `expect_new_tab` boolean - `max_new_tab_wait_time` number - `localized_axtree_string` string, nullable - ForLoopNode - `type` 'for_loop_node', required - `variable_name` string, nullable — Name of the list variable to iterate over; its length is the iteration count. Comma-separated names iterate in parallel, with the first one setting the length. Reference values in the loop body as {variable_name[]}. Mutually exclusive with locator: exactly one of the two must be set. - `locator` string, nullable — Playwright locator command evaluated against `page` (same grammar as assert_locator_node.locator), e.g. 'get_by_role("row")'. The number of matched elements is the iteration count, so use this to loop over rows/items whose count is not known when authoring. Reference the current match in the loop body as {locator[]}, which expands to .nth() and can be chained: '{locator[row]}.locator("td.NameCell")'. Mutually exclusive with variable_name: exactly one of the two must be set. - `index_variable_name` string — Placeholder name bound to the current iteration's number, used as {var[]} / {locator[]} and bare {}. Defaults to "index" for backward compatibility. Use distinct names when nesting loops so the outer index remains addressable inside the inner loop. Must not be 'index_of', must not be 'locator' in locator mode, and must not match a name listed in variable_name. - `locator_timeout` number — Locator loops only: seconds to wait for the first match to attach before counting (Playwright's count() does not auto-wait, so without this a table that renders asynchronously counts as empty and the loop body never runs). After the first match, the runtime also waits until the match count stays unchanged for 1s so rows that stream in shortly after the first paint are included. A locator that never attaches yields zero iterations (with a warning) rather than an error, so an empty result table is handled without failing the run. - `max_iterations` integer, nullable — Cap on the number of iterations; extra items are skipped with a warning. Null means iterate over everything the source provides. - `nodes` union[], required - union - … - `reset_nodes` union[] - union - … - `on_error_in_loop` 'continue' | 'break' | 'raise' - IfElseNode - `type` 'if_else_node', required - `condition` string, required - `if_nodes` union[], required - union - … - `else_nodes` union[] - union - … - AssertLocatorNode — Evaluate a Playwright locator assertion and store the boolean result. The locator is evaluated against `page` via Browser.get_locator_from_command (same `eval("page." + command)` style used by interaction actions). If the assertion holds within `timeout` seconds the result is True, otherwise False. The boolean is stored in generated_variables under `output_variable_name` (as a single-element list, e.g. {output_variable_name: [True]}) so it can be referenced later via `{output_variable_name[0]}`, e.g. in an if_else_node condition. When `output_variable_name` is omitted, the result is stored under `node{index}_output`, where index is the node's step index resolved at runtime. - `type` 'assert_locator_node', required - `locator` string, required - `assertion` 'to_be_visible' | 'to_be_hidden', required - `output_variable_name` string, nullable - `timeout` number - PrivateNode — Calls a handler contributed by an installed plugin package. ``handler`` and ``inputs`` are deliberately untyped here: the public schema cannot know what a closed-source distribution provides, so the registry resolves the name and the handler's own model validates the inputs at execution time. See ``optexity.private_nodes``. - `type` 'private_node', required - `handler` string, required - `inputs` object - `output_variable_names` string[], nullable - `before_sleep_time` number - `end_sleep_time` number - `description` string, required - `endpoint_name` string, required ## Response `200` Successful Response - SuccessMessageResponse - `success` boolean, required - `message` string, required ## Other responses - `422` — Validation Error ## Changes > 11 revisions in range; 3 could not be searched. - **2026-08-18** `db4bb403b679` — 24 info - added `#/components/schemas/PrivateNode` to the `automation/nodes/items/oneOf[subschema #2: ForLoopNode]/nodes/items/oneOf[subschema #2: IfElseNode]/else_nodes/items/` request property `anyOf` list - added `#/components/schemas/PrivateNode` to the `automation/nodes/items/oneOf[subschema #2: ForLoopNode]/nodes/items/oneOf[subschema #2: IfElseNode]/if_nodes/items/` request property `anyOf` list - added `#/components/schemas/PrivateNode` to the `automation/nodes/items/oneOf[subschema #2: ForLoopNode]/reset_nodes/items/oneOf[subschema #2: IfElseNode]/else_nodes/items/` request property `anyOf` list - added `#/components/schemas/PrivateNode` to the `automation/nodes/items/oneOf[subschema #2: ForLoopNode]/reset_nodes/items/oneOf[subschema #2: IfElseNode]/if_nodes/items/` request property `anyOf` list - …20 more - …earlier changes not shown [Full history](https://skmtc.dev/optexity/apis/dashboard-backend-api/changes/api/v1/add_example/post.md) --- [API](https://skmtc.dev/optexity/apis/dashboard-backend-api.md) · [All operations](https://skmtc.dev/optexity/apis/dashboard-backend-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/optexity/dashboard-backend-api/revisions/2e974096944a/schema)