Create Test

curl --request POST \
  --url https://api.docketqa.com/test_blueprint/create \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "title": "<string>",
  "type": "<string>",
  "steps": [
    {
      "step_number": 123,
      "type": "<string>",
      "action": "<string>",
      "use_vision": true,
      "test_blueprint_module_id": 123,
      "api_request": {
        "url": "<string>",
        "method": "<string>",
        "headers": {},
        "body": {},
        "timeout": 123,
        "retries": 123,
        "backoff_seconds": 123,
        "should_refresh_page": true
      },
      "trigger_run_config": {
        "test_blueprint_id": 123
      },
      "attached_file_ids": [
        123
      ],
      "assert_images_count": 123,
      "disable_self_healing": true,
      "click_count": 123,
      "hold_start_duration": 123,
      "hold_end_duration": 123
    }
  ],
  "starting_url": "<string>",
  "starting_prompt": "<string>",
  "test_blueprint_category_id": 123,
  "folder_path": "<string>",
  "device_type": "<string>",
  "device_name": "<string>",
  "app_id": 123,
  "browser_zoom": 123,
  "viewport_width": 123,
  "viewport_height": 123,
  "num_retries": 123,
  "reset_browser_on_retry": true,
  "typing_speed": 123,
  "persist_self_healed": true,
  "file_download_mode": "<string>",
  "variables": [
    {
      "key": "<string>",
      "type": "<string>",
      "value": "<string>",
      "randomConfig": {}
    }
  ],
  "setup_module": 123,
  "teardown_module": 123,
  "status": "<string>",
  "credentials": {
    "username": "<string>",
    "password": "<string>",
    "otp_secret": "<string>"
  }
}
'

{
  "message": "<string>",
  "test_blueprint": {
    "id": 123,
    "company_id": 123,
    "title": "<string>",
    "type": "<string>",
    "device_type": "<string>",
    "starting_url": "<string>",
    "starting_prompt": "<string>",
    "test_blueprint_category_id": 123,
    "status": "<string>",
    "browser_zoom": 123,
    "viewport_width": 123,
    "viewport_height": 123,
    "num_retries": 123,
    "persist_self_healed": true,
    "file_download_mode": "<string>",
    "variables": [
      {}
    ],
    "setup_module": 123,
    "teardown_module": 123,
    "folder_path": "<string>",
    "steps": [
      {}
    ],
    "created_by": 123,
    "created_at": "<string>",
    "updated_at": "<string>"
  }
}

POST

test_blueprint

create

Create Test

curl --request POST \
  --url https://api.docketqa.com/test_blueprint/create \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "title": "<string>",
  "type": "<string>",
  "steps": [
    {
      "step_number": 123,
      "type": "<string>",
      "action": "<string>",
      "use_vision": true,
      "test_blueprint_module_id": 123,
      "api_request": {
        "url": "<string>",
        "method": "<string>",
        "headers": {},
        "body": {},
        "timeout": 123,
        "retries": 123,
        "backoff_seconds": 123,
        "should_refresh_page": true
      },
      "trigger_run_config": {
        "test_blueprint_id": 123
      },
      "attached_file_ids": [
        123
      ],
      "assert_images_count": 123,
      "disable_self_healing": true,
      "click_count": 123,
      "hold_start_duration": 123,
      "hold_end_duration": 123
    }
  ],
  "starting_url": "<string>",
  "starting_prompt": "<string>",
  "test_blueprint_category_id": 123,
  "folder_path": "<string>",
  "device_type": "<string>",
  "device_name": "<string>",
  "app_id": 123,
  "browser_zoom": 123,
  "viewport_width": 123,
  "viewport_height": 123,
  "num_retries": 123,
  "reset_browser_on_retry": true,
  "typing_speed": 123,
  "persist_self_healed": true,
  "file_download_mode": "<string>",
  "variables": [
    {
      "key": "<string>",
      "type": "<string>",
      "value": "<string>",
      "randomConfig": {}
    }
  ],
  "setup_module": 123,
  "teardown_module": 123,
  "status": "<string>",
  "credentials": {
    "username": "<string>",
    "password": "<string>",
    "otp_secret": "<string>"
  }
}
'

{
  "message": "<string>",
  "test_blueprint": {
    "id": 123,
    "company_id": 123,
    "title": "<string>",
    "type": "<string>",
    "device_type": "<string>",
    "starting_url": "<string>",
    "starting_prompt": "<string>",
    "test_blueprint_category_id": 123,
    "status": "<string>",
    "browser_zoom": 123,
    "viewport_width": 123,
    "viewport_height": 123,
    "num_retries": 123,
    "persist_self_healed": true,
    "file_download_mode": "<string>",
    "variables": [
      {}
    ],
    "setup_module": 123,
    "teardown_module": 123,
    "folder_path": "<string>",
    "steps": [
      {}
    ],
    "created_by": 123,
    "created_at": "<string>",
    "updated_at": "<string>"
  }
}

Create a new test blueprint with a title, starting URL, and a sequence of steps.

Request body

Required fields

title

string

required

The name of the test. Must be between 1 and 128 characters and unique within your account.

type

string

required

The blueprint type. Must be one of:

"integration" — a standard end-to-end test
"module" — an account/login module (requires starting_url and credentials)

To create reusable modules, use the Create Module endpoint instead.

steps

object[]

required

An ordered list of steps for the test to execute. Required for integration type.

Show Step object properties

step_number

integer

required

The position of this step in the sequence (starting from 1). Must be unique within the test.

type

string

required

The step type. Available types:AI steps:

"act" — an AI-driven browser action (e.g. click, type, navigate). Action text must not be empty.
"assert" — an AI-driven assertion that verifies something on the page.

Module & orchestration:

"step_module" — execute a reusable module. Requires test_blueprint_module_id.
"trigger_run" — trigger another test as a sub-run. Requires trigger_run_config.

API step:

"api" — make an HTTP request. Requires api_request.

Recorded/low-level steps:

"key" — press a keyboard key.
"type" — type text into the focused element.
"mouse_move" — move the mouse to coordinates.
"left_click" — left click at coordinates.
"left_click_drag" — click and drag from one point to another.
"right_click" — right click at coordinates.
"double_click" — double click at coordinates.
"triple_click" — triple click at coordinates.
"scroll" — scroll the page.
"wait" — wait for a duration.

Mobile-only:

"deeplink" — open a deep link URL. Only supported when device_type is "android" or "ios".

action

string

required

A natural language instruction describing what the step should do. For recorded steps, this contains the coordinates or key data. For api steps, this can be left empty.

use_vision

boolean

Whether to enable vision (screenshot analysis) for this step. Defaults to false.

test_blueprint_module_id

integer

The ID of the module to execute. Required when type is "step_module".

api_request

object

The HTTP request configuration. Required for steps with type: "api".

Show API request properties

url

string

required

The full URL to send the request to.

method

string

required

The HTTP method (e.g. "GET", "POST", "PUT", "DELETE").

headers

object

Key-value pairs for request headers.

body

object

The request body (for POST, PUT, PATCH requests).

timeout

integer

Request timeout in seconds. Defaults to 60.

retries

integer

Number of retries on failure. Defaults to 1.

backoff_seconds

number

Delay between retries in seconds. Defaults to 2.5.

should_refresh_page

boolean

Whether to refresh the browser page after the API call. Defaults to false.

trigger_run_config

object

Configuration for triggering another test. Required when type is "trigger_run".

Show Trigger run config properties

test_blueprint_id

integer

required

The ID of the test blueprint to trigger as a sub-run.

attached_file_ids

integer[]

Array of file IDs to attach to this step. Files must be uploaded to the test blueprint first.

assert_images_count

integer

Number of screenshot images to capture for assertion steps. Defaults to 5.

disable_self_healing

boolean

Disable automatic self-healing for this step. Defaults to false.

click_count

integer

Number of clicks to perform for click-type steps. Defaults to 1.

hold_start_duration

number

Duration in seconds to hold before the action. Defaults to 0.

hold_end_duration

number

Duration in seconds to hold after the action. Defaults to 0.

Optional fields

starting_url

string

The URL the browser navigates to before executing steps. Must be a valid URL starting with http:// or https://. Required when type is "module".

starting_prompt

string

A high-level description of what the test does. Used as additional context for the AI agent.

test_blueprint_category_id

integer

The ID of the test suite this test belongs to. You can find this ID in the Docket dashboard URL when on the Test Suites tab.

folder_path

string

The folder path for organizing the test. Defaults to "/".

device_type

string

The device to run the test on. Must be one of:

"browser" — desktop browser (default)
"android" — Android device
"ios" — iOS device

device_name

string

The specific device name to use for mobile testing (when device_type is "android" or "ios").

app_id

integer

The ID of the mobile app to associate with this test. Used for Android and iOS testing.

browser_zoom

number

Browser zoom level. Must be between 0.75 and 2.0. Defaults to 1.0.

viewport_width

integer

Browser viewport width in pixels. Defaults to 1440.

viewport_height

integer

Browser viewport height in pixels. Defaults to 900.

num_retries

integer

Number of automatic retries if the test fails. Must be between 0 and 3. Defaults to 0.

reset_browser_on_retry

boolean

Whether to reset the browser session on retry. Defaults to true.

typing_speed

integer

Typing speed in milliseconds per character. Must be between 1 and 1000. Defaults to null (uses the default speed of 12ms).

persist_self_healed

boolean

Whether to persist self-healed action caches so future runs use the healed selectors. Defaults to true.

file_download_mode

string

How to handle file downloads during the test. Must be one of:

"save_only" — save downloaded files without processing (default)
"ingest_content" — save and ingest file contents for the AI agent to use

variables

object[]

Variables that can be referenced in step actions using {{variable_key}} syntax.

Show Variable object properties

key

string

required

The variable name (used as the reference key in steps).

type

string

required

The variable type: "text", "email", or "random".

value

string

The static value for text type variables.

randomConfig

object

Configuration for random type variables.

setup_module

integer

The ID of a module to run before the test steps begin. Useful for common setup tasks like authentication.

teardown_module

integer

The ID of a module to run after the test steps complete. Useful for cleanup tasks.

status

string

The initial status of the test. Must be "active" or "paused". Defaults to "active".

credentials

object

Show Credentials properties

username

string

required

The login username or email.

password

string

required

The login password.

otp_secret

string

Optional TOTP secret for two-factor authentication.

Example: Basic integration test

{
  "title": "Login Flow",
  "type": "integration",
  "test_blueprint_category_id": 12,
  "starting_url": "https://example.com/login",
  "steps": [
    {
      "step_number": 1,
      "type": "act",
      "action": "Enter 'user@example.com' in the email field"
    },
    {
      "step_number": 2,
      "type": "act",
      "action": "Enter 'password123' in the password field"
    },
    {
      "step_number": 3,
      "type": "act",
      "action": "Click the 'Log In' button"
    },
    {
      "step_number": 4,
      "type": "assert",
      "action": "Verify user is redirected to the dashboard page"
    }
  ]
}

Example: Test with module, API step, and variables

{
  "title": "Create Campaign with API Setup",
  "type": "integration",
  "starting_url": "https://app.example.com",
  "setup_module": 42,
  "num_retries": 1,
  "variables": [
    {
      "key": "campaign_name",
      "type": "random",
      "randomConfig": { "prefix": "Test Campaign " }
    }
  ],
  "steps": [
    {
      "step_number": 1,
      "type": "api",
      "action": "",
      "api_request": {
        "url": "https://api.example.com/campaigns",
        "method": "POST",
        "headers": { "Authorization": "Bearer {{token}}" },
        "body": { "name": "{{campaign_name}}" },
        "timeout": 30
      }
    },
    {
      "step_number": 2,
      "type": "act",
      "action": "Navigate to the campaigns list"
    },
    {
      "step_number": 3,
      "type": "assert",
      "action": "Verify '{{campaign_name}}' appears in the campaign list"
    },
    {
      "step_number": 4,
      "type": "step_module",
      "action": "Run cleanup module",
      "test_blueprint_module_id": 99
    }
  ]
}

Response

message

string

A confirmation message (e.g. "Test blueprint created successfully").

test_blueprint

object

The created test blueprint object.

Show Properties

integer

The unique ID of the test blueprint.

company_id

integer

Your company ID.

title

string

The test title.

type

string

The blueprint type ("integration" or "module").

device_type

string

The device type ("browser", "android", or "ios").

starting_url

string

The starting URL for the test.

starting_prompt

string

The high-level description of the test.

test_blueprint_category_id

integer

The test suite ID.

status

string

The test status ("active" or "paused").

browser_zoom

number

The browser zoom level.

viewport_width

integer

Browser viewport width.

viewport_height

integer

Browser viewport height.

num_retries

integer

Number of automatic retries on failure.

persist_self_healed

boolean

Whether self-healed caches are persisted.

file_download_mode

string

The file download handling mode.

variables

object[]

Variables defined for this test.

setup_module

integer

The setup module ID, if set.

teardown_module

integer

The teardown module ID, if set.

folder_path

string

The folder path of the test.

steps

object[]

The list of test steps with their generated IDs.

created_by

integer

The ID of the user who created the test.

created_at

string

ISO 8601 timestamp of when the test was created.

updated_at

string

ISO 8601 timestamp of when the test was last updated.

Example response

{
  "message": "Test blueprint created successfully",
  "test_blueprint": {
    "id": 181,
    "company_id": 2,
    "title": "Login Flow",
    "type": "integration",
    "device_type": "browser",
    "status": "active",
    "starting_url": "https://example.com/login",
    "starting_prompt": null,
    "test_blueprint_category_id": 12,
    "browser_zoom": 1.0,
    "viewport_width": 1440,
    "viewport_height": 900,
    "num_retries": 0,
    "persist_self_healed": true,
    "file_download_mode": "save_only",
    "variables": null,
    "setup_module": null,
    "teardown_module": null,
    "folder_path": "/",
    "created_by": 4,
    "created_at": "2025-07-03T01:45:55.486917+00:00",
    "updated_at": "2025-07-03T01:45:55.486923+00:00",
    "steps": [
      {
        "id": 564,
        "step_number": 1,
        "test_blueprint_id": 181,
        "type": "act",
        "action": "Enter 'user@example.com' in the email field",
        "use_vision": false,
        "disable_self_healing": false,
        "click_count": 1
      },
      {
        "id": 565,
        "step_number": 2,
        "test_blueprint_id": 181,
        "type": "act",
        "action": "Enter 'password123' in the password field",
        "use_vision": false,
        "disable_self_healing": false,
        "click_count": 1
      },
      {
        "id": 566,
        "step_number": 3,
        "test_blueprint_id": 181,
        "type": "act",
        "action": "Click the 'Log In' button",
        "use_vision": false,
        "disable_self_healing": false,
        "click_count": 1
      },
      {
        "id": 567,
        "step_number": 4,
        "test_blueprint_id": 181,
        "type": "assert",
        "action": "Verify user is redirected to the dashboard page",
        "use_vision": false,
        "disable_self_healing": false,
        "click_count": 1
      }
    ]
  }
}

API Reference Run Test

​Request body

​Required fields

​Optional fields

​Example: Basic integration test

​Example: Test with module, API step, and variables

​Response

​Example response

Request body

Required fields

Optional fields

Example: Basic integration test

Example: Test with module, API step, and variables

Response

Example response