donobu 2.37.3 → 2.38.0

package/dist/esm/assets/openapi-schema.yaml

@@ -0,0 +1,1483 @@
+openapi: '3.0.0'
+info:
+  title: 'Donobu API'
+  version: '1.0.0'
+  description: "The Donobu API provides a comprehensive suite of tools for automating web browser interactions. It allows you to create, manage, and execute 'flows,' which are sequences of actions performed in a browser, driven either by an AI agent or by a predefined script. This API is designed for a wide range of use cases, from simple website navigation and data extraction to complex, multi-step process automation and testing.\n\nKey features include:\n- **Flow Management**: Create, run, monitor, and delete automation flows.\n- **AI-Powered Automation**: Leverage powerful GPT models to drive flows autonomously based on a high-level objective.\n- **Deterministic Replay**: Rerun past flows exactly as they occurred or generate Playwright scripts for integration into testing pipelines.\n- **Configuration Management**: Manage GPT configurations, agent assignments, and environment variables used by your flows.\n- **Rich Data Access**: Retrieve detailed information about flow execution, including tool calls, screenshots, and video recordings."
+servers:
+  - url: 'http://localhost:31000'
+    description: 'Local Donobu app server'
+tags:
+  - name: 'flows'
+    description: 'Endpoints for creating, managing, and inspecting automation flows. Flows are the core resource in Donobu, representing a sequence of browser interactions to achieve a specific objective.'
+  - name: 'configs'
+    description: 'Endpoints for managing configurations used by flows, including GPT model settings and environment variables.'
+  - name: 'agents'
+    description: 'Endpoints for managing AI agents and assigning them specific GPT configurations to use for decision-making in autonomous flows.'
+  - name: 'tools'
+    description: 'Endpoints for discovering the browser automation tools available for use within flows.'
+  - name: 'system'
+    description: 'Endpoints for system-level operations, such as health checks and version information.'
+paths:
+  /api/flows:
+    get:
+      tags:
+        - 'flows'
+      summary: 'List all flows'
+      description: 'Retrieves a paginated list of flows, with options for filtering by name, date, run mode, and state. Results are ordered by creation date, with the newest flows appearing first.'
+      operationId: 'getFlows'
+      parameters:
+        - name: 'name'
+          in: 'query'
+          description: 'Filter flows by exact name match.'
+          required: false
+          schema:
+            type: 'string'
+        - name: 'startedAfter'
+          in: 'query'
+          description: 'Filter for flows that started at or after this Unix epoch timestamp (in milliseconds).'
+          required: false
+          schema:
+            type: 'integer'
+            format: 'int64'
+        - name: 'startedBefore'
+          in: 'query'
+          description: 'Filter for flows that started at or before this Unix epoch timestamp (in milliseconds).'
+          required: false
+          schema:
+            type: 'integer'
+            format: 'int64'
+        - name: 'runMode'
+          in: 'query'
+          description: 'Filter flows by their run mode.'
+          required: false
+          schema:
+            $ref: '#/components/schemas/RunMode'
+        - name: 'state'
+          in: 'query'
+          description: 'Filter flows by their current state.'
+          required: false
+          schema:
+            $ref: '#/components/schemas/State'
+        - name: 'limit'
+          in: 'query'
+          description: 'The maximum number of flows to return. Must be between 1 and 100. Defaults to 100.'
+          required: false
+          schema:
+            type: 'integer'
+            minimum: 1
+            maximum: 100
+            default: 100
+        - name: 'pageToken'
+          in: 'query'
+          description: 'A token for fetching the next page of results.'
+          required: false
+          schema:
+            type: 'string'
+      responses:
+        '200':
+          description: 'A paginated list of flow metadata.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PaginatedFlowMetadata'
+        '400':
+          description: 'The request contains invalid query parameters.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+    post:
+      tags:
+        - 'flows'
+      summary: 'Create a new flow'
+      description: 'Creates and initiates a new automation flow based on the provided configuration. The flow will start executing immediately.'
+      operationId: 'createFlow'
+      requestBody:
+        description: 'Configuration for the new flow.'
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateDonobuFlow'
+      responses:
+        '201':
+          description: 'The flow was created successfully. The response body contains the initial metadata of the newly created flow.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/FlowMetadata'
+        '400':
+          description: 'The request body is invalid or contains conflicting parameters.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+  /api/flows/{flowId}:
+    get:
+      tags:
+        - 'flows'
+      summary: 'Get flow metadata'
+      description: 'Retrieves the complete metadata for a specific flow by its unique ID. This includes its current state, configuration, and results if completed.'
+      operationId: 'getFlowMetadata'
+      parameters:
+        - name: 'flowId'
+          in: 'path'
+          description: 'The unique identifier of the flow.'
+          required: true
+          schema:
+            type: 'string'
+            format: 'uuid'
+      responses:
+        '200':
+          description: 'Successfully retrieved the flow metadata.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/FlowMetadata'
+        '404':
+          description: 'A flow with the specified ID was not found.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+    delete:
+      tags:
+        - 'flows'
+      summary: 'Delete a flow'
+      description: 'Deletes a completed flow and all its associated data, including screenshots, videos, and tool call history. A flow cannot be deleted while it is still running.'
+      operationId: 'deleteFlow'
+      parameters:
+        - name: 'flowId'
+          in: 'path'
+          description: 'The unique identifier of the flow to delete.'
+          required: true
+          schema:
+            type: 'string'
+            format: 'uuid'
+      responses:
+        '204':
+          description: 'The flow was successfully deleted.'
+        '404':
+          description: 'A flow with the specified ID was not found.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '405':
+          description: 'The flow is currently running and cannot be deleted.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+  /api/flows/{flowId}/rename:
+    post:
+      tags:
+        - 'flows'
+      summary: 'Rename a flow'
+      description: 'Updates the name of a specific flow. The name is used for display and can be used to look up flows.'
+      operationId: 'renameFlow'
+      parameters:
+        - name: 'flowId'
+          in: 'path'
+          description: 'The unique identifier of the flow to rename.'
+          required: true
+          schema:
+            type: 'string'
+            format: 'uuid'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: 'object'
+              properties:
+                name:
+                  type: 'string'
+                  description: 'The new name for the flow. Can be set to null to remove the name.'
+                  nullable: true
+              required:
+                - 'name'
+      responses:
+        '200':
+          description: 'The flow was successfully renamed. The response body contains the updated flow metadata.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/FlowMetadata'
+        '400':
+          description: 'The provided name is invalid (e.g., too long).'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '404':
+          description: 'A flow with the specified ID was not found.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+  /api/flows/{flowId}/rerun:
+    get:
+      tags:
+        - 'flows'
+      summary: 'Get flow as a rerun configuration'
+      description: 'Generates a `CreateDonobuFlow` configuration object based on a previously executed flow. This configuration can be used to rerun the flow in `DETERMINISTIC` mode, replaying its exact sequence of successful actions.'
+      operationId: 'getFlowAsRerun'
+      parameters:
+        - name: 'flowId'
+          in: 'path'
+          description: 'The unique identifier of the flow to use as a template.'
+          required: true
+          schema:
+            type: 'string'
+            format: 'uuid'
+        - $ref: '#/components/parameters/areElementIdsVolatile'
+        - $ref: '#/components/parameters/disableSelectorFailover'
+      responses:
+        '200':
+          description: 'A configuration object for rerunning the flow.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CreateDonobuFlow'
+        '404':
+          description: 'A flow with the specified ID was not found.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+  /api/flows/{flowId}/code:
+    get:
+      tags:
+        - 'flows'
+      summary: 'Get flow as Playwright script'
+      description: 'Generates a Node.js Playwright script that replays the successful actions of a specified flow. This is useful for exporting automations into a standard testing framework.'
+      operationId: 'getFlowAsCode'
+      parameters:
+        - name: 'flowId'
+          in: 'path'
+          description: 'The unique identifier of the flow to convert to code.'
+          required: true
+          schema:
+            type: 'string'
+            format: 'uuid'
+        - $ref: '#/components/parameters/areElementIdsVolatile'
+        - $ref: '#/components/parameters/disableSelectorFailover'
+        - $ref: '#/components/parameters/disableSelfHealingTests'
+        - $ref: '#/components/parameters/disablePullRequestCreation'
+        - $ref: '#/components/parameters/runInHeadedMode'
+        - $ref: '#/components/parameters/slowMotionDelay'
+      responses:
+        '200':
+          description: 'The generated Playwright script.'
+          content:
+            text/plain:
+              schema:
+                type: 'string'
+                example: "const { chromium } = require('playwright');\n\n(async () => {\n  const browser = await chromium.launch();\n  const page = await browser.newPage();\n  await page.goto('https://example.com');\n  // ... more actions\n  await browser.close();\n})();"
+        '404':
+          description: 'A flow with the specified ID was not found.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+  /api/flows/project:
+    post:
+      tags:
+        - 'flows'
+      summary: 'Get flows as Playwright project'
+      description: 'Generates a complete, runnable Playwright project from a list of flow IDs. The project includes all necessary test files, configurations, and resolved dependencies, making it easy to export and run a suite of automations.'
+      operationId: 'getFlowsAsProject'
+      requestBody:
+        description: 'A list of flow IDs to include in the project and code generation options.'
+        required: true
+        content:
+          application/json:
+            schema:
+              type: 'object'
+              properties:
+                flowIds:
+                  type: 'array'
+                  items:
+                    type: 'string'
+                    format: 'uuid'
+                  description: 'An array of flow IDs to include in the generated project.'
+                options:
+                  $ref: '#/components/schemas/CodeGenerationOptions'
+              required:
+                - 'flowIds'
+      responses:
+        '200':
+          description: 'A zip archive containing the generated Playwright project.'
+          content:
+            application/zip:
+              schema:
+                type: 'string'
+                format: 'binary'
+        '400':
+          description: 'The request body is invalid.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '404':
+          description: 'One or more of the specified flow IDs were not found.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+  /api/flows/{flowId}/images/{imageId}:
+    get:
+      tags:
+        - 'flows'
+      summary: 'Get a flow screenshot'
+      description: 'Retrieves a specific screenshot image (in PNG format) associated with a flow, identified by its image ID. Screenshots are typically captured after each tool call.'
+      operationId: 'getFlowImage'
+      parameters:
+        - name: 'flowId'
+          in: 'path'
+          description: 'The unique identifier of the flow.'
+          required: true
+          schema:
+            type: 'string'
+            format: 'uuid'
+        - name: 'imageId'
+          in: 'path'
+          description: 'The unique identifier of the image.'
+          required: true
+          schema:
+            type: 'string'
+      responses:
+        '200':
+          description: 'The screenshot image file.'
+          content:
+            image/png:
+              schema:
+                type: 'string'
+                format: 'binary'
+        '404':
+          description: 'The specified flow or image was not found.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+  /api/flows/{flowId}/video:
+    get:
+      tags:
+        - 'flows'
+      summary: 'Get flow video recording'
+      description: 'Retrieves the video recording (in WebM format) of a flow run. Videos are available for flows that were run with a visible browser window.'
+      operationId: 'getFlowVideo'
+      parameters:
+        - name: 'flowId'
+          in: 'path'
+          description: 'The unique identifier of the flow.'
+          required: true
+          schema:
+            type: 'string'
+            format: 'uuid'
+      responses:
+        '200':
+          description: 'The video recording file.'
+          content:
+            video/webm:
+              schema:
+                type: 'string'
+                format: 'binary'
+        '404':
+          description: 'The specified flow or its video was not found.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+  /api/flows/{flowId}/tool-calls:
+    get:
+      tags:
+        - 'flows'
+      summary: 'List tool calls for a flow'
+      description: 'Retrieves a list of all tool calls that were executed during a specific flow run, in the order they were performed.'
+      operationId: 'getFlowToolCalls'
+      parameters:
+        - name: 'flowId'
+          in: 'path'
+          description: 'The unique identifier of the flow.'
+          required: true
+          schema:
+            type: 'string'
+            format: 'uuid'
+      responses:
+        '200':
+          description: 'An array of tool call objects.'
+          content:
+            application/json:
+              schema:
+                type: 'array'
+                items:
+                  $ref: '#/components/schemas/ToolCall'
+        '404':
+          description: 'A flow with the specified ID was not found.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+  /api/flows/{flowId}/tool-calls/{toolCallId}:
+    get:
+      tags:
+        - 'flows'
+      summary: 'Get a specific tool call'
+      description: 'Retrieves the details of a single tool call from a flow run, identified by its unique tool call ID.'
+      operationId: 'getFlowToolCall'
+      parameters:
+        - name: 'flowId'
+          in: 'path'
+          description: 'The unique identifier of the flow.'
+          required: true
+          schema:
+            type: 'string'
+            format: 'uuid'
+        - name: 'toolCallId'
+          in: 'path'
+          description: 'The unique identifier of the tool call.'
+          required: true
+          schema:
+            type: 'string'
+      responses:
+        '200':
+          description: 'The tool call object.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ToolCall'
+        '404':
+          description: 'The specified flow or tool call was not found.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+  /api/gpt-configs:
+    get:
+      tags:
+        - 'configs'
+      summary: 'List all GPT configurations'
+      description: 'Retrieves a list of all saved GPT configurations. API keys and other secrets are redacted from the response.'
+      operationId: 'listGptConfigs'
+      responses:
+        '200':
+          description: 'A list of GPT configurations.'
+          content:
+            application/json:
+              schema:
+                type: 'array'
+                items:
+                  $ref: '#/components/schemas/GptConfig'
+  /api/gpt-configs/{name}:
+    get:
+      tags:
+        - 'configs'
+      summary: 'Get a GPT configuration'
+      description: 'Retrieves a specific GPT configuration by its name. API keys and other secrets are redacted from the response.'
+      operationId: 'getGptConfig'
+      parameters:
+        - name: 'name'
+          in: 'path'
+          description: 'The unique name of the GPT configuration.'
+          required: true
+          schema:
+            type: 'string'
+      responses:
+        '200':
+          description: 'The requested GPT configuration.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/GptConfig'
+        '404':
+          description: 'A GPT configuration with the specified name was not found.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+    post:
+      tags:
+        - 'configs'
+      summary: 'Create or update a GPT configuration'
+      description: 'Creates a new GPT configuration or updates an existing one with the same name. This is used to define connection details for different AI models and platforms.'
+      operationId: 'setGptConfig'
+      parameters:
+        - name: 'name'
+          in: 'path'
+          description: 'The unique name for the GPT configuration.'
+          required: true
+          schema:
+            type: 'string'
+      requestBody:
+        description: 'The GPT configuration object.'
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/GptConfig'
+      responses:
+        '200':
+          description: 'The GPT configuration was successfully created or updated. The response body contains the saved configuration with secrets redacted.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/GptConfig'
+        '400':
+          description: 'The request body is invalid.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+    delete:
+      tags:
+        - 'configs'
+      summary: 'Delete a GPT configuration'
+      description: 'Deletes a GPT configuration by its name. This action cannot be undone.'
+      operationId: 'deleteGptConfig'
+      parameters:
+        - name: 'name'
+          in: 'path'
+          description: 'The name of the GPT configuration to delete.'
+          required: true
+          schema:
+            type: 'string'
+      responses:
+        '204':
+          description: 'The GPT configuration was successfully deleted.'
+        '404':
+          description: 'A GPT configuration with the specified name was not found.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+  /api/env:
+    get:
+      tags:
+        - 'configs'
+      summary: 'List all environment data'
+      description: 'Retrieves all stored environment variables as a key-value map. These variables can be referenced within flows.'
+      operationId: 'getEnvironmentData'
+      responses:
+        '200':
+          description: 'A map of all environment variables.'
+          content:
+            application/json:
+              schema:
+                type: 'object'
+                additionalProperties:
+                  type: 'string'
+  /api/env/{key}:
+    get:
+      tags:
+        - 'configs'
+      summary: 'Get an environment datum'
+      description: 'Retrieves the value of a specific environment variable by its key.'
+      operationId: 'getEnvironmentDatum'
+      parameters:
+        - name: 'key'
+          in: 'path'
+          description: 'The key of the environment variable.'
+          required: true
+          schema:
+            type: 'string'
+      responses:
+        '200':
+          description: 'The value of the environment variable.'
+          content:
+            application/json:
+              schema:
+                type: 'object'
+                properties:
+                  value:
+                    type: 'string'
+        '404':
+          description: 'An environment variable with the specified key was not found.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+    post:
+      tags:
+        - 'configs'
+      summary: 'Set an environment datum'
+      description: 'Creates or updates an environment variable with a specified key and value.'
+      operationId: 'setEnvironmentDatum'
+      parameters:
+        - name: 'key'
+          in: 'path'
+          description: 'The key of the environment variable to set.'
+          required: true
+          schema:
+            type: 'string'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: 'object'
+              properties:
+                value:
+                  type: 'string'
+                  description: 'The value to assign to the environment variable.'
+              required:
+                - 'value'
+      responses:
+        '204':
+          description: 'The environment variable was successfully set.'
+    delete:
+      tags:
+        - 'configs'
+      summary: 'Delete an environment datum'
+      description: 'Deletes an environment variable by its key.'
+      operationId: 'deleteEnvironmentDatum'
+      parameters:
+        - name: 'key'
+          in: 'path'
+          description: 'The key of the environment variable to delete.'
+          required: true
+          schema:
+            type: 'string'
+      responses:
+        '204':
+          description: 'The environment variable was successfully deleted.'
+  /api/agents:
+    get:
+      tags:
+        - 'agents'
+      summary: 'List all agent assignments'
+      description: 'Retrieves a map of all agents and their assigned GPT configurations.'
+      operationId: 'listAgents'
+      responses:
+        '200':
+          description: 'A map of agent names to their assigned GPT configuration names.'
+          content:
+            application/json:
+              schema:
+                type: 'object'
+                additionalProperties:
+                  type: 'string'
+  /api/agents/{name}:
+    get:
+      tags:
+        - 'agents'
+      summary: "Get an agent's assigned GPT configuration"
+      description: 'Retrieves the name of the GPT configuration assigned to a specific agent.'
+      operationId: 'getAgent'
+      parameters:
+        - name: 'name'
+          in: 'path'
+          description: 'The name of the agent.'
+          required: true
+          schema:
+            $ref: '#/components/schemas/DonobuAgent'
+      responses:
+        '200':
+          description: "The agent's assigned GPT configuration name."
+          content:
+            application/json:
+              schema:
+                type: 'object'
+                properties:
+                  gptConfigName:
+                    type: 'string'
+        '404':
+          description: 'The specified agent or its assignment was not found.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+    post:
+      tags:
+        - 'agents'
+      summary: 'Assign a GPT configuration to an agent'
+      description: 'Assigns a specific GPT configuration to an agent, determining which AI model the agent will use for its tasks.'
+      operationId: 'setAgent'
+      parameters:
+        - name: 'name'
+          in: 'path'
+          description: 'The name of the agent to configure.'
+          required: true
+          schema:
+            $ref: '#/components/schemas/DonobuAgent'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: 'object'
+              properties:
+                gptConfigName:
+                  type: 'string'
+                  description: 'The name of the GPT configuration to assign to the agent.'
+              required:
+                - 'gptConfigName'
+      responses:
+        '200':
+          description: 'The assignment was successful.'
+          content:
+            application/json:
+              schema:
+                type: 'object'
+                properties:
+                  name:
+                    $ref: '#/components/schemas/DonobuAgent'
+                  gptConfigName:
+                    type: 'string'
+        '404':
+          description: 'The specified GPT configuration was not found.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+  /api/tools:
+    get:
+      tags:
+        - 'tools'
+      summary: 'List available tools'
+      description: 'Retrieves a list of all built-in tools that can be used within a flow to interact with web pages and control the automation process.'
+      operationId: 'listTools'
+      responses:
+        '200':
+          description: 'A list of available tools.'
+          content:
+            application/json:
+              schema:
+                type: 'array'
+                items:
+                  $ref: '#/components/schemas/ToolDefinition'
+  /api/version:
+    get:
+      tags:
+        - 'system'
+      summary: 'Get API version'
+      description: 'Retrieves the current version of the Donobu application.'
+      operationId: 'getVersion'
+      responses:
+        '200':
+          description: 'The application version.'
+          content:
+            application/json:
+              schema:
+                type: 'object'
+                properties:
+                  version:
+                    type: 'string'
+                    description: 'The semantic version of the application.'
+                    example: '1.0.0'
+  /api/ping:
+    get:
+      tags:
+        - 'system'
+      summary: 'Ping the API'
+      description: 'A simple health check endpoint to verify that the API server is running and responsive.'
+      operationId: 'ping'
+      responses:
+        '200':
+          description: 'The server is alive.'
+          content:
+            application/json:
+              schema:
+                type: 'object'
+                properties:
+                  status:
+                    type: 'string'
+                    example: 'pong'
+components:
+  parameters:
+    areElementIdsVolatile:
+      name: 'areElementIdsVolatile'
+      in: 'query'
+      description: "If true, ID-only selectors (e.g. '#submit-btn') are dropped because the element's 'id' attribute is considered volatile. When every candidate is ID-based the list is left unchanged."
+      schema:
+        type: 'boolean'
+    disableSelectorFailover:
+      name: 'disableSelectorFailover'
+      in: 'query'
+      description: 'If false, only the most specific selector is used, disabling automatic fail-over to broader selectors.'
+      schema:
+        type: 'boolean'
+    disableSelfHealingTests:
+      name: 'disableSelfHealingTests'
+      in: 'query'
+      description: 'Disable self-healing tests.'
+      schema:
+        type: 'boolean'
+    disablePullRequestCreation:
+      name: 'disablePullRequestCreation'
+      in: 'query'
+      description: 'Disable the automatic creation of pull requests for tests that have self healed.'
+      schema:
+        type: 'boolean'
+    runInHeadedMode:
+      name: 'runInHeadedMode'
+      in: 'query'
+      description: 'Run tests with visible browser windows instead of headless mode.'
+      schema:
+        type: 'boolean'
+    slowMotionDelay:
+      name: 'slowMotionDelay'
+      in: 'query'
+      description: 'Delay in milliseconds between actions. Set to 0 to disable slow motion.'
+      schema:
+        type: 'number'
+        minimum: 0
+  schemas:
+    CreateDonobuFlow:
+      type: 'object'
+      description: 'This is the expected payload for a request to create a new Donobu flow.'
+      properties:
+        name:
+          type: 'string'
+          description: 'The name for this Donobu flow; if present, must be fewer than 256 characters.'
+          maxLength: 255
+          nullable: true
+        browser:
+          $ref: '#/components/schemas/BrowserConfig'
+          nullable: true
+        envVars:
+          type: 'array'
+          items:
+            type: 'string'
+          description: 'The names of environment variables made available for use by the flow.'
+          nullable: true
+        customTools:
+          type: 'array'
+          items:
+            $ref: '#/components/schemas/CustomTool'
+          description: 'Custom tools available for the flow.'
+          nullable: true
+        defaultMessageDuration:
+          type: 'number'
+          description: "The default amount of time the Donobu flow agent's messaging for the user should show (in milliseconds)."
+          nullable: true
+        callbackUrl:
+          type: 'string'
+          description: 'The URL to HTTP POST to when the flow completes. The body will contain a JSON object with single field, "id", of which is the ID of the flow that completed.'
+          nullable: true
+        targetWebsite:
+          type: 'string'
+          description: 'The website URL to start the flow at.'
+        overallObjective:
+          type: 'string'
+          description: "The overall objective to pursue; can only be omitted if initialRunMode has an effective value of 'INSTRUCT' or 'DETERMINISTIC'."
+          nullable: true
+        allowedTools:
+          type: 'array'
+          items:
+            type: 'string'
+          description: 'The complete set of tools (by name) that this flow is permitted to use. This list is automatically populated by combining any explicitly specified allowedTools with tools from customTools and any tools referenced in toolCallsOnStart. Tools not in this list cannot be invoked during flow execution.'
+          nullable: true
+        resultJsonSchema:
+          type: 'object'
+          description: 'If non-null, the JSON schema that the result field will conform to.'
+          additionalProperties: true
+          nullable: true
+        maxToolCalls:
+          type: 'number'
+          description: "Set the maximum number of actions that can be taken in a flow. This setting is only used if the initialRunMode has an effective value of 'AUTONOMOUS'."
+          nullable: true
+        gptConfigNameOverride:
+          type: 'string'
+          description: 'The name of a specific GPT configuration to use. If the corresponding GPT configuration is not defined or unresolvable, the default flow agent configuration will be used.'
+          nullable: true
+        initialRunMode:
+          $ref: '#/components/schemas/RunMode'
+          nullable: true
+        isControlPanelEnabled:
+          type: 'boolean'
+          description: 'Set to true if the in-browser control panel should be enabled. If the headless parameter is true, then this parameter is ignored.'
+          nullable: true
+        toolCallsOnStart:
+          type: 'array'
+          items:
+            $ref: '#/components/schemas/ProposedToolCall'
+          description: 'An ordered series of tool calls to invoke when starting the flow.'
+          nullable: true
+    FlowMetadata:
+      type: 'object'
+      properties:
+        id:
+          type: 'string'
+          description: 'The unique ID of this flow.'
+        name:
+          type: 'string'
+          description: 'The name of this flow.'
+          nullable: true
+        createdWithDonobuVersion:
+          type: 'string'
+          description: 'The version of Donobu that created the flow.'
+        browser:
+          $ref: '#/components/schemas/BrowserConfig'
+        envVars:
+          type: 'array'
+          items:
+            type: 'string'
+          description: 'The names of environment variables made available for use by the flow.'
+          nullable: true
+        gptConfigName:
+          type: 'string'
+          description: 'The name of the specific GPT configuration used for the flow.'
+          nullable: true
+        hasGptConfigNameOverride:
+          type: 'boolean'
+          description: 'If true, means that the `gptConfigName` was explicitly overwritten when the flow was created.'
+        customTools:
+          type: 'array'
+          items:
+            $ref: '#/components/schemas/CustomTool'
+          description: 'Custom tools available for the flow.'
+          nullable: true
+        defaultMessageDuration:
+          type: 'number'
+          description: "The default amount of time the Donobu flow agent's messaging for the user should show (in milliseconds)."
+          nullable: true
+        runMode:
+          $ref: '#/components/schemas/RunMode'
+        isControlPanelEnabled:
+          type: 'boolean'
+          description: 'Set to true if the in-browser control panel should be enabled.'
+        callbackUrl:
+          type: 'string'
+          description: 'The URL to HTTP POST to when the flow completes. The body will contain a JSON object with single field, "id", of which is the ID of the flow that completed.'
+          nullable: true
+        targetWebsite:
+          type: 'string'
+          description: 'The website URL to start the flow at.'
+        overallObjective:
+          type: 'string'
+          description: 'The overall objective to pursue.'
+          nullable: true
+        allowedTools:
+          type: 'array'
+          items:
+            type: 'string'
+          description: 'The complete set of tools (by name) that this flow is permitted to use. This list is automatically populated by combining any explicitly specified allowedTools with tools from customTools and any tools referenced in toolCallsOnStart. Tools not in this list cannot be invoked during flow execution.'
+        resultJsonSchema:
+          type: 'object'
+          description: 'If non-null, the JSON schema that the result field will conform to.'
+          additionalProperties: true
+          nullable: true
+        result:
+          type: 'object'
+          description: "The final output of the flow, populated when the flow reaches a terminal state. The content depends on how the flow completes:\n(1) If the flow succeeds and resultJsonSchema is specified, contains an object conforming to that schema extracted from the flow context;\n(2) If resultJsonSchema extraction fails, contains error details about the extraction failure;\n(3) Otherwise, contains the metadata from the final tool call, or null if no tools were executed."
+          additionalProperties: true
+          nullable: true
+        inputTokensUsed:
+          type: 'number'
+          description: 'The number of LLM input tokens used during this flow.'
+        completionTokensUsed:
+          type: 'number'
+          description: 'The number of LLM completion tokens used during this flow.'
+        maxToolCalls:
+          type: 'number'
+          description: 'If non-null, the maximum number of tool calls allowed for this flow.'
+          nullable: true
+        startedAt:
+          type: 'number'
+          description: 'The Unix epoch millisecond timestamp of when the flow started.'
+          nullable: true
+        completedAt:
+          type: 'number'
+          description: 'The Unix epoch millisecond timestamp of when the flow completed.'
+          nullable: true
+        state:
+          $ref: '#/components/schemas/State'
+        nextState:
+          $ref: '#/components/schemas/State'
+          nullable: true
+    PaginatedFlowMetadata:
+      type: 'object'
+      description: 'A paginated list of flow metadata objects.'
+      properties:
+        items:
+          type: 'array'
+          items:
+            $ref: '#/components/schemas/FlowMetadata'
+        nextPageToken:
+          type: 'string'
+          description: 'A token that can be used to retrieve the next page of results. If absent, there are no more results.'
+    State:
+      type: 'string'
+      description: "Represents the possible states of a flow:\n - UNSTARTED: Flow created but not yet initialized.\n - INITIALIZING: Setting up browser context and initial state.\n - RUNNING_ACTION: Executing a tool call.\n - QUERYING_LLM_FOR_NEXT_ACTION: AI determining next action (AUTONOMOUS mode).\n - WAITING_ON_USER_FOR_NEXT_ACTION: Waiting for user input (INSTRUCT mode).\n - PAUSED: Flow execution temporarily suspended.\n - RESUMING: Transitioning from paused to active state.\n - FAILED: Flow terminated unsuccessfully.\n - SUCCESS: Flow completed successfully."
+      enum:
+        - 'UNSTARTED'
+        - 'INITIALIZING'
+        - 'QUERYING_LLM_FOR_NEXT_ACTION'
+        - 'WAITING_ON_USER_FOR_NEXT_ACTION'
+        - 'PAUSED'
+        - 'RESUMING'
+        - 'RUNNING_ACTION'
+        - 'FAILED'
+        - 'SUCCESS'
+    RunMode:
+      type: 'string'
+      description: "The execution mode that determines how a flow operates and makes decisions:\n\n- AUTONOMOUS: The flow is driven by an AI agent (GPT) that autonomously decides what actions to\n              take based on the overall objective. The AI analyzes the current page state,\n              determines the next appropriate action, and executes it without human intervention.\n              This mode requires a valid GPT client configuration.\n\n- INSTRUCT: The flow waits for explicit user instructions for each action. The user manually\n            directs what tools to call and when, making this mode suitable for guided walkthroughs\n            or when human oversight is required for each step. No GPT client is required.\n\n- DETERMINISTIC: The flow executes a predetermined sequence of actions without any decision-making.\n                 It runs through a fixed list of tool calls (typically from toolCallsOnStart) and\n                 completes when all actions are finished. This mode is commonly used for replaying\n                 previously recorded flows or executing scripted sequences."
+      enum:
+        - 'AUTONOMOUS'
+        - 'INSTRUCT'
+        - 'DETERMINISTIC'
+    BrowserConfig:
+      type: 'object'
+      properties:
+        initialState:
+          $ref: '#/components/schemas/BrowserStateReference'
+          description: 'When starting the flow, initialize the browser state from here.'
+        persistState:
+          type: 'boolean'
+          description: 'If set to true, saves the browser state at the end of the flow.'
+        using:
+          description: 'Browser configuration type and settings.'
+          oneOf:
+            - $ref: '#/components/schemas/DeviceBrowser'
+            - $ref: '#/components/schemas/RemoteInstanceBrowser'
+            - $ref: '#/components/schemas/BrowserBaseBrowser'
+          discriminator:
+            propertyName: 'type'
+    DeviceBrowser:
+      type: 'object'
+      description: 'Configuration for using a local device browser.'
+      properties:
+        type:
+          type: 'string'
+          description: 'Use a local device browser.'
+          enum: ['device']
+        deviceName:
+          type: 'string'
+          description: "The name of the device to run the flow with. See devices.json for details. If not specified, defaults to 'Desktop Chromium'."
+        headless:
+          type: 'boolean'
+          description: 'If true, will not open a real browser window to perform the flow.'
+        proxy:
+          type: 'object'
+          description: 'Optional network proxy configuration.'
+          properties:
+            server:
+              type: 'string'
+            bypass:
+              type: 'string'
+            username:
+              type: 'string'
+              description: 'Will default to process.env.PROXY_USERNAME.'
+            password:
+              type: 'string'
+              description: 'Will default to process.env.PROXY_PASSWORD.'
+      required:
+        - 'type'
+    RemoteInstanceBrowser:
+      type: 'object'
+      description: 'Configuration for connecting to a remote browser instance.'
+      properties:
+        type:
+          type: 'string'
+          description: 'Connect to a remote browser instance.'
+          enum: ['remoteInstance']
+        url:
+          type: 'string'
+          description: 'The URL of a remote browser instance to connect to using the Chrome DevTools Protocol (CDP).'
+      required:
+        - 'type'
+        - 'url'
+    BrowserBaseBrowser:
+      type: 'object'
+      description: 'Configuration for using the BrowserBase cloud browser service.'
+      properties:
+        type:
+          type: 'string'
+          description: 'Use BrowserBase cloud browser service.'
+          enum: ['browserBase']
+        sessionArgs:
+          $ref: '#/components/schemas/BrowserBaseSessionArgs'
+      required:
+        - 'type'
+        - 'sessionArgs'
+    BrowserBaseSessionArgs:
+      type: 'object'
+      description: 'Configuration arguments for the BrowserBase session.'
+      properties:
+        projectId:
+          type: 'string'
+          description: 'The project ID for the BrowserBase session.'
+        extensionId:
+          type: 'string'
+          description: 'Optional extension ID.'
+        browserSettings:
+          type: 'object'
+          description: 'Browser-specific settings.'
+          properties:
+            context:
+              type: 'object'
+              description: 'Browser context settings.'
+              properties:
+                id:
+                  type: 'string'
+                  description: 'Context ID.'
+            extensionId:
+              type: 'string'
+              description: 'Extension ID in browser settings.'
+            viewport:
+              type: 'object'
+              description: 'Viewport dimensions.'
+              properties:
+                width:
+                  type: 'number'
+                  description: 'Viewport width in pixels.'
+                height:
+                  type: 'number'
+                  description: 'Viewport height in pixels.'
+            blockAds:
+              type: 'boolean'
+              description: 'Whether to block advertisements.'
+            solveCaptchas:
+              type: 'boolean'
+              description: 'Whether to automatically solve captchas.'
+            advancedStealth:
+              type: 'boolean'
+              description: 'Whether to enable advanced stealth mode.'
+        timeout:
+          type: 'number'
+          description: 'Duration in seconds after which the session will automatically end.'
+        keepAlive:
+          type: 'boolean'
+          description: 'Set to true to keep the session alive even after disconnections. Available on the Hobby Plan and above.'
+        proxies:
+          type: 'boolean'
+          description: 'Whether to use proxies.'
+        region:
+          type: 'string'
+          description: 'Geographic region for the browser session.'
+        userMetadata:
+          type: 'object'
+          description: 'Custom user metadata as key-value pairs.'
+          additionalProperties:
+            type: 'string'
+      required:
+        - 'projectId'
+    BrowserStateReference:
+      description: 'Specifies how to reference a flow from which to restore browser state.'
+      oneOf:
+        - $ref: '#/components/schemas/BrowserStateReferenceById'
+        - $ref: '#/components/schemas/BrowserStateReferenceByName'
+        - $ref: '#/components/schemas/BrowserStateReferenceByJson'
+      discriminator:
+        propertyName: 'type'
+    BrowserStateReferenceById:
+      type: 'object'
+      properties:
+        type:
+          type: 'string'
+          enum: ['id']
+        value:
+          type: 'string'
+          format: 'uuid'
+          description: 'The ID of the flow to restore state from.'
+      required:
+        - 'type'
+        - 'value'
+    BrowserStateReferenceByName:
+      type: 'object'
+      properties:
+        type:
+          type: 'string'
+          enum: ['name']
+        value:
+          type: 'string'
+          description: 'The name of the flow to restore state from.'
+      required:
+        - 'type'
+        - 'value'
+    BrowserStateReferenceByJson:
+      type: 'object'
+      properties:
+        type:
+          type: 'string'
+          enum: ['json']
+        value:
+          $ref: '#/components/schemas/BrowserStorageState'
+      required:
+        - 'type'
+        - 'value'
+    BrowserStorageState:
+      type: 'object'
+      description: 'Represents the storage state of a browser, including cookies and local/session storage for various origins.'
+      properties:
+        cookies:
+          type: 'array'
+          items:
+            type: 'object'
+            properties:
+              name:
+                type: 'string'
+              value:
+                type: 'string'
+              domain:
+                type: 'string'
+              path:
+                type: 'string'
+              expires:
+                type: 'number'
+                description: 'Epoch seconds, or -1 for session cookies.'
+              httpOnly:
+                type: 'boolean'
+              secure:
+                type: 'boolean'
+              sameSite:
+                type: 'string'
+                enum: ['Strict', 'Lax', 'None']
+        origins:
+          type: 'array'
+          items:
+            type: 'object'
+            properties:
+              origin:
+                type: 'string'
+              localStorage:
+                type: 'array'
+                items:
+                  type: 'object'
+                  properties:
+                    name:
+                      type: 'string'
+                    value:
+                      type: 'string'
+              sessionStorage:
+                type: 'array'
+                items:
+                  type: 'object'
+                  properties:
+                    name:
+                      type: 'string'
+                    value:
+                      type: 'string'
+    CustomTool:
+      type: 'object'
+      description: 'A definition of a user-defined tool to use for a DonobuFlow.'
+      properties:
+        name:
+          type: 'string'
+          description: 'The name of the user-defined tool.'
+        description:
+          type: 'string'
+          description: 'A description of what the tool does.'
+        inputSchema:
+          type: 'object'
+          description: 'The input schema definition for the tool as a JSON object.'
+          additionalProperties: true
+        javascript:
+          type: 'string'
+          description: 'The JavaScript code that implements the tool functionality.'
+      required:
+        - 'name'
+        - 'description'
+        - 'inputSchema'
+        - 'javascript'
+    ProposedToolCall:
+      type: 'object'
+      description: 'A proposed (i.e., yet to be executed) tool call.'
+      properties:
+        name:
+          type: 'string'
+          description: 'The name of the tool to call.'
+        parameters:
+          type: 'object'
+          description: "The parameters to supply to the tool's call method. Must conform to the tool's expected parameters type."
+          additionalProperties: true
+        toolCallId:
+          type: 'string'
+          description: 'The ID used by the GPT model to track a proposed tool call to a tool call result.'
+          nullable: true
+      required:
+        - 'name'
+        - 'parameters'
+    ToolCall:
+      type: 'object'
+      description: 'The record for a singular, completed, call for a tool. This is used for persistence and APIs.'
+      properties:
+        id:
+          type: 'string'
+          description: 'The ID for this singular call.'
+        toolName:
+          type: 'string'
+          description: 'The tool name of the tool called.'
+        parameters:
+          type: 'object'
+          description: 'The parameters supplied to the tool.'
+          additionalProperties: true
+        outcome:
+          $ref: '#/components/schemas/ToolCallResult'
+        postCallImageId:
+          type: 'string'
+          description: 'The ID of the image of the page after the tool was called. If the page was closed during the tool call, this will be null.'
+          nullable: true
+        page:
+          type: 'string'
+          description: 'The URL of the webpage that the tool had focus on when running.'
+        startedAt:
+          type: 'number'
+          description: 'The Unix epoch millisecond timestamp of the instant the tool was called.'
+        completedAt:
+          type: 'number'
+          description: 'The Unix epoch millisecond timestamp of the instant the tool completed.'
+    ToolCallResult:
+      type: 'object'
+      description: 'Response wrapper object for a tool call.'
+      properties:
+        isSuccessful:
+          type: 'boolean'
+          description: 'Indicates if the tool call should be considered a success.'
+        forLlm:
+          type: 'string'
+          description: 'The data to return back to the LLM so that it knows the outcome of this tool call.'
+        metadata:
+          type: 'object'
+          description: 'Metadata to record, but will not be shared with the LLM.'
+          additionalProperties: true
+          nullable: true
+    CodeGenerationOptions:
+      type: 'object'
+      properties:
+        areElementIdsVolatile:
+          type: 'boolean'
+          description: "If true, ID-only selectors (e.g. '#submit-btn') are *dropped* because the element's 'id' attribute is considered volatile. When every candidate is ID-based the list is left unchanged (something is better than nothing)."
+        disableSelectorFailover:
+          type: 'boolean'
+          description: 'If false, only the **first** selector (the most specific one) is used, disabling automatic fail-over to broader selectors.'
+        disableSelfHealingTests:
+          type: 'boolean'
+          description: 'Disable self-healing tests.'
+        disablePullRequestCreation:
+          type: 'boolean'
+          description: 'Disable the automatic creation of pull requests for tests that have self healed.'
+        runInHeadedMode:
+          type: 'boolean'
+          description: 'Run tests with visible browser windows instead of headless mode. Useful for debugging and demos.'
+        slowMotionDelay:
+          type: 'number'
+          description: 'Delay in milliseconds between actions. Set to 0 to disable slow motion. Useful for debugging and demos.'
+          minimum: 0
+    GptConfig:
+      description: 'A resource structure that can be used to establish connectivity with a particular GPT platform and model. If there are an `apiKey`, and/or a `secretAccessKey` fields, they will be redacted before being returned through the API.'
+      oneOf:
+        - $ref: '#/components/schemas/AnthropicConfig'
+        - $ref: '#/components/schemas/AnthropicAwsBedrockConfig'
+        - $ref: '#/components/schemas/GoogleGenerativeAiConfig'
+        - $ref: '#/components/schemas/GoogleVertexConfig'
+        - $ref: '#/components/schemas/OpenAiConfig'
+      discriminator:
+        propertyName: 'type'
+    AnthropicConfig:
+      type: 'object'
+      properties:
+        type:
+          type: 'string'
+          enum: ['ANTHROPIC']
+        apiKey:
+          type: 'string'
+          writeOnly: true
+        modelName:
+          type: 'string'
+      required:
+        - 'type'
+        - 'apiKey'
+        - 'modelName'
+    AnthropicAwsBedrockConfig:
+      type: 'object'
+      properties:
+        type:
+          type: 'string'
+          enum: ['ANTHROPIC_AWS_BEDROCK']
+        region:
+          type: 'string'
+        accessKeyId:
+          type: 'string'
+          writeOnly: true
+        secretAccessKey:
+          type: 'string'
+          writeOnly: true
+        modelName:
+          type: 'string'
+      required:
+        - 'type'
+        - 'modelName'
+    GoogleGenerativeAiConfig:
+      type: 'object'
+      properties:
+        type:
+          type: 'string'
+          enum: ['GOOGLE_GEMINI']
+        apiKey:
+          type: 'string'
+          writeOnly: true
+        modelName:
+          type: 'string'
+      required:
+        - 'type'
+        - 'apiKey'
+        - 'modelName'
+    GoogleVertexConfig:
+      type: 'object'
+      properties:
+        type:
+          type: 'string'
+          enum: ['GOOGLE_VERTEX']
+        modelName:
+          type: 'string'
+        project:
+          type: 'string'
+        location:
+          type: 'string'
+        baseURL:
+          type: 'string'
+      required:
+        - 'type'
+        - 'modelName'
+    OpenAiConfig:
+      type: 'object'
+      properties:
+        type:
+          type: 'string'
+          enum: ['OPENAI']
+        apiKey:
+          type: 'string'
+          writeOnly: true
+        modelName:
+          type: 'string'
+      required:
+        - 'type'
+        - 'apiKey'
+        - 'modelName'
+    DonobuAgent:
+      type: 'string'
+      enum:
+        - 'flow-runner'
+    ToolDefinition:
+      type: 'object'
+      description: 'Defines an available tool.'
+      properties:
+        name:
+          type: 'string'
+          description: 'The unique name of the tool.'
+        description:
+          type: 'string'
+          description: 'A description of what the tool does and when to use it.'
+        inputSchema:
+          type: 'object'
+          description: 'A JSON Schema defining the input parameters for the tool.'
+          additionalProperties: true
+        requiresGpt:
+          type: 'boolean'
+          description: 'Whether this tool requires a configured GPT client to function.'
+    ErrorResponse:
+      type: 'object'
+      description: 'A standardized error response.'
+      properties:
+        code:
+          type: 'string'
+          description: 'A machine-readable error code.'
+        message:
+          type: 'string'
+          description: 'A human-readable description of the error.'
+      required:
+        - 'code'
+        - 'message'