titledescriptionupdated_date
TestRail API2025-10-24T16:45:21Z

TestRail API Integration Guide

This guide provides instructions on how to integrate with TestRail using the REST API, with a focus on authentication and permissions.

What we need

[] Username [] API KEy [] Your test rail instance, it looks like https://<your_instance_name>.testrail.io/index.php?/api/v2/

Overview

TestRail is a comprehensive test case management tool that offers a REST API for integration with other systems. This API allows you to:

  • Access test cases
  • View test runs and test plans
  • Retrieve test results
  • Generate reports
  • View users and permissions
  • And more

Authentication Methods

TestRail offers two authentication methods for API access:

For better security, TestRail supports API keys. This is the recommended approach for all integrations:

  1. Log into TestRail as the user who will be making API calls
  2. Navigate to “My Settings” (click on your profile in the top-right corner)
  3. Select the “API Keys” tab
  4. Click “Add Key” and provide a name for the key
  5. Click “Generate Key”
  6. Click the “save the settings” button. It’ll turn grey when the settings are successfully saved

Use the generated API key in your requests:

curl -H "Content-Type: application/json" \
     -u "user@example.com:your-api-key" \
     "https://your-instance.testrail.io/index.php?/api/v2/get_case/1"

Permissions and Access Control

When integrating with TestRail’s API, it’s important to understand the permissions model to ensure your integration has the appropriate access levels.

User Roles and Permissions

TestRail uses a role-based access control system:

  1. Global Roles: Every user has an assigned global role that determines their default permissions across all projects.

  2. Project-Specific Roles: Permissions can be overridden at the project level, allowing different access levels for different projects.

  3. Built-in Roles:

    • Administrator: Full access to all features and projects. Necesary for getting all users
    • Lead: Can manage test cases, test runs, and results
    • Tester: Can add and execute tests, but with limited management capabilities
    • Guest: Read-only access to projects and test data

  4. Custom Roles: Administrators can create custom roles with specific permission sets.

API Key Permissions

API keys inherit the permissions of the user who created them. This means:

  • An API key created by an Administrator will have full access
  • An API key created by a Tester will only have the permissions assigned to the Tester role
  • If a user’s role changes, the API key’s permissions will change accordingly

Best Practices for API Permissions

  1. Create a dedicated API user: Create a specific user account for API integrations rather than using a personal account.

  2. Apply the principle of least privilege: Assign the minimum permissions necessary for the integration to function.

  3. Use project-specific access: If your integration only needs access to specific projects, configure the user’s project access accordingly.

  4. Regularly audit API keys: Periodically review and rotate API keys to maintain security.

  5. Revoke unused keys: Delete API keys that are no longer in use to minimize security risks.

REST API Basics

TestRail’s REST API is HTTP-based and follows these conventions:

  • All operations use HTTP GET
  • Data is transferred in JSON format with UTF-8 encoding
  • Authentication is via HTTP Basic Authentication

Base URL

https://your-instance.testrail.io/index.php?/api/v2/

Common Endpoints

  • get_cases/{project_id} - Get test cases for a project
  • get_case/{case_id} - Get a specific test case
  • get_results/{test_id} - Get test results

Example: Getting Test Cases

curl -H "Content-Type: application/json" \
     -u "user@example.com:your-api-key" \
     "https://your-instance.testrail.io/index.php?/api/v2/get_cases/1"

Error Handling

The REST API returns standard HTTP status codes:

  • 200: Success
  • 400: Bad request (invalid parameters)
  • 401: Unauthorized (authentication failed)
  • 403: Forbidden (insufficient permissions)
  • 404: Not found
  • 429: Too many requests (rate limit exceeded)
  • 500: Server error

Error responses include a JSON body with details:

{
  "error": "Field 'status_id' is required"
}

Rate Limiting

TestRail implements rate limiting to prevent API abuse. The specific limits depend on your TestRail plan and instance configuration. If you exceed the rate limit, you’ll receive a 429 status code.

Security Considerations

  1. Always use HTTPS: Ensure all API communications use HTTPS to encrypt data in transit.

  2. Protect API keys: Store API keys securely and never expose them in client-side code.

  3. Implement proper error handling: Handle authentication and permission errors gracefully in your integration.

  4. Monitor API usage: Regularly review API access logs to detect unusual patterns.

Troubleshooting

Common Issues

  1. Authentication failures:

    • Verify the username and API key are correct
    • Check if the API key has been revoked or expired
    • Ensure the user account is active

  2. Permission errors:

    • Verify the user has the necessary permissions for the requested operation
    • Check project-specific access settings

  3. Rate limiting:

    • Implement exponential backoff for retries
    • Optimize queries to reduce the number of API calls

Additional Resources