> ## Documentation Index
> Fetch the complete documentation index at: https://docs.autosana.ai/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](/api-reference) for authentication details.

## Suites

### List Suites

Get all test suites for your organization.

<Note>
  **GET** `/api/v1/suites` — Returns `200 OK`
</Note>

#### Example Request

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

#### Response Fields

<ResponseField name="suites" type="array">
  List of suite objects

  <Expandable title="Suite object">
    <ResponseField name="id" type="string">
      Unique identifier (UUID)
    </ResponseField>

    <ResponseField name="name" type="string">
      Name of the suite
    </ResponseField>

    <ResponseField name="description" type="string | null">
      Description of what the suite tests
    </ResponseField>

    <ResponseField name="instructions" type="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](/suites#suite-context).
    </ResponseField>

    <ResponseField name="setup_flow_id" type="string | null">
      UUID of the authentication setup flow, if the suite has auth instructions configured
    </ResponseField>

    <ResponseField name="auth_instructions" type="string | null">
      The authentication/login instructions for the suite's setup flow, if configured
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of when the suite was created
    </ResponseField>

    <ResponseField name="created_by" type="object | null">
      Who created the suite, as `{ id, name, type }` (`type` is always `user`). `null` for older suites.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="count" type="integer">
  Total number of suites returned
</ResponseField>

#### 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`
</Note>

#### Request Body

<ParamField body="name" type="string" required>
  Name of the test suite (1-255 characters)
</ParamField>

<ParamField body="description" type="string">
  Optional description of what the suite tests
</ParamField>

<ParamField body="instructions" type="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](/suites#suite-context).
</ParamField>

<ParamField body="auth_instructions" type="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://autosana.ai/settings?tab=environments).
</ParamField>

#### Example Request

```bash theme={null}
curl -X POST https://backend.autosana.ai/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

<ResponseField name="id" type="string">
  Unique identifier (UUID) of the created suite
</ResponseField>

<ResponseField name="name" type="string">
  Name of the suite
</ResponseField>

<ResponseField name="description" type="string | null">
  Description of what the suite tests
</ResponseField>

<ResponseField name="instructions" type="string | null">
  Suite-level context echoed back when `instructions` was provided.
</ResponseField>

<ResponseField name="setup_flow_id" type="string | null">
  UUID of the authentication setup flow. Present when `auth_instructions` was provided.
</ResponseField>

<ResponseField name="auth_instructions" type="string | null">
  The authentication/login instructions for the suite's setup flow. Echoed back when `auth_instructions` was provided.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp of when the suite was created
</ResponseField>

<ResponseField name="created_by" type="object | null">
  Who created the suite, as `{ id, name, type }` (`type` is always `user`). `null` for older suites.
</ResponseField>

#### 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.
</Note>

<ParamField path="suite_id" type="string" required>
  UUID of the suite.
</ParamField>

```bash theme={null}
curl -X GET https://backend.autosana.ai/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.
</Note>

<ParamField path="suite_id" type="string" required>
  UUID of the suite.
</ParamField>

<ParamField body="name" type="string">
  New name (1-255 characters).
</ParamField>

<ParamField body="description" type="string | null">
  New description. Pass `null` to clear.
</ParamField>

<ParamField body="instructions" type="string | null">
  New suite-level context. Pass `null` to clear. See [Suite Context](/suites#suite-context).
</ParamField>

<ParamField body="auth_instructions" type="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://autosana.ai/settings?tab=environments). To remove auth entirely, use the dashboard.
</ParamField>

```bash theme={null}
curl -X PATCH https://backend.autosana.ai/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.
</Note>

<ParamField path="suite_id" type="string" required>
  UUID of the suite.
</ParamField>

```bash theme={null}
curl -X DELETE https://backend.autosana.ai/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`
</Note>

#### Query Parameters

<ParamField query="suite_id" type="string">
  Optional. Filter flows by suite ID to get only flows in a specific suite (ordered by position).
</ParamField>

#### Example Request

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

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

#### Response Fields

<ResponseField name="flows" type="array">
  List of flow objects

  <Expandable title="Flow object">
    <ResponseField name="id" type="string">
      Unique identifier (UUID)
    </ResponseField>

    <ResponseField name="name" type="string">
      Name of the flow
    </ResponseField>

    <ResponseField name="instructions" type="string">
      Natural language test instructions
    </ResponseField>

    <ResponseField name="caching_enabled" type="boolean">
      Whether action caching is enabled for this flow. Defaults to `false` for flows created via the API — enable from the dashboard if you want caching.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of when the flow was created
    </ResponseField>

    <ResponseField name="created_by" type="object | null">
      Who created the flow, as `{ id, name, type }` (`type` is always `user`). `null` for older flows.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="count" type="integer">
  Total number of flows returned
</ResponseField>

#### 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_enabled": false,
      "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_enabled": false,
      "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`
</Note>

#### Request Body

<ParamField body="name" type="string" required>
  Name of the test flow (1-255 characters)
</ParamField>

<ParamField body="instructions" type="string" required>
  Natural language instructions for the test. See [Writing Effective Flow Instructions](/flows#writing-effective-flow-instructions) for best practices.
</ParamField>

<ParamField body="suite_id" type="string">
  Optional UUID of a suite to attach this flow to. The flow will be added to the end of the suite.
</ParamField>

#### Example Request

```bash theme={null}
curl -X POST https://backend.autosana.ai/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"
  }'
```

#### Response Fields

<ResponseField name="id" type="string">
  Unique identifier (UUID) of the created flow
</ResponseField>

<ResponseField name="name" type="string">
  Name of the flow
</ResponseField>

<ResponseField name="instructions" type="string">
  Natural language test instructions
</ResponseField>

<ResponseField name="caching_enabled" type="boolean">
  Always `false` for flows created via this endpoint. Enable from the dashboard if you want caching.
</ResponseField>

<ResponseField name="suite_id" type="string | null">
  UUID of the suite this flow belongs to (if attached)
</ResponseField>

<ResponseField name="position" type="integer | null">
  Position of this flow within the suite (0-indexed, if attached)
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp of when the flow was created
</ResponseField>

<ResponseField name="created_by" type="object | null">
  Who created the flow, as `{ id, name, type }` (`type` is always `user`). `null` for older flows.
</ResponseField>

#### 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_enabled": false,
  "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.
</Note>

<ParamField path="flow_id" type="string" required>
  UUID of the flow.
</ParamField>

```bash theme={null}
curl -X GET https://backend.autosana.ai/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.
</Tip>

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

<ParamField path="flow_id" type="string" required>
  UUID of the flow.
</ParamField>

<ParamField body="name" type="string">
  New name (1-255 characters).
</ParamField>

<ParamField body="instructions" type="string">
  Natural-language test instructions.
</ParamField>

```bash theme={null}
curl -X PATCH https://backend.autosana.ai/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.
</Note>

<ParamField path="flow_id" type="string" required>
  UUID of the flow.
</ParamField>

```bash theme={null}
curl -X DELETE https://backend.autosana.ai/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.
</Note>

<ParamField path="suite_id" type="string" required>
  UUID of the suite.
</ParamField>

<ParamField path="flow_id" type="string" required>
  UUID of the flow to attach.
</ParamField>

#### Response Fields

<ResponseField name="suite_id" type="string">
  UUID of the suite the flow was attached to.
</ResponseField>

<ResponseField name="flow_id" type="string">
  UUID of the flow that was attached.
</ResponseField>

<ResponseField name="position" type="integer">
  0-indexed position the flow was placed at — always the next slot at the end of the suite.
</ResponseField>

```bash theme={null}
curl -X POST https://backend.autosana.ai/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.
</Note>

<ParamField path="suite_id" type="string" required>
  UUID of the suite.
</ParamField>

<ParamField path="flow_id" type="string" required>
  UUID of the flow to detach.
</ParamField>

```bash theme={null}
curl -X DELETE https://backend.autosana.ai/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:

<Steps>
  <Step title="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.autosana.ai/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.
  </Step>

  <Step title="Create Flows">
    Create test flows and attach them to the suite:

    ```bash theme={null}
    # Positive test case
    curl -X POST https://backend.autosana.ai/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.autosana.ai/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"
      }'
    ```
  </Step>

  <Step title="Run Tests">
    Run your tests from the [Flows page](https://autosana.ai/flows), trigger them via the [Runs API](/api-runs) (auth instructions run automatically for individual flows), or set up [Automations](/automations) to run them on a schedule.
  </Step>
</Steps>