TestRail Cases API

openapi: 3.2.0
info:
  title: TestRail API (v2) Cases API
  description: TestRail is a web-based test case management and QA platform.
  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: Cases
  description: Reusable test cases in the repository.
paths:
  /get_cases/{project_id}:
    get:
      operationId: getCases
      tags:
      - Cases
      summary: Get cases
      description: Returns a list of test cases for a project and optional suite. Bulk endpoint - returns up to 250 records per page; use limit and offset to page. Supports filters such as suite_id, section_id, and updated_after.
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - name: suite_id
        in: query
        required: false
        schema:
          type: integer
      - name: section_id
        in: query
        required: false
        schema:
          type: integer
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: A list of test cases.
  /get_case/{case_id}:
    get:
      operationId: getCase
      tags:
      - Cases
      summary: Get case
      description: Returns an existing test case.
      parameters:
      - $ref: '#/components/parameters/CaseId'
      responses:
        '200':
          description: The requested test case.
  /add_case/{section_id}:
    post:
      operationId: addCase
      tags:
      - Cases
      summary: Add case
      description: Creates a new test case in a section.
      parameters:
      - name: section_id
        in: path
        required: true
        schema:
          type: integer
      requestBody:
        $ref: '#/components/requestBodies/GenericJson'
      responses:
        '200':
          description: The created test case.
  /update_case/{case_id}:
    post:
      operationId: updateCase
      tags:
      - Cases
      summary: Update case
      description: Updates an existing test case.
      parameters:
      - $ref: '#/components/parameters/CaseId'
      requestBody:
        $ref: '#/components/requestBodies/GenericJson'
      responses:
        '200':
          description: The updated test case.
  /delete_case/{case_id}:
    post:
      operationId: deleteCase
      tags:
      - Cases
      summary: Delete case
      description: Deletes an existing test case.
      parameters:
      - $ref: '#/components/parameters/CaseId'
      responses:
        '200':
          description: Deletion confirmation.
  /get_case_fields:
    get:
      operationId: getCaseFields
      tags:
      - Cases
      summary: Get case fields
      description: Returns a list of available custom fields for test cases.
      responses:
        '200':
          description: A list of case fields.
  /get_case_types:
    get:
      operationId: getCaseTypes
      tags:
      - Cases
      summary: Get case types
      description: Returns a list of available case types.
      responses:
        '200':
          description: A list of case types.
components:
  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
  parameters:
    ProjectId:
      name: project_id
      in: path
      required: true
      description: The ID of the project.
      schema:
        type: integer
    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
    Offset:
      name: offset
      in: query
      required: false
      description: Number of records to skip for pagination on bulk endpoints.
      schema:
        type: integer
        minimum: 0
    CaseId:
      name: case_id
      in: path
      required: true
      description: The ID of the test case.
      schema:
        type: integer
  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.