API Reference

Getting Started

This guide will help you get started with the Test IO API. You'll learn how to authenticate, set up a test, run it, and retrieve the bugs found.

Prerequisites

  • A Test IO account
  • An API token from Integrations → API in your Test IO account
  • Your product already created in Test IO (or you'll create one via API)

Step 1: Authenticate

All API requests require authentication using your API token in the Authorization header:

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

See Authentication for detailed information.

Step 2: Get or Create a Product

First, list your existing products:

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

If you need to create a new product:

1curl -X POST "https://api.test.io/customer/v2/products" \
2  -H "Authorization: Token YOUR_API_TOKEN" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "product": {
6      "title": "My Web Application",
7      "description": "E-commerce platform",
8      "product_type": "website",
9      "industry": "retail"
10    }
11  }'

Save the product_id from the response. You'll need it for subsequent steps.

See Products for more details.

Step 3: Create a Test Environment

A test environment defines where testers will access your application:

1curl -X POST "https://api.test.io/customer/v2/products/{product_id}/test_environments" \
2  -H "Authorization: Token YOUR_API_TOKEN" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "test_environment": {
6      "title": "Staging Environment",
7      "url": "https://staging.example.com",
8      "username": "tester",
9      "password": "test_password",
10      "access": "No special access required",
11      "allow_orders": false
12    }
13  }'

Note: For mobile apps, upload your binary app first using Binary Apps, then reference it with binary_app_id in the test environment.

See Test Environments for more options.

Step 4: Choose Your Test Approach

You have two options for defining what to test:

List available templates for your product:

1curl -X GET "https://api.test.io/customer/v2/test_templates?product_id={product_id}" \
2  -H "Authorization: Token YOUR_API_TOKEN"

Use a template ID when creating your test. See Test Templates.

Option B: Create Features

Create features that define what testers should focus on:

1curl -X POST "https://api.test.io/customer/v2/features" \
2  -H "Authorization: Token YOUR_API_TOKEN" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "product_id": {product_id},
6    "feature": {
7      "title": "Checkout Process",
8      "description": "Test the complete checkout flow",
9      "howtofind": "Navigate to cart and proceed to checkout",
10      "user_stories": [
11        "As a customer, I want to complete a purchase",
12        "As a customer, I want to see order confirmation"
13      ]
14    }
15  }'

See Features for more details.

Step 5: Create and Run an Exploratory Test

Create an exploratory test that will be executed by testers:

1curl -X POST "https://api.test.io/customer/v2/products/{product_id}/exploratory_tests" \
2  -H "Authorization: Token YOUR_API_TOKEN" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "exploratory_test": {
6      "test_title": "Checkout Flow Test",
7      "goal": "Validate the checkout process for usability and bugs",
8      "instructions": "Focus on the checkout flow and payment process",
9      "duration": "24",
10      "report_language": "en",
11      "testing_type": "coverage",
12      "test_environment": {
13        "title": "Staging Environment",
14        "url": "https://staging.example.com",
15        "username": "tester",
16        "password": "test_password"
17      },
18      "test_template": {
19        "id": {template_id}
20      }
21    }
22  }'

Key parameters:

  • testing_type: coverage (default), usability, rapid, or focused
  • duration: Test duration in hours (default: 28 for coverage, 24 for usability, 2 for rapid)
  • test_environment: Can reference an existing environment ID or define inline
  • test_template OR features: Provide exactly one (mutually exclusive)

The test will start automatically. Save the exploratory_test_id from the response.

See Exploratory Tests for all options.

Step 6: Fetch Bugs

Once your test is running, bugs will be reported by testers. Fetch them using:

1curl -X GET "https://api.test.io/customer/v2/bugs?filter_product_ids={product_id}" \
2  -H "Authorization: Token YOUR_API_TOKEN"

Filter by test cycle to get bugs from a specific test:

1curl -X GET "https://api.test.io/customer/v2/bugs?filter_test_cycle_ids={test_cycle_id}" \
2  -H "Authorization: Token YOUR_API_TOKEN"

Get a specific bug by ID:

1curl -X GET "https://api.test.io/customer/v2/bugs/{bug_id}" \
2  -H "Authorization: Token YOUR_API_TOKEN"

Bug Management:

  • Accept: PUT /bugs/{bug_id}/accept
  • Reject: PUT /bugs/{bug_id}/reject (with reason and comment)
  • Mark as fixed: PUT /bugs/{bug_id}/mark_as_fixed
  • Mark as known: PUT /bugs/{bug_id}/mark_as_known

See Bugs for all bug management operations.

Quick Reference: Typical Flow

  1. Authenticate → Get API token
  2. Get Product → List or create product, save product_id
  3. Create Test Environment → Define where to test, save test_environment_id (or use inline)
  4. Choose Test Definition → Use template OR create features
  5. Create Exploratory Test → Test starts automatically
  6. Fetch Bugs → Retrieve bugs as they're reported

Testing Types

  • Coverage (default): Comprehensive testing, 28 hours default duration
  • Usability: Focus on user experience, 24 hours default
  • Rapid: Quick feedback, 2 hours default
  • Focused: Target specific bug severities (high/critical), 24 hours default

Next Steps

Error Handling

The API uses standard HTTP status codes:

  • 200 OK - Successful request
  • 201 Created - Resource created successfully
  • 400 Bad Request - Invalid request parameters
  • 401 Unauthorized - Invalid or missing API token
  • 404 Not Found - Resource not found
  • 422 Unprocessable Entity - Validation error

Always check the response status and handle errors appropriately:

1# Example: Check response status
2response=$(curl -s -w "\n%{http_code}" -X GET "https://api.test.io/customer/v2/products" \
3  -H "Authorization: Token YOUR_API_TOKEN")
4http_code=$(echo "$response" | tail -n1)
5body=$(echo "$response" | sed '$d')
6
7if [ "$http_code" -eq 200 ]; then
8  echo "Success: $body"
9else
10  echo "Error ($http_code): $body"
11fi

Best Practices

1. Store Credentials Securely

Never hardcode your API token. Use environment variables:

1export TESTIO_API_TOKEN="your_token_here"
2curl -X GET "https://api.test.io/customer/v2/products" \
3  -H "Authorization: Token $TESTIO_API_TOKEN"

2. Poll for Test Completion

Tests run asynchronously. Poll the test status to know when it's complete:

1# Get test status
2curl -X GET "https://api.test.io/customer/v2/exploratory_tests/{test_id}" \
3  -H "Authorization: Token YOUR_API_TOKEN"

Check the status field in the response. Common statuses include pending, running, completed, cancelled.

3. Filter Bugs Efficiently

Use filters to get only relevant bugs:

1# Get only unexported bugs for a specific product
2curl -X GET "https://api.test.io/customer/v2/bugs?filter_product_ids=1&export_status=not_exported" \
3  -H "Authorization: Token YOUR_API_TOKEN"

4. Reuse Test Environments

Create test environments once and reuse them across multiple tests by referencing the test_environment_id:

1# Use existing environment ID instead of inline definition
2{
3  "exploratory_test": {
4    "test_environment_id": 42,  // Reference existing environment
5    "test_template": { "id": 1 }
6  }
7}

5. Handle Pagination

When listing resources, use pagination for large datasets:

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

Common Workflows

Website Testing Workflow

  1. Get or create product (product_type: "website")
  2. Create test environment with URL
  3. List test templates or create features
  4. Create exploratory test with template/features
  5. Poll test status until complete
  6. Fetch bugs filtered by product or test cycle

Mobile App Testing Workflow

  1. Get or create product (product_type: "mobile_app_ios" or "mobile_app_android")
  2. Upload binary app (.ipa or .apk)
  3. Create test environment with binary_app_id
  4. Create exploratory test
  5. Fetch bugs

Rapid Testing Workflow

For quick feedback, use testing_type: "rapid" with a 2-hour duration:

1{
2  "exploratory_test": {
3    "testing_type": "rapid",
4    "duration": "2",
5    "test_environment": { ... },
6    "test_template": { "id": 1 }
7  }
8}

Troubleshooting

Authentication Issues

  • Verify your API token is correct
  • Check token hasn't expired (rotate if needed)
  • Ensure header format: Authorization: Token YOUR_API_TOKEN

Test Not Starting

  • Verify test environment is correctly configured
  • Check that either test_template OR features is provided (not both)
  • Ensure product exists and is active

No Bugs Returned

  • Tests may still be running (check test status)
  • Verify filters are correct (product_id, test_cycle_id)
  • Bugs appear as testers report them (may take time)

Mobile App Upload Fails

  • Check file size (max 1GB)
  • Verify file extension (.ipa, .apk, .xap, .appx, .zip, .wgt)
  • For large files, use the direct upload URL method (see Binary Apps)

Additional Resources

For more help, visit the Test IO Help Center.

Next
Authentication