API Reference

Comprehensive reference for the Donobu API, including endpoints for flows, configurations, agents, and tools.

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.

The API runs locally on http://localhost:31000 when you have the Donobu Studio app running.

Flows

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.

List all flows

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.

GET /api/flows

Query Parameters

Name	Type	Description
`name`	string	Filter flows by exact name match.
`startedAfter`	integer (int64)	Filter for flows that started at or after this Unix epoch timestamp (in milliseconds).
`startedBefore`	integer (int64)	Filter for flows that started at or before this Unix epoch timestamp (in milliseconds).
`runMode`	string	Filter flows by their run mode (`AUTONOMOUS`, `INSTRUCT`, `DETERMINISTIC`).
`state`	string	Filter flows by their current state.
`limit`	integer	The maximum number of flows to return. Must be between 1 and 100. Defaults to 100.
`pageToken`	string	A token for fetching the next page of results.

Response

Returns a paginated list of flow metadata.

Create a new flow

Creates and initiates a new automation flow based on the provided configuration. The flow will start executing immediately.

POST /api/flows

Request Body

The request body must contain a CreateDonobuFlow object.

{
  "name": "string",
  "targetWebsite": "string",
  "overallObjective": "string",
  "initialRunMode": "AUTONOMOUS | INSTRUCT | DETERMINISTIC",
  "browser": {
    "using": {
      "type": "device | remoteInstance | browserBase",
      // ... browser specific config
    }
  },
  "envVars": ["string"],
  "customTools": [
    {
      "name": "string",
      "description": "string",
      "inputSchema": {},
      "javascript": "string"
    }
  ],
  "maxToolCalls": 0,
  "gptConfigNameOverride": "string"
}

Response

Returns the initial metadata of the newly created flow.

Get flow metadata

Retrieves the complete metadata for a specific flow by its unique ID. This includes its current state, configuration, and results if completed.

GET /api/flows/{flowId}

Path Parameters

Name	Type	Description
`flowId`	string (uuid)	The unique identifier of the flow.

Delete a flow

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.

DELETE /api/flows/{flowId}

Path Parameters

Name	Type	Description
`flowId`	string (uuid)	The unique identifier of the flow to delete.

Rename a flow

Updates the name of a specific flow.

POST /api/flows/{flowId}/rename

Path Parameters

Name	Type	Description
`flowId`	string (uuid)	The unique identifier of the flow to rename.

Request Body

{
  "name": "New Flow Name"
}

Get flow as a rerun configuration

Generates a configuration object based on a previously executed flow. This configuration can be used to rerun the flow in DETERMINISTIC mode.

GET /api/flows/{flowId}/rerun

Path Parameters

Name	Type	Description
`flowId`	string (uuid)	The unique identifier of the flow.

Query Parameters

Name	Type	Description
`areElementIdsVolatile`	boolean	If true, ID-only selectors are dropped.
`disableSelectorFailover`	boolean	If false, only the most specific selector is used.

Get flow as Playwright script

Generates a Node.js Playwright script that replays the successful actions of a specified flow.

GET /api/flows/{flowId}/code

Path Parameters

Name	Type	Description
`flowId`	string (uuid)	The unique identifier of the flow.

Query Parameters

Name	Type	Description
`runInHeadedMode`	boolean	Run tests with visible browser windows.
`slowMotionDelay`	number	Delay in milliseconds between actions.
`disableSelfHealingTests`	boolean	Disable self-healing tests.

Get flows as Playwright project

Generates a complete, runnable Playwright project from a list of flow IDs.

POST /api/flows/project

Request Body

{
  "flowIds": ["uuid1", "uuid2"],
  "options": {
    "runInHeadedMode": true,
    "slowMotionDelay": 100
  }
}

Response

Returns a zip archive containing the generated Playwright project.

Get a flow screenshot

Retrieves a specific screenshot image (in PNG format) associated with a flow.

GET /api/flows/{flowId}/images/{imageId}

Get flow video recording

Retrieves the video recording (in WebM format) of a flow run.

GET /api/flows/{flowId}/video

List tool calls for a flow

Retrieves a list of all tool calls that were executed during a specific flow run.

GET /api/flows/{flowId}/tool-calls

Get a specific tool call

Retrieves the details of a single tool call from a flow run.

GET /api/flows/{flowId}/tool-calls/{toolCallId}

Configs

Endpoints for managing configurations used by flows, including GPT model settings and environment variables.

List all GPT configurations

Retrieves a list of all saved GPT configurations.

GET /api/gpt-configs

Get a GPT configuration

Retrieves a specific GPT configuration by its name.

GET /api/gpt-configs/{name}

Create or update a GPT configuration

Creates a new GPT configuration or updates an existing one.

POST /api/gpt-configs/{name}

Request Body

{
  "type": "OPENAI | ANTHROPIC | GOOGLE_GEMINI | ...",
  "apiKey": "string",
  "modelName": "string"
}

Delete a GPT configuration

Deletes a GPT configuration by its name.

DELETE /api/gpt-configs/{name}

List all environment data

Retrieves all stored environment variables as a key-value map.

GET /api/env

Get an environment datum

Retrieves the value of a specific environment variable.

GET /api/env/{key}

Set an environment datum

Creates or updates an environment variable.

POST /api/env/{key}

Request Body

{
  "value": "string"
}

Delete an environment datum

Deletes an environment variable.

DELETE /api/env/{key}

Agents

Endpoints for managing AI agents and assigning them specific GPT configurations.

List all agent assignments

Retrieves a map of all agents and their assigned GPT configurations.

GET /api/agents

Get an agent's assigned GPT configuration

Retrieves the name of the GPT configuration assigned to a specific agent.

GET /api/agents/{name}

Assign a GPT configuration to an agent

Assigns a specific GPT configuration to an agent.

POST /api/agents/{name}

Request Body

{
  "gptConfigName": "string"
}

Tools

Endpoints for discovering the browser automation tools available for use within flows.

List available tools

Retrieves a list of all built-in tools.

GET /api/tools

System

Endpoints for system-level operations.

Get API version

Retrieves the current version of the Donobu application.

GET /api/version

Ping the API

A simple health check endpoint.

GET /api/ping