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

array

List of suite objects

Show Suite object

string

Unique identifier (UUID)

string

Name of the suite

string | null

Description of what the suite tests

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.

string | null

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

string | null

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

string

ISO 8601 timestamp of when the suite was created

object | null

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

integer

Total number of suites returned

Example Response

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

POST /api/v1/suites — Returns 201 Created

Request Body

string

required

Name of the test suite (1-255 characters)

string

Optional description of what the suite tests

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.

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",
    "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

string

Unique identifier (UUID) of the created suite

string

Name of the suite

string | null

Description of what the suite tests

string | null

Suite-level context echoed back when instructions was provided.

string | null

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

string | null

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

string

ISO 8601 timestamp of when the suite was created

object | null

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

Example Response

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

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

string

required

UUID of the suite.

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.

PATCH /api/v1/suites/{suite_id} — Returns 200 OK. 400 if no recognized fields are provided. 404 if the suite does not exist.

string

required

UUID of the suite.

string

New name (1-255 characters).

string | null

New description. Pass null to clear.

string | null

New suite-level context. Pass null to clear. See Suite Context.

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. To remove auth entirely, use the dashboard.

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.

DELETE /api/v1/suites/{suite_id} — Returns 204 No Content, or 404 if the suite does not exist.

string

required

UUID of the suite.

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.

GET /api/v1/flows — Returns 200 OK

Query Parameters

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

array

List of flow objects

Show Flow object

string

Unique identifier (UUID)

string

Name of the flow

string

Natural language test instructions

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.

string

ISO 8601 timestamp of when the flow was created

object | null

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

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

POST /api/v1/flows — Returns 201 Created

Request Body

string

required

Name of the test flow (1-255 characters)

string

required

Natural language instructions for the test. See Writing Effective Flow Instructions for best practices.

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

string

Name of the flow

string

Natural language test instructions

boolean

Always false for flows created via this endpoint. Enable from the dashboard if you want caching.

string | null

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

integer | null

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

string

ISO 8601 timestamp of when the flow was created

object | null

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

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",
  "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

GET /api/v1/flows/{flow_id} — Returns 200 OK with the same shape as items in List Flows, or 404 if the flow does not exist.

string

required

UUID of the flow.

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.

To move a flow from one suite to another, use Add Flow to Suite on the target suite and Remove Flow from Suite on the source suite. Run history is preserved.

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

string

required

UUID of the flow.

string

New name (1-255 characters).

string

Natural-language test instructions.

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.

DELETE /api/v1/flows/{flow_id} — Returns 204 No Content, or 404 if the flow does not exist.

string

required

UUID of the flow.

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.

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.

string

required

UUID of the suite.

string

required

UUID of the flow to attach.

Response Fields

string

UUID of the suite the flow was attached to.

string

UUID of the flow that was attached.

integer

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

curl -X POST https://backend.autosana.ai/api/v1/suites/SUITE_UUID/flows/FLOW_UUID \
  -H "X-API-Key: YOUR_API_KEY"

Example Response

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

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.

string

required

UUID of the suite.

string

required

UUID of the flow to detach.

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:

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, trigger them via the Runs API (auth instructions run automatically for individual flows), or set up Automations to run them on a schedule.

​Suites

​List Suites

​Example Request

​Response Fields

​Example Response

​Create Suite

​Request Body

​Example Request

​Response Fields

​Example Response

​Get Suite

​Update Suite

​Delete Suite

​Flows

​List Flows

​Query Parameters

​Example Request

​Response Fields

​Example Response

​Create Flow

​Request Body

​Example Request

​Response Fields

​Example Response

​Get Flow

​Update Flow

​Delete Flow

​Suite Membership

​Add Flow to Suite

​Response Fields

​Example Response

​Remove Flow from Suite

​Example Workflow

Suites

List Suites

Example Request

Response Fields

Example Response

Create Suite

Request Body

Example Request

Response Fields

Example Response

Get Suite

Update Suite

Delete Suite

Flows

List Flows

Query Parameters

Example Request

Response Fields

Example Response

Create Flow

Request Body

Example Request

Response Fields

Example Response

Get Flow

Update Flow

Delete Flow

Suite Membership

Add Flow to Suite

Response Fields

Example Response

Remove Flow from Suite

Example Workflow