Skip to main content
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 step modules, use the Create Module endpoint instead.
​
steps
object[]
required
An ordered list of steps for the test to execute. Required for integration type.

​
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.
​
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
Login credentials for module (account) type blueprints. Required when type is "module".

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

​
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
      }
    ]
  }
}