> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Suites & Flows API

> Create and list test suites and flows programmatically

These endpoints allow you to manage test suites and flows via the API. All requests require an API key in the `X-API-Key` header. See [API Reference](/docs/api-reference.md) for authentication details.

## Suites

### List Suites

Get all test suites for your organization.

> [!NOTE]
>
> **GET** `/api/v1/suites` — Returns `200 OK`

#### Example Request

```bash theme={null}
curl -X GET https://backend.usebugradar.com/api/v1/suites \
  -H "X-API-Key: YOUR_API_KEY"
```

#### Response Fields

**suites** `array`

List of suite objects

**Suite object**

**id** `string`

Unique identifier (UUID)

**name** `string`

Name of the suite

**description** `string | null`

Description of what the suite tests

**instructions** `string | null`

Free-form **suite-level context** injected into the AI agent's system prompt for every flow run in the suite. See [Suite Context](/docs/suites.md#suite-context).

**setup\_flow\_id** `string | null`

UUID of the authentication setup flow, if the suite has auth instructions configured

**auth\_instructions** `string | null`

The authentication/login instructions for the suite's setup flow, if configured

**created\_at** `string`

ISO 8601 timestamp of when the suite was created

**created\_by** `object | null`

Who created the suite, as `{ id, name, type }` (`type` is always `user`). `null` for older suites.

**count** `integer`

Total number of suites returned

#### Example Response

```json theme={null}
{
  "suites": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Login Feature Tests",
      "description": "Tests for user authentication",
      "instructions": "Treat the welcome tour as expected on a fresh login — dismiss it and continue.",
      "setup_flow_id": "770e8400-e29b-41d4-a716-446655440099",
      "auth_instructions": "Tap Login\nEnter ${env:USERNAME}\nEnter ${env:PASSWORD}\nTap Submit",
      "created_at": "2025-01-15T10:30:00Z",
      "created_by": { "id": "990e8400-e29b-41d4-a716-446655440088", "name": "Ada Lovelace", "type": "user" }
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "name": "Checkout Flow Tests",
      "description": null,
      "instructions": null,
      "setup_flow_id": null,
      "auth_instructions": null,
      "created_at": "2025-01-14T09:00:00Z",
      "created_by": null
    }
  ],
  "count": 2
}
```

***

### Create Suite

Create a new test suite to organize your flows.

> [!NOTE]
>
> **POST** `/api/v1/suites` — Returns `201 Created`

#### Request Body

**name** `string` *required*

Name of the test suite (1-255 characters)

**description** `string`

Optional description of what the suite tests

**instructions** `string`

Optional free-form **suite-level context** that gets injected into the AI agent's system prompt for every flow run in the suite. Use this for product knowledge, conventions, or constraints that apply to all flows in the suite — e.g. *"All flows assume the user is already onboarded; if you see the welcome tour, dismiss it."* This is not executed as a flow; for actions that should run before each flow, use `auth_instructions` instead. See [Suite Context](/docs/suites.md#suite-context).

**auth\_instructions** `string`

Optional login/authentication instructions that run before each flow in the suite. Use `${env:VAR_NAME}` placeholders for sensitive values like credentials — configure these in your [Environment Settings](https://usebugradar.com/settings?tab=environments).

#### Example Request

```bash theme={null}
curl -X POST https://backend.usebugradar.com/api/v1/suites \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "JIRA-1234: User Authentication",
    "description": "Auto-generated tests for login feature",
    "instructions": "Treat any \"Beta\" badge in the UI as expected — do not fail because of it.",
    "auth_instructions": "Tap Login\nEnter ${env:USERNAME} into the username field\nEnter ${env:PASSWORD} into the password field\nTap Submit"
  }'
```

#### Response Fields

**id** `string`

Unique identifier (UUID) of the created suite

**name** `string`

Name of the suite

**description** `string | null`

Description of what the suite tests

**instructions** `string | null`

Suite-level context echoed back when `instructions` was provided.

**setup\_flow\_id** `string | null`

UUID of the authentication setup flow. Present when `auth_instructions` was provided.

**auth\_instructions** `string | null`

The authentication/login instructions for the suite's setup flow. Echoed back when `auth_instructions` was provided.

**created\_at** `string`

ISO 8601 timestamp of when the suite was created

**created\_by** `object | null`

Who created the suite, as `{ id, name, type }` (`type` is always `user`). `null` for older suites.

#### Example Response

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "JIRA-1234: User Authentication",
  "description": "Auto-generated tests for login feature",
  "instructions": "Treat any \"Beta\" badge in the UI as expected — do not fail because of it.",
  "setup_flow_id": "770e8400-e29b-41d4-a716-446655440099",
  "auth_instructions": "Tap Login\nEnter ${env:USERNAME} into the username field\nEnter ${env:PASSWORD} into the password field\nTap Submit",
  "created_at": "2025-01-15T10:30:00Z",
  "created_by": { "id": "990e8400-e29b-41d4-a716-446655440088", "name": "Ada Lovelace", "type": "user" }
}
```

***

### Get Suite

> [!NOTE]
>
> **GET** `/api/v1/suites/{suite_id}` — Returns `200 OK` (same shape as Create Suite), or `404` if the suite does not exist.

**suite\_id** `string` *required*

UUID of the suite.

```bash theme={null}
curl -X GET https://backend.usebugradar.com/api/v1/suites/SUITE_UUID \
  -H "X-API-Key: YOUR_API_KEY"
```

***

### Update Suite

Update any subset of a suite's fields — omitted fields are unchanged. Returns the same shape as Create Suite.

> [!NOTE]
>
> **PATCH** `/api/v1/suites/{suite_id}` — Returns `200 OK`. `400` if no recognized fields are provided. `404` if the suite does not exist.

**suite\_id** `string` *required*

UUID of the suite.

**name** `string`

New name (1-255 characters).

**description** `string | null`

New description. Pass `null` to clear.

**instructions** `string | null`

New suite-level context. Pass `null` to clear. See [Suite Context](/docs/suites.md#suite-context).

**auth\_instructions** `string`

New login instructions that run before each flow in the suite. Use `${env:VAR_NAME}` placeholders for credentials — configure them in your [Environment Settings](https://usebugradar.com/settings?tab=environments). To remove auth entirely, use the dashboard.

```bash theme={null}
curl -X PATCH https://backend.usebugradar.com/api/v1/suites/SUITE_UUID \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "instructions": "All flows assume the staging tenant; dismiss the welcome tour if it appears." }'
```

***

### Delete Suite

Deletes the suite. Flows inside the suite are **not** deleted — delete them separately if needed.

> [!NOTE]
>
> **DELETE** `/api/v1/suites/{suite_id}` — Returns `204 No Content`, or `404` if the suite does not exist.

**suite\_id** `string` *required*

UUID of the suite.

```bash theme={null}
curl -X DELETE https://backend.usebugradar.com/api/v1/suites/SUITE_UUID \
  -H "X-API-Key: YOUR_API_KEY"
```

***

## Flows

### List Flows

Get all test flows for your organization. Optionally filter by suite.

> [!NOTE]
>
> **GET** `/api/v1/flows` — Returns `200 OK`

#### Query Parameters

**suite\_id** `string`

Optional. Filter flows by suite ID to get only flows in a specific suite (ordered by position).

#### Example Request

```bash theme={null}
# Get all flows
curl -X GET https://backend.usebugradar.com/api/v1/flows \
  -H "X-API-Key: YOUR_API_KEY"

# Get flows in a specific suite
curl -X GET "https://backend.usebugradar.com/api/v1/flows?suite_id=550e8400-e29b-41d4-a716-446655440000" \
  -H "X-API-Key: YOUR_API_KEY"
```

#### Response Fields

**flows** `array`

List of flow objects

**Flow object**

**id** `string`

Unique identifier (UUID)

**name** `string`

Name of the flow

**instructions** `string`

Natural language test instructions

**caching\_mode** `string | null`

`off`, `standard`, or `aggressive`. `null` inherits the workspace mode. A flow cannot exceed its workspace’s mode.

**device\_count** `integer`

Number of devices required by the flow: `1` or `2`.

**created\_at** `string`

ISO 8601 timestamp of when the flow was created

**created\_by** `object | null`

Who created the flow, as `{ id, name, type }` (`type` is always `user`). `null` for older flows.

**count** `integer`

Total number of flows returned

#### Example Response

```json theme={null}
{
  "flows": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "name": "Login with valid credentials",
      "instructions": "Enter valid email and password, tap login, verify home screen",
      "caching_mode": null,
      "device_count": 1,
      "created_at": "2025-01-15T10:31:00Z",
      "created_by": { "id": "990e8400-e29b-41d4-a716-446655440088", "name": "Ada Lovelace", "type": "user" }
    },
    {
      "id": "660e8400-e29b-41d4-a716-446655440002",
      "name": "Login with invalid password",
      "instructions": "Enter valid email but wrong password, verify error message",
      "caching_mode": null,
      "device_count": 1,
      "created_at": "2025-01-15T10:32:00Z",
      "created_by": null
    }
  ],
  "count": 2
}
```

***

### Create Flow

Create a new test flow (test case). Optionally attach it to a suite.

> [!NOTE]
>
> **POST** `/api/v1/flows` — Returns `201 Created`

#### Request Body

**name** `string` *required*

Name of the test flow (1-255 characters)

**instructions** `string` *required*

Natural language instructions for the test. See [Writing Effective Flow Instructions](/docs/writing-effective-flow-instructions.md) for best practices.

**suite\_id** `string`

Optional UUID of a suite to attach this flow to. The flow will be added to the end of the suite.

**caching\_mode** `string | null`

`off`, `standard`, or `aggressive`. Omit or pass `null` to inherit the workspace mode. A flow can reduce the workspace mode, never exceed it.

**device\_count** `integer` (default: 1)

Number of devices the agent controls. Allowed values are `1` and `2`. A flow
attached to a suite must match every member and auth flow in that suite.

#### Example Request

```bash theme={null}
curl -X POST https://backend.usebugradar.com/api/v1/flows \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Login with valid credentials",
    "instructions": "1. Tap the Sign In button\n2. Enter test@example.com in the email field\n3. Enter password123 in the password field\n4. Tap the Login button\n5. Verify that the home screen appears with Welcome message",
    "suite_id": "550e8400-e29b-41d4-a716-446655440000",
    "device_count": 2
  }'
```

#### Response Fields

**id** `string`

Unique identifier (UUID) of the created flow

**name** `string`

Name of the flow

**instructions** `string`

Natural language test instructions

**caching\_mode** `string | null`

`off`, `standard`, or `aggressive`. Defaults to `null`, which inherits the workspace mode.

**device\_count** `integer`

Number of devices required by the flow: `1` or `2`.

**suite\_id** `string | null`

UUID of the suite this flow belongs to (if attached)

**position** `integer | null`

Position of this flow within the suite (0-indexed, if attached)

**created\_at** `string`

ISO 8601 timestamp of when the flow was created

**created\_by** `object | null`

Who created the flow, as `{ id, name, type }` (`type` is always `user`). `null` for older flows.

#### Example Response

```json theme={null}
{
  "id": "660e8400-e29b-41d4-a716-446655440001",
  "name": "Login with valid credentials",
  "instructions": "1. Tap the Sign In button\n2. Enter test@example.com in the email field\n3. Enter password123 in the password field\n4. Tap the Login button\n5. Verify that the home screen appears with Welcome message",
  "caching_mode": null,
  "suite_id": "550e8400-e29b-41d4-a716-446655440000",
  "position": 0,
  "created_at": "2025-01-15T10:31:00Z",
  "created_by": { "id": "990e8400-e29b-41d4-a716-446655440088", "name": "Ada Lovelace", "type": "user" }
}
```

***

### Get Flow

> [!NOTE]
>
> **GET** `/api/v1/flows/{flow_id}` — Returns `200 OK` with the same shape as items in [List Flows](#list-flows), or `404` if the flow does not exist.

**flow\_id** `string` *required*

UUID of the flow.

```bash theme={null}
curl -X GET https://backend.usebugradar.com/api/v1/flows/FLOW_UUID \
  -H "X-API-Key: YOUR_API_KEY"
```

***

### Update Flow

Update any subset of a flow's fields — omitted fields are unchanged. Returns the same shape as items in [List Flows](#list-flows).

> [!TIP]
>
> To move a flow from one suite to another, use [Add Flow to Suite](#add-flow-to-suite) on the target suite and [Remove Flow from Suite](#remove-flow-from-suite) on the source suite. Run history is preserved.

> [!NOTE]
>
> **PATCH** `/api/v1/flows/{flow_id}` — Returns `200 OK`. `400` if no recognized fields are provided. `404` if the flow does not exist.

**flow\_id** `string` *required*

UUID of the flow.

**name** `string`

New name (1-255 characters).

**instructions** `string`

Natural-language test instructions.

**device\_count** `integer`

New device requirement: `1` or `2`. The update is rejected when it would make
a suite's member or auth flow counts inconsistent.

```bash theme={null}
curl -X PATCH https://backend.usebugradar.com/api/v1/flows/FLOW_UUID \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "instructions": "1. Tap Sign In\n2. Enter the email\n3. Tap Submit" }'
```

***

### Delete Flow

Deletes the flow. Past runs are preserved.

> [!NOTE]
>
> **DELETE** `/api/v1/flows/{flow_id}` — Returns `204 No Content`, or `404` if the flow does not exist.

**flow\_id** `string` *required*

UUID of the flow.

```bash theme={null}
curl -X DELETE https://backend.usebugradar.com/api/v1/flows/FLOW_UUID \
  -H "X-API-Key: YOUR_API_KEY"
```

***

## Suite Membership

Move a flow between suites without losing run history.

### Add Flow to Suite

Attaches an existing flow to the end of a suite.

> [!NOTE]
>
> **POST** `/api/v1/suites/{suite_id}/flows/{flow_id}` — Returns `201 Created`. `404` if the suite or flow does not exist. `409` if the flow is already in the suite.

**suite\_id** `string` *required*

UUID of the suite.

**flow\_id** `string` *required*

UUID of the flow to attach.

#### Response Fields

**suite\_id** `string`

UUID of the suite the flow was attached to.

**flow\_id** `string`

UUID of the flow that was attached.

**position** `integer`

0-indexed position the flow was placed at — always the next slot at the end of the suite.

```bash theme={null}
curl -X POST https://backend.usebugradar.com/api/v1/suites/SUITE_UUID/flows/FLOW_UUID \
  -H "X-API-Key: YOUR_API_KEY"
```

#### Example Response

```json theme={null}
{
  "suite_id": "550e8400-e29b-41d4-a716-446655440000",
  "flow_id": "660e8400-e29b-41d4-a716-446655440001",
  "position": 3
}
```

***

### Remove Flow from Suite

Detaches a flow from a suite. The flow itself is **not** deleted.

> [!NOTE]
>
> **DELETE** `/api/v1/suites/{suite_id}/flows/{flow_id}` — Returns `204 No Content`. `404` if the suite does not exist, or if the flow is not in this suite.

**suite\_id** `string` *required*

UUID of the suite.

**flow\_id** `string` *required*

UUID of the flow to detach.

```bash theme={null}
curl -X DELETE https://backend.usebugradar.com/api/v1/suites/SUITE_UUID/flows/FLOW_UUID \
  -H "X-API-Key: YOUR_API_KEY"
```

***

## Example Workflow

Here's a typical workflow for creating a test suite with multiple test cases:

**1. Create a Suite**

First, create a suite to organize your test cases. If your app requires login, include `auth_instructions` — these run automatically before each flow:

```bash theme={null}
curl -X POST https://backend.usebugradar.com/api/v1/suites \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Login Feature Tests",
    "auth_instructions": "Tap Sign In\nEnter ${env:USERNAME}\nEnter ${env:PASSWORD}\nTap Submit"
  }'
```

Save the returned `id` for the next step.

**2. Create Flows**

Create test flows and attach them to the suite:

```bash theme={null}
# Positive test case
curl -X POST https://backend.usebugradar.com/api/v1/flows \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Login with valid credentials",
    "instructions": "Enter valid email and password, tap login, verify home screen appears",
    "suite_id": "SUITE_ID_FROM_STEP_1"
  }'

# Negative test case
curl -X POST https://backend.usebugradar.com/api/v1/flows \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Login with invalid password",
    "instructions": "Enter valid email but wrong password, tap login, verify error message appears",
    "suite_id": "SUITE_ID_FROM_STEP_1"
  }'
```

**3. Run Tests**

Run your tests from the [Flows page](https://usebugradar.com/flows), trigger them via the [Runs API](/docs/api-runs.md) (auth instructions run automatically for individual flows), or set up [Automations](/docs/automations.md) to run them on a schedule.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.