Skip to main content
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
​
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",
      "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

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

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

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

​
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

​
id
string
Unique identifier (UUID) of the created flow
​
name
string
Name of the flow
​
instructions
string
Natural language test instructions
​
caching_enabled
boolean
Always false for flows created via this endpoint. Enable from the dashboard if you want caching.
​
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

{
  "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.
​
flow_id
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.
​
flow_id
string
required
UUID of the flow.
​
name
string
New name (1-255 characters).
​
instructions
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.
​
flow_id
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.
​
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.
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.
​
suite_id
string
required
UUID of the suite.
​
flow_id
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:
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:
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.
2

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

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.