openapi: 3.0.3 info: title: TestRail API (v2) Cases Results API description: 'TestRail is a web-based test case management and QA platform. This document models the TestRail HTTP API v2, which lets teams manage projects, suites, sections, test cases, test runs, test plans, individual tests, results, milestones, configurations, and users. TestRail runs on a per-customer instance: TestRail Cloud is hosted at https://{instance}.testrail.io (older Cloud instances use .testrail.com), and TestRail Server / Enterprise is self-hosted on your own host. There is no single shared public endpoint. URL style: every call is routed through TestRail''s `index.php` front controller, so the effective base is `https://{instance}.testrail.io/index.php?/api/v2` and a method looks like `GET /index.php?/api/v2/get_run/1`. The `?/api/v2/...` is a rewritten query string that TestRail treats as the API path. In this document the servers entry carries the `index.php?/api/v2` prefix and each path is the method name plus its id/parent segment. Authentication is HTTP Basic: the username is your TestRail email and the password is your account password or an API key generated under My Settings. The API must be enabled by an administrator under Administration > Site Settings > API. All payloads are JSON. Bulk GET endpoints (get_cases, get_runs, get_results, etc.) return up to 250 records per page and accept `limit` (1-250) and `offset` for pagination.' version: '2.0' contact: name: TestRail (IDERA) url: https://www.testrail.com x-transport-note: The real request URL embeds the API version in a query string via index.php, e.g. https://example.testrail.io/index.php?/api/v2/get_run/1 - this is intentional and specific to TestRail, not a normal REST path. servers: - url: https://{instance}.testrail.io/index.php?/api/v2 description: TestRail Cloud (per-instance host; replace {instance} with your subdomain) variables: instance: default: example description: Your TestRail Cloud subdomain. - url: https://{host}/index.php?/api/v2 description: TestRail Server / Enterprise (self-hosted; replace {host} with your install host) variables: host: default: testrail.example.com description: Hostname of your self-hosted TestRail installation. security: - basicAuth: [] tags: - name: Results description: Recorded outcomes for tests and cases. paths: /get_results/{test_id}: get: operationId: getResults tags: - Results summary: Get results for a test description: Returns a list of test results for a test. Bulk endpoint - returns up to 250 records per page. parameters: - name: test_id in: path required: true schema: type: integer - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Offset' responses: '200': description: A list of results for the test. /get_results_for_case/{run_id}/{case_id}: get: operationId: getResultsForCase tags: - Results summary: Get results for a case in a run description: Returns a list of test results for a test run and case combination. parameters: - $ref: '#/components/parameters/RunId' - $ref: '#/components/parameters/CaseId' - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Offset' responses: '200': description: A list of results for the case in the run. /get_results_for_run/{run_id}: get: operationId: getResultsForRun tags: - Results summary: Get results for a run description: Returns a list of test results for a test run. Bulk endpoint - returns up to 250 records per page; supports created_after and status_id filters. parameters: - $ref: '#/components/parameters/RunId' - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Offset' responses: '200': description: A list of results for the run. /add_result/{test_id}: post: operationId: addResult tags: - Results summary: Add result for a test description: Adds a new test result, comment, or assignment to a test. Requires a status_id and may include comment, elapsed, defects, and version. parameters: - name: test_id in: path required: true schema: type: integer requestBody: $ref: '#/components/requestBodies/GenericJson' responses: '200': description: The created result. /add_result_for_case/{run_id}/{case_id}: post: operationId: addResultForCase tags: - Results summary: Add result for a case in a run description: Adds a new test result for a test run and case combination. parameters: - $ref: '#/components/parameters/RunId' - $ref: '#/components/parameters/CaseId' requestBody: $ref: '#/components/requestBodies/GenericJson' responses: '200': description: The created result. /add_results/{run_id}: post: operationId: addResults tags: - Results summary: Add results (bulk, by test) description: Adds one or more new test results in a single request, keyed by test_id. Recommended for automated suites to report many outcomes at once and reduce rate-limited calls. parameters: - $ref: '#/components/parameters/RunId' requestBody: $ref: '#/components/requestBodies/GenericJson' responses: '200': description: The created results. /add_results_for_cases/{run_id}: post: operationId: addResultsForCases tags: - Results summary: Add results (bulk, by case) description: Adds one or more new test results in a single request, keyed by case_id. Preferred bulk endpoint for automation frameworks pushing results into a run. parameters: - $ref: '#/components/parameters/RunId' requestBody: $ref: '#/components/requestBodies/GenericJson' responses: '200': description: The created results. components: parameters: Limit: name: limit in: query required: false description: Number of records to return (1-250; bulk endpoints default and cap at 250). schema: type: integer minimum: 1 maximum: 250 default: 250 CaseId: name: case_id in: path required: true description: The ID of the test case. schema: type: integer Offset: name: offset in: query required: false description: Number of records to skip for pagination on bulk endpoints. schema: type: integer minimum: 0 RunId: name: run_id in: path required: true description: The ID of the test run. schema: type: integer requestBodies: GenericJson: required: true description: JSON request body. Field names follow the TestRail API reference for the specific method (see the method's support.testrail.com article). content: application/json: schema: type: object additionalProperties: true securitySchemes: basicAuth: type: http scheme: basic description: HTTP Basic authentication. Username is your TestRail email; password is your account password or an API key generated under My Settings. The API must be enabled by an admin under Administration > Site Settings > API.