### Quick Start: Get, Run, and Update Workflows Source: https://docs.cloudcruise.com/sdk/cli/overview Basic commands to retrieve a workflow definition, start a run, and update a workflow with a new version. ```bash cloudcruise workflows get > workflow.json cloudcruise run start --wait cloudcruise run get cloudcruise workflows update --file workflow.json --version-note "Fixed selector" ``` -------------------------------- ### Start a New Run Source: https://docs.cloudcruise.com/sdk/js/overview Start a new automated run with a specified workflow ID and input variables. This example shows how to initiate a run and log its session ID. ```javascript const run = await client.runs.start({ workflow_id: "workflow-123", run_input_variables: { variable_1: "https://example.com", variable_2: "john_doe", }, }); console.log("Session ID:", run.sessionId); ``` -------------------------------- ### Install CloudCruise Python SDK Source: https://docs.cloudcruise.com/sdk/python/overview Install the SDK using pip. Ensure you have the required credentials set via environment variables or in code. ```bash pip install cloudcruise ``` -------------------------------- ### Install CloudCruise SDK Source: https://docs.cloudcruise.com/sdk/js/overview Install the latest version of the CloudCruise SDK using npm. ```bash npm install cloudcruise ``` -------------------------------- ### Validate and Start Workflow Run Source: https://docs.cloudcruise.com/sdk/python/workflows Get workflow metadata to understand input requirements, build a payload, validate it against the schema, and then start a workflow run. Handles `InputValidationError` if validation fails. ```python from cloudcruise import StartRunRequest from cloudcruise.workflows.types import InputValidationError workflow_id = "workflow-123" # Get metadata to understand required inputs metadata = client.workflows.get_workflow_metadata(workflow_id) schema = metadata.get("input_schema", {}) required_fields = schema.get("required", []) print(f"Required inputs: {required_fields}") # Build a form with required_fields... # Build your payload payload = { "url": "https://example.com", "USER": "user-123", } # Validate before running try: client.workflows.validate_workflow_input(workflow_id, payload) except InputValidationError as exc: print(f"Fix these issues: {exc}") raise # Start the run run = client.runs.start( StartRunRequest( workflow_id=workflow_id, run_input_variables=payload, ) ) print(f"Started run: {run.sessionId}") ``` -------------------------------- ### Install CloudCruise CLI Source: https://docs.cloudcruise.com/sdk/cli/overview Install the CloudCruise CLI globally using npm. This command makes the `cloudcruise` executable available in your terminal. ```bash npm install -g @cloudcruise/cli ``` -------------------------------- ### Start Workflow with Pooled Credentials Source: https://docs.cloudcruise.com/run-api/start-a-run Configure this to start a workflow run utilizing multiple vault entries for load balancing and fault tolerance. The 'USER' key can accept an array of permissioned_user_ids for round-robin selection. ```json { "workflow_id": "d4e5f6a7-89ab-45cd-ef01-456789012abc", "run_input_variables": { "USER": [ "a1b2c3d4-5678-90ab-cdef-1234567890ab", "b2c3d4e5-6789-01bc-def2-234567890abc", "c3d4e5f6-789a-12cd-ef34-34567890abcd" ], "other_input": "value" } } ``` -------------------------------- ### Install CloudCruise Skills for Coding Agents Source: https://docs.cloudcruise.com/sdk/cli/overview Install skill files to provide coding agents with CLI and workflow DSL references. Specify targets for Claude Code or Cursor. ```bash cloudcruise install --skills # Claude Code + Cursor ``` ```bash cloudcruise install --skills --target claude # Claude Code only ``` ```bash cloudcruise install --skills --target cursor # Cursor only ``` -------------------------------- ### Run the Browser Agent Source: https://docs.cloudcruise.com/introduction Trigger the browser agent to execute a workflow via the CloudCruise API. This example demonstrates how to start a run with specified input variables. ```APIDOC ## Run the Browser Agent ### Description Trigger the browser agent to execute a workflow via the CloudCruise API. This example demonstrates how to start a run with specified input variables. ### Method POST ### Endpoint https://api.cloudcruise.com/run ### Parameters #### Request Body - **workflow_id** (string) - Required - The ID of the workflow to run. - **run_input_variables** (object) - Required - A JSON object containing the input variables for the workflow. ### Request Example ```json { "workflow_id": "", "run_input_variables": { "first_name": "John", "last_name": "Doe" } } ``` ### Response #### Success Response (200) - **data** (object) - The output of the workflow run. #### Response Example ```json { "data": {} } ``` ``` -------------------------------- ### Start Workflow Run Source: https://docs.cloudcruise.com/run-api/start-a-run Initiates a new workflow execution with specified input variables and optional configurations. ```APIDOC ## POST /runs ### Description Starts a new workflow execution. ### Method POST ### Endpoint /runs ### Request Body - **workflow_id** (string) - Required - The ID of the workflow to run. - **run_input_variables** (object) - Required - A map of input variables for the workflow. - **workflow_version_number** (integer) - Optional - Pin the run to a specific workflow version. - **dry_run** (object) - Optional - Configuration for dry run execution. - **enabled** (boolean) - Required - Enable dry run mode. - **add_to_output** (object) - Optional - Additional data to add to the output when dry run is enabled. - **webhook** (object) - Optional - Webhook configuration for receiving execution event notifications. - **url** (string) - Required - HTTPS endpoint for webhook events. - **event_types_subscribed** (array) - Optional - List of event types to subscribe to. - **metadata** (object) - Optional - Custom data to include in webhook payloads. - **priority** (string) - Optional - Execution priority (LOW, MEDIUM, HIGH). ### Request Example ```json { "workflow_id": "d4e5f6a7-89ab-45cd-ef01-456789012abc", "run_input_variables": { "USER": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "other_input": "value" }, "dry_run": { "enabled": true, "add_to_output": { "mock_data": "example" } }, "webhook": { "url": "https://example.com/webhook", "event_types_subscribed": ["RUN_COMPLETED"], "metadata": { "source": "api_call" } }, "priority": "HIGH" } ``` ### Response #### Success Response (200) - **run_id** (string) - The ID of the newly created run. - **status** (string) - The initial status of the run. ``` -------------------------------- ### Start a Run Source: https://docs.cloudcruise.com/run-api/start-a-run Initiates a new browser agent run. This endpoint allows you to start a run with input variables, execute runs on behalf of authenticated users, configure webhook notifications for run events, and perform dry runs to prevent writes in the target software. ```APIDOC ## POST /run ### Description Initiates a new browser agent run. This endpoint allows you to: - Start a run with input variables - Execute runs on behalf of authenticated users - Configure webhook notifications for run events - Perform dry runs to prevent writes in the target software ### Method POST ### Endpoint /run ### Parameters #### Request Body - **workflow_id** (string) - Required - Unique identifier for the workflow to execute - **run_input_variables** (object) - Optional - Variables required by the workflow for execution. This includes both regular workflow inputs and vault entry references. **Vault Entry References**: When your workflow requires authentication, reference vault entries using their permissioned_user_id: - Single credential: "USER": "a1b2c3d4-5678-90ab-cdef-1234567890ab" - Pooled credentials: "USER": ["a1b2c3d4-5678-90ab-cdef-1234567890ab", "b2c3d4e5-6789-01bc-def2-234567890abc", "c3d4e5f6-789a-12cd-ef34-34567890abcd"] **Pooled Credentials**: Provide multiple user IDs as an array to enable automatic load balancing and rotation: - CloudCruise uses round-robin selection to distribute runs across available credentials - Helps prevent rate limiting and provides fault tolerance - Respects each credential's concurrency limits and session settings The alias names (e.g., "USER") are defined in your workflow's vault_schema configuration. - **dry_run** (DryRun) - Optional - Configuration for dry runs - **webhook** (PayloadWebhook) - Optional - Configuration for webhook notifications - **priority_level** (Priority) - Optional - Priority level for the run - **encrypted_keys** (array) - Optional - List of run_input_variables keys that are encrypted with your workspace AES key. - **force_refresh** (boolean) - Optional - Force-refresh workflow and encryption key caches before starting the run. Defaults to false. - **capture_console_logs** (boolean) - Optional - Capture browser console logs during execution. Defaults to false. - **send_connection_string** (boolean) - Optional - Include live-view connection details in run execution events when available. Defaults to false. - **client_id** (string) - Optional - Optional client identifier used by SDKs to bind SSE event streams to this run. - **debug** (boolean) - Optional - When enabled, captures an HTML page snapshot for every node executed in the workflow. Defaults to false. - **additional_context** (object) - Optional - Optional JSON data that provides additional context to help the maintenance agent handle unexpected scenarios. ### Request Example ```json { "workflow_id": "your_workflow_id", "run_input_variables": { "USER": "your_vault_entry_id", "some_other_variable": "some_value" }, "dry_run": true, "capture_console_logs": true } ``` ### Response #### Success Response (200) - **session_id** (string) - Unique identifier for the workflow execution session #### Response Example ```json { "session_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab" } ``` #### Error Responses - **400** - Invalid run payload, workflow input validation failed, or required encryption/webhook configuration is missing - **404** - Workflow not found ``` -------------------------------- ### Click to Trigger Download Source: https://docs.cloudcruise.com/concepts/workflow-dsl/file-download Use a Click node to initiate a file download before using the File Download node. This example shows clicking a button with a specific selector. ```json { "id": "click-download", "name": "Click download button", "action": "CLICK", "parameters": { "execution": "STATIC", "selector": "//button[@id='download-report']" } } ``` -------------------------------- ### Start a Run Source: https://docs.cloudcruise.com/sdk/python/overview Initiate a new run with a specified workflow ID and input variables. The `sessionId` is printed upon successful initiation. ```python from cloudcruise import StartRunRequest request = StartRunRequest( workflow_id="workflow-123", run_input_variables={ "variable_1": "https://example.com", "variable_2": "john_doe", }, ) run = client.runs.start(request) print("Session ID:", run.sessionId) ``` -------------------------------- ### Input Schema Structure Example Source: https://docs.cloudcruise.com/sdk/js/workflows An example of the JSON Schema structure for workflow inputs. It defines the type, properties, and required fields for a workflow's input. ```json { "type": "object", "properties": { "url": { "type": "string" }, "max_attempts": { "type": "integer" }, "USER": { "type": "string" }, }, "required": ["url", "USER"], "additionalProperties": false } ``` -------------------------------- ### Vault Client Setup Source: https://docs.cloudcruise.com/sdk/python/vault Initialize the CloudCruise client with API and encryption keys to enable vault operations. ```APIDOC ## Setup ```python theme={null} from cloudcruise import CloudCruise, CloudCruiseParams client = CloudCruise( CloudCruiseParams( api_key="your-api-key", encryption_key="your-encryption-key", ) ) ``` The `encryption_key` is required for vault operations. Get it from [CloudCruise Settings](https://app.cloudcruise.com/settings/encryption-keys). ``` -------------------------------- ### Basic Delay Example Source: https://docs.cloudcruise.com/concepts/workflow-dsl/delay This snippet demonstrates how to configure the Delay node to wait for 2 seconds. Ensure the 'delay_time' parameter is set to the desired duration in seconds. ```json { "id": "abc123", "name": "Wait for animation", "action": "DELAY", "parameters": { "delay_time": 2 } } ``` -------------------------------- ### Run CloudCruise CLI without Installation Source: https://docs.cloudcruise.com/sdk/cli/overview Execute CloudCruise CLI commands without a global installation using npx. Useful for quick checks or testing. ```bash npx @cloudcruise/cli --help ``` -------------------------------- ### Start a CloudCruise Workflow Run (Python) Source: https://docs.cloudcruise.com/introduction Initiates a workflow run using the CloudCruise SDK. Requires API and encryption keys. Listen for events or wait for completion. ```python from cloudcruise import CloudCruise, CloudCruiseParams, StartRunRequest client = CloudCruise( CloudCruiseParams( api_key="your-api-key", encryption_key="your-encryption-key", ) ) run = client.runs.start( StartRunRequest( workflow_id="", run_input_variables={ "first_name": "John", "last_name": "Doe", }, ) ) # Listen for events run.on("end", lambda info: print(f"Run completed with status: {info.get('type')}")) # Or wait for completion result = run.wait() print("Output:", result.get("data")) ``` -------------------------------- ### Handle Other Run Events Source: https://docs.cloudcruise.com/sdk/js/overview Examples of handling less common events like 'ping' and 'reconnect' for monitoring connection status. ```typescript handle.on('ping', (e) => console.log('ping:', e)); handle.on('reconnect', ({ attemptDelayMs }) => console.log('reconnect in', attemptDelayMs, 'ms')); ``` -------------------------------- ### Get all workflows Source: https://docs.cloudcruise.com/workflow-api/get-workflows Retrieves all workflows of the workspace the API key is associated with. ```APIDOC ## GET /workflows ### Description Retrieves all workflows of the workspace the API key is associated with. ### Method GET ### Endpoint /workflows ### Responses #### Success Response (200) - **workflows** (array) - An array of Workflow objects. - **id** (string) - Unique identifier for the workflow - **name** (string) - Name of the workflow - **description** (string, nullable) - Description of the workflow - **created_at** (string) - Timestamp when the workflow was created - **updated_at** (string) - Timestamp when the workflow was last updated - **workspace_id** (string) - ID of the workspace this workflow belongs to - **created_by** (string) - ID of the user who created the workflow - **enable_popup_handling** (boolean) - Whether popup handling is enabled for this workflow - **enable_xpath_recovery** (boolean) - Whether XPath recovery is enabled for this workflow - **enable_node_description_enrichment** (boolean) - Whether node descriptions are auto-enriched for reliability improvements - **enable_error_code_generation** (boolean) - Whether error code generation is enabled for this workflow - **enable_service_unavailable_recovery** (boolean) - Whether service unavailable recovery is enabled for this workflow - **enable_incorrect_form_input_recovery** (boolean) - Whether incorrect form input recovery is enabled - **enable_password_update_recovery** (boolean) - Whether password update recovery is enabled. - **enable_tfa_setup_recovery** (boolean) - Whether automatic TFA setup recovery is enabled. - **enable_action_timing_recovery** (boolean) - Whether action timing recovery is enabled for this workflow - **origin_catalog_workflow_id** (string, nullable) - ID of the catalog workflow this was forked from (if applicable) - **origin_catalog_version_number** (integer, nullable) - Version number of the catalog workflow this was forked from - **track_updates_from_catalog** (boolean) - Whether to track updates from the origin catalog workflow #### Error Response (400) - **description** (string) - Bad request - Missing workspace ID #### Error Response (401) - **description** (string) - Unauthorized - Invalid or missing authentication #### Error Response (500) - **description** (string) - Internal server error ### Request Example (No request body for GET request) ### Response Example ```json [ { "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef", "name": "Example Workflow", "description": "This is an example workflow.", "created_at": "2023-10-27T10:00:00Z", "updated_at": "2023-10-27T10:00:00Z", "workspace_id": "f0e9d8c7-b6a5-4321-0987-654321fedcba", "created_by": "1a2b3c4d-5e6f-7890-1234-567890abcdef", "enable_popup_handling": true, "enable_xpath_recovery": true, "enable_node_description_enrichment": false, "enable_error_code_generation": true, "enable_service_unavailable_recovery": true, "enable_incorrect_form_input_recovery": false, "enable_password_update_recovery": false, "enable_tfa_setup_recovery": false, "enable_action_timing_recovery": true, "origin_catalog_workflow_id": null, "origin_catalog_version_number": null, "track_updates_from_catalog": false } ] ``` ``` -------------------------------- ### Start a CloudCruise Workflow Run (TypeScript) Source: https://docs.cloudcruise.com/introduction Initiates a workflow run using the CloudCruise SDK. Requires API and encryption keys. Listen for events or wait for completion. ```typescript import { CloudCruise } from 'cloudcruise'; const client = new CloudCruise({ apiKey: "your-api-key", encryptionKey: "your-encryption-key", }); const run = await client.runs.start({ workflow_id: "", run_input_variables: { first_name: "John", last_name: "Doe", }, }); // Listen for events run.on('end', ({ type }) => { console.log(`Run completed with status: ${type}`); run.close(); }); // Or wait for completion const result = await run.wait(); console.log("Output:", result.data); ``` -------------------------------- ### Start a CloudCruise Workflow Run (cURL) Source: https://docs.cloudcruise.com/introduction Initiates a workflow run via the CloudCruise API using a cURL command. Requires your API key and workflow ID. ```bash curl --request POST \ --url https://api.cloudcruise.com/run \ --header 'Content-Type: application/json' \ --header 'cc-key: ' \ --data '{ \ "workflow_id": "", \ "run_input_variables": { \ "first_name": "John", \ "last_name": "Doe" \ } \ }' ``` -------------------------------- ### Stream Run Events using Async Iteration Source: https://docs.cloudcruise.com/sdk/python/overview Iterate over the run handle to process Server-Sent Events (SSE) messages asynchronously. This example breaks the loop upon successful completion. ```python for message in handle: data = (message.get("data") or {}) event_type = data.get("event") if event_type != "execution.success": print("Received:", event_type) continue print("Workflow completed successfully") break ``` -------------------------------- ### Get Debug Snapshots Source: https://docs.cloudcruise.com/run-api/get-debug-snapshots Retrieves debug snapshots for a specific node in a workflow run. This endpoint is only available for runs started with `debug: true`. It returns an HTML page snapshot and any screenshots taken at that node. ```APIDOC ## Get Debug Snapshots ### Description Retrieves debug snapshots for a specific node in a workflow run. This endpoint is only available for runs started with `debug: true`. It returns: - An HTML page snapshot captured at the time the node was executed - Any screenshots taken at that node The HTML snapshot contains the full DOM state of the page, including inlined iframe content. Signed URLs are valid for 1 hour. ``` -------------------------------- ### Get Debug Snapshots Source: https://docs.cloudcruise.com/run-api/get-debug-snapshots Retrieves debug snapshots for a specific node in a workflow run. This endpoint is only available for runs started with `debug: true`. It returns an HTML page snapshot and any screenshots taken at that node. The HTML snapshot contains the full DOM state of the page, including inlined iframe content. Signed URLs are valid for 1 hour. ```APIDOC ## GET /run/{session_id}/debug-snapshots/{node_id} ### Description Retrieves debug snapshots for a specific node in a workflow run. This endpoint is only available for runs started with `debug: true`. It returns: - An HTML page snapshot captured at the time the node was executed - Any screenshots taken at that node The HTML snapshot contains the full DOM state of the page, including inlined iframe content. Signed URLs are valid for 1 hour. ### Method GET ### Endpoint /run/{session_id}/debug-snapshots/{node_id} ### Parameters #### Path Parameters - **session_id** (string) - Required - Unique identifier for the workflow execution session - **node_id** (string) - Required - Unique identifier for the workflow node #### Query Parameters None #### Request Body None ### Request Example None ### Response #### Success Response (200) - **session_id** (string) - Unique identifier for the workflow execution session - **node_id** (string) - Unique identifier for the workflow node - **page_snapshot_url** (string) - Signed URL to the HTML page snapshot captured when this node was executed. Contains the full DOM state including inlined iframe content. Valid for 1 hour. Null if no snapshot was captured. - **screenshots** (array) - Screenshots taken at this node during execution - **screenshot_id** (string) - Unique identifier for the screenshot - **signed_screenshot_url** (string) - Signed URL to the screenshot image. Valid for 1 hour. - **node_display_name** (string) - Display name of the workflow node - **node_id** (string) - Unique identifier for the workflow node - **timestamp** (string) - When the screenshot was captured - **signed_screenshot_url_expires** (string) - When the signed screenshot URL expires - **error_screenshot** (boolean) - Whether this screenshot was taken during an error state #### Response Example ```json { "session_id": "e5f6a7b8-9abc-4def-0123-56789abcdef0", "node_id": "9f8e7d6c-5b4a-4321-9edc-ba9876543210", "page_snapshot_url": "https://storage.example.com/page_snapshots/workspace/workflow/node/session.html?token=...", "screenshots": [ { "screenshot_id": "aabbccdd-eeff-4001-8899-112233445566", "signed_screenshot_url": "https://storage.example.com/screenshots/workspace/session/screenshot.jpeg?token=...", "node_display_name": "Click Login Button", "node_id": "9f8e7d6c-5b4a-4321-9edc-ba9876543210", "timestamp": "2026-02-27T07:16:20.083Z", "signed_screenshot_url_expires": "2026-02-27T08:16:20.083Z", "error_screenshot": false } ] } ``` #### Error Response - **404** - Session not found or node has no snapshots ``` -------------------------------- ### Basic Navigation to a URL Source: https://docs.cloudcruise.com/concepts/workflow-dsl/navigate Use this to navigate to a fixed URL. Ensure the URL is correctly formatted. ```json { "id": "abc123", "name": "Go to dashboard", "action": "NAVIGATE", "parameters": { "url": "https://app.example.com/dashboard" } } ``` -------------------------------- ### Listen to Run Events with Handlers Source: https://docs.cloudcruise.com/sdk/python/overview Attach specific event handlers for `execution.step` and `execution.start` for a typed experience. Also includes handlers for `error` and `end` events. ```python def on_execution_step(event): payload = event.get("payload", {}) current_step = payload.get("current_step") next_step = payload.get("next_step") print(f"[SESSION: {handle.sessionId}] STEP: {current_step} -> {next_step} @ {event.get('timestamp')}") def on_execution_start(event): workflow_id = event.get("payload", {}).get("workflow_id") print(f"[SESSION: {handle.sessionId}] START: {workflow_id} @ {event.get('timestamp')}") handle = client.runs.start( StartRunRequest( workflow_id="workflow-123", run_input_variables={"target": "https://example.com"}, ) ) handle.on("execution.step", on_execution_step) handle.on("execution.start", on_execution_start) handle.on("error", lambda err: print(f"[SESSION: {handle.sessionId}] ERROR: {err}")) handle.on("end", lambda info: print(f"[SESSION: {handle.sessionId}] Workflow completed with status: {info.get('type')}")) ``` -------------------------------- ### OpenAPI Specification for Get Workflows Source: https://docs.cloudcruise.com/workflow-api/get-workflows This OpenAPI specification defines the `/workflows` GET endpoint for retrieving all workflows. It includes request and response schemas, authentication methods, and error codes. ```yaml openapi: 3.0.0 info: title: Workflow API version: 1.0.0 description: API for managing workflows and their metadata servers: - url: https://api.cloudcruise.com description: CloudCruise Platform Production API Server security: - AuthScheme: [] paths: /workflows: get: summary: Get all workflows description: Retrieves all workflows of the workspace the API key is associated with operationId: getWorkflows responses: '200': description: Successful operation content: application/json: schema: type: array items: $ref: '#/components/schemas/Workflow' '400': description: Bad request - Missing workspace ID '401': description: Unauthorized - Invalid or missing authentication '500': description: Internal server error components: schemas: Workflow: type: object properties: id: type: string format: uuid description: Unique identifier for the workflow name: type: string description: Name of the workflow description: type: string nullable: true description: Description of the workflow created_at: type: string format: date-time description: Timestamp when the workflow was created updated_at: type: string format: date-time description: Timestamp when the workflow was last updated workspace_id: type: string format: uuid description: ID of the workspace this workflow belongs to created_by: type: string format: uuid description: ID of the user who created the workflow enable_popup_handling: type: boolean description: Whether popup handling is enabled for this workflow enable_xpath_recovery: type: boolean description: Whether XPath recovery is enabled for this workflow enable_node_description_enrichment: type: boolean description: >- Whether node descriptions are auto-enriched for reliability improvements enable_error_code_generation: type: boolean description: Whether error code generation is enabled for this workflow enable_service_unavailable_recovery: type: boolean description: Whether service unavailable recovery is enabled for this workflow enable_incorrect_form_input_recovery: type: boolean description: Whether incorrect form input recovery is enabled enable_password_update_recovery: type: boolean description: >- Whether password update recovery is enabled. When a site forces a password change, the Maintenance Agent classifies the error and sends a notification. enable_tfa_setup_recovery: type: boolean description: >- Whether automatic TFA setup recovery is enabled. When a site requires two-factor authentication setup during login, the Maintenance Agent can autonomously complete the enrollment and update the vault credential. enable_action_timing_recovery: type: boolean description: Whether action timing recovery is enabled for this workflow origin_catalog_workflow_id: type: string format: uuid nullable: true description: ID of the catalog workflow this was forked from (if applicable) origin_catalog_version_number: type: integer nullable: true description: Version number of the catalog workflow this was forked from track_updates_from_catalog: type: boolean description: Whether to track updates from the origin catalog workflow required: - id - name - created_at - updated_at - workspace_id - created_by - enable_popup_handling - enable_xpath_recovery - enable_error_code_generation - enable_service_unavailable_recovery - enable_action_timing_recovery - track_updates_from_catalog securitySchemes: AuthScheme: type: apiKey name: cc-key in: header description: >- API key-based authentication. Provide your CloudCruise API key in the cc-key header. ``` -------------------------------- ### Start Workflow with Single Credential Source: https://docs.cloudcruise.com/run-api/start-a-run Use this configuration to start a workflow run when a single vault entry is required for authentication. The 'USER' key maps to the vault entry's permissioned_user_id. ```json { "workflow_id": "d4e5f6a7-89ab-45cd-ef01-456789012abc", "run_input_variables": { "USER": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "other_input": "value" } } ``` -------------------------------- ### Start a Run with Webhook Configuration Source: https://docs.cloudcruise.com/run-api/start-a-run Initiates a run and sets up webhook notifications for specified event types. The webhook secret is used to verify payload authenticity, and the validity period prevents replay attacks. ```APIDOC ## POST /runs ### Description Starts a new run and configures webhook notifications. ### Method POST ### Endpoint /runs ### Parameters #### Request Body - **url** (string) - Required - The URL to send webhook events to. - **event_types_subscribed** (array of strings) - Required - A list of event types to subscribe to. Available events include: - execution.failed - execution.paused - execution.queued - execution.requeued - execution.start - execution.step - execution.stopped - execution.success - execution.password_updated - file.uploaded - interaction.failed - interaction.finished - interaction.waiting - execution.input_required - agent.error_analysis - agent.tfa_setup_recovery - screenshot.uploaded - video.uploaded - **secret** (string) - Required - Secret key used to generate the X-HMAC-Signature header for verifying webhook payload authenticity. - **validity** (integer) - Required - Number of seconds for webhook event validity. This sets the `expires_at` field in webhook events to prevent replay attacks. - **nr_retries** (integer) - Optional - Maximum number of retry attempts for webhook delivery. Defaults to 3. Minimum 0, Maximum 10. ### Request Example ```json { "url": "https://example.com/webhook", "event_types_subscribed": [ "execution.start", "execution.success" ], "secret": "your-super-secret-key", "validity": 300, "nr_retries": 5 } ``` ### Response #### Success Response (200) - **run_id** (string) - The unique identifier for the started run. - **webhook_status** (string) - The status of the webhook configuration. #### Response Example ```json { "run_id": "run_abc123", "webhook_status": "configured" } ``` ``` -------------------------------- ### Validate Workflow Input and Start Run Source: https://docs.cloudcruise.com/sdk/js/workflows Retrieve workflow metadata to understand required inputs, build a payload, validate it against the schema, and then start a new run. Handles potential validation errors. ```typescript const workflowId = "workflow-123"; // Get metadata to understand required inputs const metadata = await client.workflows.getWorkflowMetadata(workflowId); const schema = metadata.input_schema; const requiredFields = schema?.required || []; console.log(`Required inputs: ${requiredFields.join(", ")}`); // Build a form with required_fields... // Build your payload const payload = { url: "https://example.com", USER: "user-123", }; // Validate before running try { await client.workflows.validateWorkflowInput(workflowId, payload); } catch (error) { console.log(`Fix these issues: ${error}`); throw error; } // Start the run const run = await client.runs.start({ workflow_id: workflowId, run_input_variables: payload, }); console.log(`Started run: ${run.sessionId}`); ``` -------------------------------- ### CloudCruise CLI Commands Reference Source: https://docs.cloudcruise.com/sdk/cli/overview A table summarizing available CloudCruise CLI commands and their descriptions. ```bash auth login --api-key "sk_..." | Save API key to `~/.cloudcruise/config.json` ``` ```bash auth status | Check authentication status ``` ```bash auth logout | Remove saved credentials ``` ```bash workflows get | Get workflow definition with nodes and edges ``` ```bash workflows update --file | Update workflow (creates a new version) ``` ```bash run start | Start a run (returns session_id) ``` ```bash run start --wait | Start and stream events until completion ``` ```bash run start --wait --debug | Start with debug snapshots on every node ``` ```bash run get | Get run status, errors, screenshots, output ``` ```bash run list | List runs (supports `--workflow`, `--status`, `--limit`) ``` ```bash run interrupt | Stop a running session ``` ```bash run errors --since 24h | Error analytics for a workflow ``` ```bash run snapshots | Debug snapshots for a specific node ``` ```bash utils uuid | Generate a random UUID for new node IDs ``` ```bash install --skills | Install skill files for coding agents ``` -------------------------------- ### Validate Workflow Input Source: https://docs.cloudcruise.com/sdk/js/workflows Manually validate a payload against a workflow's input schema before starting a run. This helps catch errors early. The SDK also performs this validation automatically when starting a run. ```typescript import { InputValidationError } from 'cloudcruise'; const payload = { url: "https://example.com", USER: "user-123", }; try { await client.workflows.validateWorkflowInput("workflow-123", payload); console.log("✓ Payload is valid"); } catch (error) { if (error instanceof InputValidationError) { console.log(`✗ Validation failed: ${error.message}`); console.log(` Missing required: ${error.missingRequired}`); console.log(` Invalid types: ${error.invalidTypes}`); console.log(` Unknown keys: ${error.unknownKeys}`); } throw error; } ``` -------------------------------- ### Creating a Vault Entry Source: https://docs.cloudcruise.com/sdk/js/vault Use `client.vault.create()` to store new credentials. Sensitive fields are automatically encrypted. ```APIDOC ## Creating a Vault Entry Use `client.vault.create()` to store new credentials: ```typescript const entry = await client.vault.create( "https://example.com", // domain "unique-user-id", // permissioned_user_id { user_name: "john@example.com", password: "secret-password", user_alias: "John's Account", } ); console.log("Created vault entry:", entry.id); ``` ### Parameters | Parameter | Type | Required | Description | | ---------------------- | -------- | -------- | --------------------------------------------------------------- | | `domain` | `string` | Yes | Target domain for the credentials (e.g., `https://example.com`) | | `permissioned_user_id` | `string` | Yes | Unique identifier to reference this entry in workflows | | `options` | `object` | No | Additional fields (see below) | ### Options Object | Field | Type | Description | | ------------------------- | --------- | ---------------------------------------------------------------------------- | | `user_name` | `string` | Username or email for authentication | | `password` | `string` | Password credential | | `user_alias` | `string` | Human-readable label for the entry | | `tfa_secret` | `string` | TOTP secret for two-factor authentication | | `tfa_method` | `string` | TFA method: `"AUTHENTICATOR"`, `"EMAIL"`, `"MAGIC_LINK"`, or `"SMS"` | | `persist_cookies` | `boolean` | Maintain cookies across workflow executions | | `persist_local_storage` | `boolean` | Maintain local storage across executions | | `persist_session_storage` | `boolean` | Maintain session storage across executions | | `skip_csrf_cookies` | `boolean` | Skip injecting CSRF-related cookies (e.g. XSRF-TOKEN) during session restore | | `allow_multiple_sessions` | `boolean` | Allow concurrent workflow sessions with these credentials | | `max_concurrency` | `number` | Maximum concurrent sessions (when `allow_multiple_sessions` is true) | | `proxy` | `object` | Proxy configuration with `enable` (boolean) and `target_ip` (string) | ``` -------------------------------- ### OpenAPI Specification for Get Workflow Metadata Source: https://docs.cloudcruise.com/workflow-api/get-metadata This OpenAPI specification defines the `get /workflows/{workflow_id}/metadata` endpoint. It includes parameters for workflow ID and authentication, and describes the successful response structure containing input and vault schemas, as well as potential error responses. ```yaml openapi: 3.0.0 info: title: Workflow API version: 1.0.0 description: API for managing workflows and their metadata servers: - url: https://api.cloudcruise.com description: CloudCruise Platform Production API Server security: - AuthScheme: [] paths: /workflows/{workflow_id}/metadata: get: summary: Get workflow metadata description: Retrieves computed input and vault schemas for a specific workflow operationId: getWorkflowMetadata parameters: - name: workflow_id in: path required: true schema: type: string description: The ID of the workflow - name: cc-key in: header required: false schema: type: string description: CloudCruise API key for authentication responses: '200': description: Successful operation content: application/json: schema: type: object properties: input_schema: type: object description: >- Full JSON schema used to validate `run_input_variables`, including workflow-level and derived schema constraints. additionalProperties: true vault_schema: type: object description: Schema defining vault credentials and their configuration additionalProperties: type: object properties: type: type: string enum: - credential description: Type of vault entry domain: type: string description: Domain associated with the credential example: https://example.com example: type: string description: Example value for the credential example: 11223344-5566-7788-9900-112233445566 example: USER: type: credential domain: https://example.com example: 11223344-5566-7788-9900-112233445566 '401': description: Unauthorized - Invalid or missing authentication '404': description: Workflow not found '500': description: Internal server error components: securitySchemes: AuthScheme: type: apiKey name: cc-key in: header description: >- API key-based authentication. Provide your CloudCruise API key in the cc-key header. ``` -------------------------------- ### Navigate using Input Variables Source: https://docs.cloudcruise.com/concepts/workflow-dsl/navigate Dynamically set the navigation URL using template variables from context inputs. This allows for flexible navigation based on workflow inputs. ```json { "id": "abc123", "name": "Navigate to user profile", "action": "NAVIGATE", "parameters": { "url": "https://app.example.com/users/{{context.inputs.user_id}}" } } ``` -------------------------------- ### Get Vault Entries Source: https://docs.cloudcruise.com/sdk/python/vault Retrieves vault entries based on specified filters. ```APIDOC ## Get Vault Entries Retrieves vault entries based on specified filters. ### Method `client.vault.get()` ### Parameters #### Request Body - **domain** (string) - Optional - Filters entries by domain. - **permissioned_user_id** (string) - Optional - Filters entries by permissioned user ID. ### Request Example ```python entries = client.vault.get( GetVaultEntriesFilters( domain="https://login.example.com", permissioned_user_id="user-123", ) ) ``` ``` -------------------------------- ### Initialize CloudCruise Client Source: https://docs.cloudcruise.com/sdk/js/overview Initialize the CloudCruise client with your API and encryption keys. ```javascript import { CloudCruise } from 'cloudcruise'; const client = new CloudCruise({ apiKey: "your-api-key", encryptionKey: "your-encryption-key", }); ``` -------------------------------- ### Initialize CloudCruise Client Source: https://docs.cloudcruise.com/sdk/python/overview Initialize the CloudCruise client with your API and encryption keys. These can be provided directly or through environment variables. ```python from cloudcruise import CloudCruise, CloudCruiseParams client = CloudCruise( CloudCruiseParams( api_key="your-api-key", encryption_key="your-encryption-key", ) ) ``` -------------------------------- ### Get workflow Source: https://docs.cloudcruise.com/llms.txt Retrieves the full workflow definition including nodes, edges, and configuration. ```APIDOC ## Get workflow ### Description Retrieves the full workflow definition including nodes, edges, and configuration. ### Method GET ### Endpoint /workflows/{workflow_id} ### Parameters #### Path Parameters - **workflow_id** (string) - Required - The unique identifier of the workflow. ### Response #### Success Response (200) - **workflow_id** (string) - The unique identifier of the workflow. - **name** (string) - The name of the workflow. - **definition** (object) - The workflow definition. ### Response Example ```json { "workflow_id": "wf_xyz789", "name": "Example Workflow", "definition": { "nodes": [ { "id": "node1", "type": "start" } ], "edges": [] } } ``` ``` -------------------------------- ### Get vault entries Source: https://docs.cloudcruise.com/llms.txt Retrieves vault entries for users matching the specified criteria. ```APIDOC ## Get vault entries ### Description Retrieves vault entries for users matching the specified criteria. ### Method GET ### Endpoint /vault ### Parameters #### Query Parameters - **domain** (string) - Optional - Filter by domain. - **userId** (string) - Optional - Filter by user ID. ### Response #### Success Response (200) - **vaultEntries** (array) - A list of vault entry objects. - **domain** (string) - The domain of the vault entry. - **userId** (string) - The user ID of the vault entry. ### Response Example ```json { "vaultEntries": [ { "domain": "example.com", "userId": "user123" } ] } ``` ``` -------------------------------- ### Get Workflow Metadata Source: https://docs.cloudcruise.com/workflow-api/get-metadata Retrieves computed input and vault schemas for a specific workflow. ```APIDOC ## GET /workflows/{workflow_id}/metadata ### Description Retrieves computed input and vault schemas for a specific workflow. ### Method GET ### Endpoint /workflows/{workflow_id}/metadata ### Parameters #### Path Parameters - **workflow_id** (string) - Required - The ID of the workflow #### Query Parameters - **cc-key** (string) - Optional - CloudCruise API key for authentication ### Response #### Success Response (200) - **input_schema** (object) - Full JSON schema used to validate `run_input_variables`, including workflow-level and derived schema constraints. - **vault_schema** (object) - Schema defining vault credentials and their configuration. #### Error Response - **401** - Unauthorized - Invalid or missing authentication - **404** - Workflow not found - **500** - Internal server error ```