# Donobu API

## Reference documentation for the Donobu REST API, including endpoints for flows, configurations, agents, and tools.

The Donobu API is the local REST API that powers [Donobu Studio](/content/docs/studio/index.html) and the [Donobu Playwright Extension](/content/docs/playwright/index.html). 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](/content/docs/api/introduction/index.html).

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

### In this section

- [Introduction](/content/docs/api/introduction/index.html) — What the API is, when to use it directly
- [Configuration](/content/docs/api/configuration/index.html) — GPT providers, environment variables, browser settings
- [Working with Flows](/content/docs/api/working-with-flows/index.html) — Creating, monitoring, and managing flows
- [MCP Server](/content/docs/api/mcp-server/index.html) — 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**

| Name           | Type                    | Description                                              |
|----------------|-------------------------|----------------------------------------------------------|
| `name`         | string                  | Filter flows by exact name match.                       |
| `startedAfter` | integer (int64)        | Filter for flows that started at or after this timestamp.|
| `startedBefore`| integer (int64)        | Filter for flows that started at or before this timestamp.|
| `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.

```json
{
  "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**

```json
{
  "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**

**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**

```json
{
  "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**

```json
{
  "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**

```json
{
  "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**

```json
{
  "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`