API Reference

Exploratory Tests

Create and manage exploratory tests for your products.

Prerequisites:

Get exploratory test

Retrieve a specific exploratory test by ID.

Endpoint: GET /exploratory_tests/{exploratory_test_id}

Parameters:

  • exploratory_test_id (number, required) - ID of the Exploratory test

Example Request:

1curl -X GET "https://api.test.io/customer/v2/exploratory_tests/123" \
2  -H "Authorization: Token YOUR_API_TOKEN"

Response: 200 OK

Returns the exploratory test object with full details including test environment, features, requirements, and more.

List exploratory tests

Returns a paginated list of exploratory tests for the specified product.

Endpoint: GET /products/{product_id}/exploratory_tests{?page,per_page}

Parameters:

  • product_id (number, required) - ID of the Product
  • page (number, optional) - Page number of the result set
  • per_page (number, optional) - Number of items per page when pagination is applied. Used only if page is provided. Default: 25

Notes:

If page parameter is omitted, pagination is not applied and the last 150 tests are returned.

Example Request:

1curl -X GET "https://api.test.io/customer/v2/products/1/exploratory_tests?page=1&per_page=25" \
2  -H "Authorization: Token YOUR_API_TOKEN"

Response: 200 OK

Returns an array of exploratory test objects.

Create exploratory test

Creates a new exploratory test for the specified product.

Endpoint: POST /products/{product_id}/exploratory_tests

Parameters:

  • product_id (number, required) - ID of the Product

All attributes must be provided inside the root object exploratory_test.

Attributes

  • test_title (string, optional) - Test title
  • goal (string, optional) - Goal of the test
  • out_of_scope (string, optional) - Out of scope items
  • instructions (string, optional) - Additional requirements for testers
  • start_at (string, optional) - Start date and time of the test. Default: within the next full hour
  • duration (string, optional) - Duration of the test. Default:
    • 2 hours for rapid test
    • 24 hours for usability and focused test
    • 28 hours for coverage test
  • report_language (string, optional, default: en) - Language in which bugs will be reported. Allowed values: en, de
  • testing_type (string, optional, default: coverage) - Type of the test. Allowed values: coverage, usability, rapid, focused
  • bug_severities (object, optional) - Bug severities related attributes (only applicable if testing_type is focused)
    • low (boolean, optional, default: false) - Enable low-severity bugs
    • high (boolean, optional, default: false) - Enable high-severity bugs
    • critical (boolean, optional, default: false) - Enable critical-severity bugs
  • section_id (number, optional) - Section ID to associate the test with
  • allow_device_clouds (boolean, optional, default: false) - Allow testers to use device clouds
  • requirements (array, optional) - Device requirements (see Building Requirements Array below)
  • attachments (array, optional) - Test attachments
  • use_default_devices (boolean, optional, default: true) - Whether to use default devices selection
  • test_environment (object, required) - Test environment related attributes
  • features (array, optional) - Features to be tested
  • test_template (object, optional) - Test template related attributes

⚠️ Constraint: features and test_template are mutually exclusive - exactly one must be provided.

Example Request

1{
2  "exploratory_test": {
3    "test_title": "Checkout Flow Test",
4    "goal": "Validate the checkout process for usability and bugs",
5    "out_of_scope": "Payment provider integration",
6    "instructions": "Focus on speed and clarity of the checkout process.",
7    "start_at": "2025-09-20T14:00:00Z",
8    "duration": "30",
9    "report_language": "en",
10    "testing_type": "focused",
11    "bug_severities": {
12      "high": true,
13      "critical": true
14    },
15    "section_id": 42,
16    "allow_device_clouds": true,
17    "requirements": [
18      {
19        "category": {
20          "id": 5
21        },
22        "vendor": {
23          "id": 10
24        },
25        "devices": [
26          {
27            "id": 101
28          },
29          {
30            "id": 102
31          }
32        ],
33        "operating_system": {
34          "id": 20
35        },
36        "min_operating_system_version": {
37          "id": 200
38        },
39        "max_operating_system_version": {
40          "id": 205
41        },
42        "browsers": [
43          {
44            "id": 301
45          }
46        ],
47        "input_devices": [
48          {
49            "id": 401
50          }
51        ]
52      }
53    ],
54    "attachments": [
55      {
56        "id": 5
57      },
58      {
59        "file_url": "https://example.com/checkout_flow.pdf"
60      }
61    ],
62    "use_default_devices": false,
63    "test_environment": {
64      "title": "Staging Checkout Environment",
65      "url": "https://staging.example.com/",
66      "username": "tester",
67      "password": "secret",
68      "access": "VPN required",
69      "allow_orders": false
70    },
71    "features": [
72      {
73        "id": 15
74      },
75      {
76        "title": "Shopping Cart",
77        "description": "Verify adding and removing items works as expected.",
78        "howtofind": "Navigate to cart after adding an item.",
79        "enable_default": true,
80        "enable_content": true,
81        "enable_visual": false,
82        "user_stories": [
83          "As a customer, I want to add items to my cart so I can purchase them.",
84          "As a customer, I want to remove items from my cart if I change my mind."
85        ],
86        "use_markdown": true
87      }
88    ]
89  }
90}

Response: 201 Created

Returns the created exploratory test object with full details.

Building Requirements Array

The requirements array allows you to specify device targeting for your test. Each requirement object can include:

  • category - Device category (e.g., mobile, desktop, tablet)
  • vendor - Device manufacturer (e.g., Apple, Samsung)
  • devices - Specific device models
  • operating_system - OS (e.g., iOS, Android, Windows)
  • min_operating_system_version / max_operating_system_version - OS version range
  • browsers - Browser applications
  • input_devices - Input methods (e.g., keyboard, touch)

Important: All IDs in the requirements array (category, vendor, devices, operating_system, browsers, etc.) must be retrieved from the Public Device API. Use the Public Device API to:

  1. List available device categories, vendors, and models
  2. Get operating system and browser options
  3. Retrieve the correct IDs for each requirement field

Example: To find available iOS devices, query the Public Device API for devices with operating_system: "iOS", then use the returned IDs in your requirements array.

For a simpler approach using device type, OS, and browser names, see the Requirements page which explains the alternative format used in test case tests.

Previous
Binary Apps
Next
Test Templates