Tricentis Test Cases API

openapi: 3.2.0
info:
  title: TTM for Jira Test Cases API
  description: Tricentis Test Management for Jira
  version: 1.0.0
  termsOfService: https://www.tricentis.com/legal-information/general-terms-of-use/
servers:
- url: https://api.ttm4j.tricentis.com
security:
- api_key: []
tags:
- name: Test Cases
paths:
  /v1/projects/{project-key}/test-cases:
    get:
      tags:
      - Test Cases
      summary: Read test case(s).
      description: "Please note that this endpoint is deprecated and will be removed in the future. Use the /test-cases/bulk endpoint instead.\n            \n## Get or retrieve information from test case(s).\n            \n#### Body fields:\n* **jiraFields**: a comma-separated list of Jira fields to return for each issue. Use this to retrieve a subset of fields.\n* **ttmFields**: a comma-separated list of Jira fields to return for each issue. Use this to retrieve a subset of fields."
      parameters:
      - name: jiraFields
        in: query
        description: A list of Jira fields to return for each issue, use it to retrieve a subset of fields. Provide a comma-separated list.
        schema:
          type: string
      - name: ttmFields
        in: query
        description: A list of TTM fields to return for each issue, use it to retrieve a subset of fields. Provide a comma-separated list.
        schema:
          type: string
      - name: project-key
        in: path
        required: true
        schema:
          type: string
      - name: limit
        in: query
        description: Numeric value that determines that maximum N results will be returned
        schema:
          type: Integer
          default: 10
          example: 10
      - name: offset
        in: query
        description: 'Numeric value that determines that the result list will start from result #N (zero based)'
        schema:
          type: Integer
          default: 0
          example: 0
      responses:
        '200':
          description: Successfully retrieved test cases information.
          content:
            application/json:
              schema:
                type: object
                properties:
                  offset:
                    type:
                    - integer
                    - 'null'
                    description: Gets or sets offset.
                    format: int32
                  limit:
                    type:
                    - integer
                    - 'null'
                    description: Gets or sets limit.
                    format: int32
                  totalCount:
                    type: integer
                    description: Gets or sets totalCount.
                    format: int32
                  items:
                    type:
                    - array
                    - 'null'
                    items:
                      type: object
                      properties:
                        id:
                          type:
                          - string
                          - 'null'
                        key:
                          type:
                          - string
                          - 'null'
                        project:
                          type:
                          - string
                          - 'null'
                        testCategory:
                          type:
                          - string
                          - 'null'
                        testType:
                          enum:
                          - Manual
                          - Automated
                          type: string
                        fields:
                          type: object
                          properties:
                            components:
                              type:
                              - array
                              - 'null'
                              items:
                                type: string
                            summary:
                              type:
                              - string
                              - 'null'
                            description:
                              type:
                              - string
                              - 'null'
                            status:
                              type:
                              - string
                              - 'null'
                            priority:
                              type:
                              - string
                              - 'null'
                            labels:
                              type:
                              - array
                              - 'null'
                              items:
                                type: string
                          additionalProperties: false
                        customFields:
                          type:
                          - array
                          - 'null'
                          items:
                            type: object
                            properties:
                              key:
                                type:
                                - string
                                - 'null'
                              name:
                                type:
                                - string
                                - 'null'
                              value: {}
                            additionalProperties: false
                        ttmFields:
                          type: object
                          properties:
                            precondition:
                              type:
                              - string
                              - 'null'
                            steps:
                              type:
                              - array
                              - 'null'
                              items:
                                type: object
                                additionalProperties: false
                          additionalProperties: false
                        requirements:
                          type:
                          - array
                          - 'null'
                          items:
                            type: string
                        folder:
                          type:
                          - string
                          - 'null'
                        folderId:
                          type:
                          - string
                          - 'null'
                          format: uuid
                        automation:
                          type: object
                          properties:
                            name:
                              type:
                              - string
                              - 'null'
                            externalId:
                              type:
                              - string
                              - 'null'
                            content:
                              type:
                              - string
                              - 'null'
                          additionalProperties: false
                      additionalProperties: false
                    description: Gets or sets items.
                additionalProperties: false
                description: Page Response Scheme.
              examples:
                Tests results:
                  value:
                    offset: 0
                    limit: 1
                    totalCount: 100
                    items:
                    - id: acde1582-0cfe-46d2-9561-478a67d43b93
                      key: TE-1
                      project: TE
                      testType: Manual
                      fields:
                        summary: Test 1 status
                        description: Test 1 description
                        status: Backlog
                        priority: High
                        labels:
                        - My Label
                      customFields:
                      - key: customField_10001
                        name: A custom field
                        value: Some value
                      ttmFields:
                        precondition: A precondition
                        steps:
                        - testCaseKey: TE-2
                          testCaseId: '10000'
                        - description: Login
                          expectedResult: Login should work
                        - description: Logout
                          expectedResult: Logout should work
                        - testCaseKey: TE-5
                          testCaseId: '10004'
                          deleted: true
                      requirements:
                      - TE-10
                      - TE-11
                      folder: parent folder/child folder
                      folderId: 35ea12e6-f03e-4c20-85c1-da64525a0436
                    - id: e5dbf10e-ee5c-47d9-9e8c-403ce6c1b34a
                      key: TE-2
                      project: TE
                      testType: Automated
                      fields:
                        summary: An automated test
                        description: Automated test description
                        status: Backlog
                        priority: High
                        labels:
                        - My Label
                      requirements:
                      - TE-12
                      - TE-13
                      folder: automated tests/feature1
                      folderId: 13354c28-a3da-4d37-a2e9-d25330e78909
        '400':
          description: '`Invalid parameters.'
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type:
                    - string
                    - 'null'
                  title:
                    type:
                    - string
                    - 'null'
                  status:
                    type:
                    - integer
                    - 'null'
                    format: int32
                  detail:
                    type:
                    - string
                    - 'null'
                  instance:
                    type:
                    - string
                    - 'null'
                additionalProperties: {}
              examples:
                BadDataResponse:
                  value:
                    message: bad data
        '401':
          description: '`Unauthorized`.'
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type:
                    - string
                    - 'null'
                  title:
                    type:
                    - string
                    - 'null'
                  status:
                    type:
                    - integer
                    - 'null'
                    format: int32
                  detail:
                    type:
                    - string
                    - 'null'
                  instance:
                    type:
                    - string
                    - 'null'
                additionalProperties: {}
              examples:
                UnauthorizedResponse:
                  value:
                    message: unauthorized
        '404':
          description: '`Not Found`.'
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type:
                    - string
                    - 'null'
                  title:
                    type:
                    - string
                    - 'null'
                  status:
                    type:
                    - integer
                    - 'null'
                    format: int32
                  detail:
                    type:
                    - string
                    - 'null'
                  instance:
                    type:
                    - string
                    - 'null'
                additionalProperties: {}
              examples:
                NotFoundResponse:
                  value:
                    message: not found
      deprecated: true
      security:
      - api_key: []
    post:
      tags:
      - Test Cases
      summary: Create test case(s).
      description: "## Create test case(s).\n            \n#### Body fields:\n            \n* **folder** _(optional)_: Specify the folder path where you want to save the test case. A path is a string of concatenated parts separated by a slash \"/\".  If you don't specify a folder path, the test case saves in the \"All tests\" folder. Do not specify both the folder and the folderID, or the request will fail.\n* **folderId** _(optional)_: Specify a unique ID associated with the folder in the TTM database, which specifies where the test case should be saved. Do not specify both the folder and the folderID, or the request will fail.\n* **callbackUrl** _(optional)_: Specify a URL that will recevie status of the request (The URL will serve as POST endpoint in the user side).\n* **tests**: Provide a list of tests with the following values:\n    * **fields**: The native Jira fields in a test case. The following fields are available:\n        * **summary**: The Summary of the test case in Jira.\n        * **description** _(optional)_: The Description of the test case in Jira.\n        * **status** _(optional)_: The Status of the test case in Jira.\n        * **priority** _(optional)_: The Priority of the test case in Jira.\n        * **labels** _(optional)_: The Labels of the test case in Jira.\n    * **ttmFields**: These are the Jira fields provided by the Tricentis Test Management for Jira plugin. The following fields are available:\n        * **precondition** _(optional)_: The precondition for a test case.\n        * **steps** _(optional)_: The list of steps for the test case.\n            * **description** _(optional)_: Step description.\n            * **expectedResult** _(optional)_: Step expected result.\n            * **data** _(optional)_: Step data.\n            * **testCaseKey** _(optional)_: test case key, when set the step will call the test case and other step fields will be ignored.\n    * **testType**: Can be one of the following: \"Manual\", \"Automated\"\n    * **requirements** _(optional)_: List of issues keys (from Jira) that should be linked as requirements.\n    * **customFields** _(optional)_: The custom Jira fields in a test case.\n    * **folder** _(optional)_: Specify the folder path where you want to save the test case. A path is a string of concatenated parts separated by a slash \"/\".  If you don't specify a folder path, the test case saves in the \"All tests\" folder. Do not specify both the folder and the folderID, or the request will fail. If you do not specify the folder in this field, the request uses the folder specified at the root level.\n    * **folderId** _(optional)_: Specify a unique ID associated with the folder in the TTM database, which specifies where the test case should be saved. Do not specify both the folder and the folderID, or the request will fail. If you do not specify the folderId in this field, the request uses the folderId specified at the root level.\n    * **automation** _(optional)_: Automation data. Provide the following values for your test case:\n        * **name**: The name of your external automation system. For example, Testim.\n        * **externalId** _(optional)_: The ID of the test in your external automation platform.\n        * **content** _(optional)_: The content your automation system supplies to represent the test."
      parameters:
      - name: strictOrder
        in: query
        description: If strict order is true, test-cases will be created according to the given order.
        schema:
          type: boolean
          default: false
      - name: project-key
        in: path
        required: true
        schema:
          type: string
      requestBody:
        description: External API body payload that describes the tests to create.
        content:
          application/json:
            schema:
              type: object
              properties:
                folder:
                  type:
                  - string
                  - 'null'
                folderId:
                  type:
                  - string
                  - 'null'
                  format: uuid
                callbackUrl:
                  type:
                  - string
                  - 'null'
                tests:
                  type:
                  - array
                  - 'null'
                  items:
                    required:
                    - testType
                    type: object
                    properties:
                      testType:
                        enum:
                        - Manual
                        - Automated
                        type: string
                      fields:
                        type: object
                        properties:
                          components:
                            type:
                            - array
                            - 'null'
                            items:
                              type: string
                          summary:
                            type:
                            - string
                            - 'null'
                          description:
                            type:
                            - string
                            - 'null'
                          status:
                            type:
                            - string
                            - 'null'
                          priority:
                            type:
                            - string
                            - 'null'
                          labels:
                            type:
                            - array
                            - 'null'
                            items:
                              type: string
                        additionalProperties: false
                      customFields:
                        type:
                        - object
                        - 'null'
                        additionalProperties: {}
                      ttmFields:
                        type: object
                        properties:
                          precondition:
                            type:
                            - string
                            - 'null'
                          steps:
                            type:
                            - array
                            - 'null'
                            items:
                              type: object
                              properties:
                                expectedResult:
                                  type:
                                  - string
                                  - 'null'
                                data:
                                  type:
                                  - string
                                  - 'null'
                                description:
                                  type:
                                  - string
                                  - 'null'
                                testCaseKey:
                                  type:
                                  - string
                                  - 'null'
                              additionalProperties: false
                        additionalProperties: false
                      automation:
                        required:
                        - name
                        type: object
                        properties:
                          name:
                            minLength: 1
                            type: string
                          externalId:
                            type:
                            - string
                            - 'null'
                          content:
                            type:
                            - string
                            - 'null'
                        additionalProperties: false
                      requirements:
                        type:
                        - array
                        - 'null'
                        items:
                          type: string
                      folder:
                        type:
                        - string
                        - 'null'
                      folderId:
                        type:
                        - string
                        - 'null'
                        format: uuid
                    additionalProperties: false
              additionalProperties: false
            examples:
              Quick start example:
                value:
                  tests:
                  - testType: Manual
                    fields:
                      summary: Empty test with summary only
                  - testType: Manual
                    fields:
                      summary: Test with summary, description and precondition only
                      description: Some description
                    ttmFields:
                      precondition: Some precondition
                  - testType: Manual
                    fields:
                      summary: Test with summary, description, precondition and steps
                      description: Some description
                    ttmFields:
                      precondition: Some precondition
                      steps:
                      - description: Step with description only
                      - description: Step with description and expected result
                        expectedResult: Expected result of the step
                      - description: Step with description, expected result and data
                        expectedResult: Step with description, expected result and data
                        data: Step with description, expected result and data
                  - testType: Manual
                    fields:
                      summary: Test with custom fields (Please replace the custom fields to real fields from your account)
                    customFields:
                      custom summary field: Custom summary text
                      custom status field: MyCustomStatus
              Complex example:
                value:
                  folder: Sanity tests/Login feature
                  callbackUrl: http://yourPostEndpoint
                  tests:
                  - testType: Manual
                    fields:
                      summary: Test example with common used fields
                      description: Please replace the issues in "requirements" and "testCase" fields to real issues from your Jira account
                      status: In Progress
                      priority: High
                      labels:
                      - My Label
                    ttmFields:
                      precondition: You need internet connection
                      steps:
                      - description: Open the browser
                      - description: 'Type the url: "https://example.com/login"'
                      - description: Enter username and password, and click login
                        expectedResult: Login should successful, the next step is a clean up test (child test)
                        data: Website to login is https://api.ttm4j.tricentis.com/
                      - testCaseKey: PR-1
                    requirements:
                    - PR-10
                    - PR-11
                  - testType: Manual
                    fields:
                      summary: Test in a specific folder
                      description: 'Note: the folder will be created if it does not exist'
                    folder: Specific folder/Feature 1
                  - testType: Manual
                    fields:
                      summary: Test in a specific folder (by parent id. please replace this ID to a real id from your account)
                    folderId: 160441c9-6a84-4dc9-aaa8-cfbaaf736497
                  - testType: Manual
                    fields:
                      summary: Test with custom fields (Please replace the custom fields to real fields from your account)
                    customFields:
                      custom summary field: Custom summary text
                      custom status field: MyCustomStatus
                  - testType: Automated
                    fields:
                      summary: Automated test case (Should include "automation" field)
                    automation:
                      name: Automation name
                      externalId: '12345'
                      content: Automation content
      responses:
        '202':
          description: The job to create the test cases was successfully scheduled.
          content:
            application/json:
              schema:
                type: object
                properties:
                  folder:
                    type:
                    - string
                    - 'null'
                  folderId:
                    type:
                    - string
                    - 'null'
                    format: uuid
                  callbackUrl:
                    type:
                    - string
                    - 'null'
                  tests:
                    type:
                    - array
                    - 'null'
                    items:
                      required:
                      - testType
                      type: object
                      properties:
                        testType:
                          enum:
                          - Manual
                          - Automated
                          type: string
                        fields:
                          type: object
                          properties:
                            components:
                              type:
                              - array
                              - 'null'
                              items:
                                type: string
                            summary:
                              type:
                              - string
                              - 'null'
                            description:
                              type:
                              - string
                              - 'null'
                            status:
                              type:
                              - string
                              - 'null'
                            priority:
                              type:
                              - string
                              - 'null'
                            labels:
                              type:
                              - array
                              - 'null'
                              items:
                                type: string
                          additionalProperties: false
                        customFields:
                          type:
                          - object
                          - 'null'
                          additionalProperties: {}
                        ttmFields:
                          type: object
                          properties:
                            precondition:
                              type:
                              - string
                              - 'null'
                            steps:
                              type:
                              - array
                              - 'null'
                              items:
                                type: object
                                properties:
                                  expectedResult:
                                    type:
                                    - string
                                    - 'null'
                                  data:
                                    type:
                                    - string
                                    - 'null'
                                  description:
                                    type:
                                    - string
                                    - 'null'
                                  testCaseKey:
                                    type:
                                    - string
                                    - 'null'
                                additionalProperties: false
                          additionalProperties: false
                        automation:
                          required:
                          - name
                          type: object
                          properties:
                            name:
                              minLength: 1
                              type: string
                            externalId:
                              type:
                              - string
                              - 'null'
                            content:
                              type:
                              - string
                              - 'null'
                          additionalProperties: false
                        requirements:
                          type:
                          - array
                          - 'null'
                          items:
                            type: string
                        folder:
                          type:
                          - string
                          - 'null'
                        folderId:
                          type:
                          - string
                          - 'null'
                          format: uuid
                      additionalProperties: false
                additionalProperties: false
              examples:
                Create tests job created:
                  value:
                    jobId: 51d3c699-6319-4f33-adf9-f399a1510ce4
        '400':
          description: '`Invalid parameters.'
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type:
                    - string
                    - 'null'
                  title:
                    type:
                    - string
                    - 'null'
                  status:
                    type:
                    - integer
                    - 'null'
                    format: int32
                  detail:
                    type:
                    - string
                    - 'null'
                  instance:
                    type:
                    - string
                    - 'null'
                additionalProperties: {}
              examples:
                BadDataResponse:
                  value:
                    message: bad data
        '401':
          description: '`Unauthorized`.'
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type:
                    - string
                    - 'null'
                  title:
                    type:
                    - string
                    - 'null'
                  status:
                    type:
                    - integer
                    - 'null'
                    format: int32
                  detail:
                    type:
                    - string
                    - 'null'
                  instance:
                    type:
                    - string
                    - 'null'
                additionalProperties: {}
              examples:
                UnauthorizedResponse:
                  value:
                    message: unauthorized
        '404':
          description: '`Not Found`.'
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type:
                    - string
                    - 'null'
    

# --- truncated at 32 KB (97 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tricentis/refs/heads/main/openapi/tricentis-test-cases-api-openapi.yml