Donobu API

The Donobu API is the local REST API that powers Donobu Studio and the Donobu Playwright Extension. Most users interact with Donobu through one of these products rather than calling the API directly.

If you're looking for guidance on when to use the API, see the API Introduction.

The API runs locally at http://localhost:31000 when Donobu Studio is running. This page is the complete endpoint reference.

In this section

• Introduction — What the API is, when to use it directly
• Configuration — GPT providers, environment variables, browser settings
• Working with Flows — Creating, monitoring, and managing flows
• MCP Server — Bridge between AI IDEs and Donobu Studio

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

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

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

Rename a flow

Updates the name of a specific flow.

POST /api/flows/{flowId}/rename

Path Parameters

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

Query Parameters

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

Query Parameters

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