Suites & Flows API

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 for authentication details.

Suites

List Suites

Get all test suites for your organization.

GET /api/v1/suites — Returns 200 OK

Example Request

curl -X GET https://backend.autosana.ai/api/v1/suites \
  -H "X-API-Key: YOUR_API_KEY"

Response Fields

suites

array

List of suite objects

Show Suite object

string

Unique identifier (UUID)

name

string

Name of the suite

description

string | null

Description of what the suite tests

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

count

integer

Total number of suites returned

Example Response

{
  "suites": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Login Feature Tests",
      "description": "Tests for user authentication",
      "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"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "name": "Checkout Flow Tests",
      "description": null,
      "setup_flow_id": null,
      "auth_instructions": null,
      "created_at": "2025-01-14T09:00:00Z"
    }
  ],
  "count": 2
}

Create Suite

Create a new test suite to organize your flows.

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

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.

Example Request

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",
    "auth_instructions": "Tap Login\nEnter ${env:USERNAME} into the username field\nEnter ${env:PASSWORD} into the password field\nTap Submit"
  }'

Response Fields

string

Unique identifier (UUID) of the created suite

name

string

Name of the suite

description

string | null

Description of what the suite tests

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

Example Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "JIRA-1234: User Authentication",
  "description": "Auto-generated tests for login feature",
  "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"
}

Flows

List Flows

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

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

# 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

flows

array

List of flow objects

Show Flow object

string

Unique identifier (UUID)

name

string

Name of the flow

instructions

string

Natural language test instructions

type

string

Flow type (currently always single-prompt)

caching_enabled

boolean

Whether caching is enabled for this flow

created_at

string

ISO 8601 timestamp of when the flow was created

count

integer

Total number of flows returned

Example Response

{
  "flows": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "name": "Login with valid credentials",
      "instructions": "Enter valid email and password, tap login, verify home screen",
      "type": "single-prompt",
      "caching_enabled": true,
      "created_at": "2025-01-15T10:31:00Z"
    },
    {
      "id": "660e8400-e29b-41d4-a716-446655440002",
      "name": "Login with invalid password",
      "instructions": "Enter valid email but wrong password, verify error message",
      "type": "single-prompt",
      "caching_enabled": true,
      "created_at": "2025-01-15T10:32:00Z"
    }
  ],
  "count": 2
}

Create Flow

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

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

Example Request

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

string

Unique identifier (UUID) of the created flow

name

string

Name of the flow

instructions

string

Natural language test instructions

type

string

Flow type (currently always single-prompt)

caching_enabled

boolean

Whether caching is enabled for this flow

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

Example Response

{
  "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",
  "type": "single-prompt",
  "caching_enabled": true,
  "suite_id": "550e8400-e29b-41d4-a716-446655440000",
  "position": 0,
  "created_at": "2025-01-15T10:31:00Z"
}

Example Workflow

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

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:

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.

Create Flows

Create test flows and attach them to the suite:

# 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"
  }'

Run Tests

Run your tests from the Flows page or set up Automations to run them on a schedule.

Getting Started

Core Features

Integrations

App Upload Guides

APIs

Suites & Flows API

Suites

List Suites

Example Request

Response Fields

Example Response

Create Suite

Request Body

Example Request

Response Fields

Example Response

Flows

List Flows

Query Parameters

Example Request

Response Fields

Example Response

Create Flow

Request Body

Example Request

Response Fields

Example Response

Example Workflow

Getting Started

Core Features

Integrations

App Upload Guides

APIs

Documentation Index

​Suites

​List Suites

​Example Request

​Response Fields

​Example Response

​Create Suite

​Request Body

​Example Request

​Response Fields

​Example Response

​Flows

​List Flows

​Query Parameters

​Example Request

​Response Fields

​Example Response

​Create Flow

​Request Body

​Example Request

​Response Fields

​Example Response

​Example Workflow

Suites

List Suites

Example Request

Response Fields

Example Response

Create Suite

Request Body

Example Request

Response Fields

Example Response

Flows

List Flows

Query Parameters

Example Request

Response Fields

Example Response

Create Flow

Request Body

Example Request

Response Fields

Example Response

Example Workflow