API


Tuskr provides a powerful and easy REST API that enables you to programmatically access the software.

Authentication

To use the API an access token must be passed for every request. The token must be sent in the HTTP header like this:

Authorization: Bearer YourPermanentAccessTokenHere

To obtain a permanent access token, go to Top MenuAPI. Treat this token as a secret. Anybody with access to the token can access, modify or delete your data.

Authorization

The API request will be treated as a request coming from the user whose access token is used for that request. The API call will be allowed only if the user has the privilege. Otherwise, the call will fail with a HTTP status code of 403 (Forbidden).

Rate Limiting

To prevent abuse, there is a limit on the number of API calls you can make per hour. This limit applies to your entire account, not just users. The rate limit is currently 1200 requests per hour.

Your Tenant ID

All API calls require a tenant ID to be specified. Tenant ID is the unique ID of your account. This will be the same for all users under the account. It will be a string like this: 5f465f45-37d2-4209-8764-3b0f8aee1754.

To get your account's Tenant ID, go to Top MenuAPI

API Calls

HTTP Request
POST https://api.tuskr.live/api/tenant/<tenant-id>/test-case
HTTP Request Body means mandatory

The request body must be a JSON object. This object must contain the key data and its value must be the JSON object having the request details. The example below should make this clearer.

The request object should have the following details:

ParameterKeyType
NamenameString.
DescriptiondescriptionString.
ProjectprojectString. ID or name .
Test SuitetestSuiteString. ID or name .
Test Suite SectiontestSuiteSectionString. ID or name .
Test Case TypetestCaseTypeString. ID or name .
Estimated Execution TimeestimatedTimeInMinutes Integer. The estimate time in minutes required to execute this test case.
Custom FieldscustomFieldsA JSON object. See example.
Return Value

On success, an HTTP 200 response is returned and the body contains a JSON object of the test case. In case of an error, a non-200 code is returned and the body of the response contains the error message.

Example

The following call creates a test case along with some custom fields.

curl --location  \
    --request POST 'https://api.tuskr.live/api/tenant/07bdb096-dac9-410b-a5fb-10b7c67ac792/test-case' \
    --header 'Authorization: Bearer IYguRJ3AwA41tF0fpCKvbDRySZD7We1FD4lsyyKS' \
    --header 'Content-Type: application/json' \
    --data-raw '{
       "data": {
           "name": "A test case created from API",
           "project": "Acme Shopping App",
           "testSuite": "Checkout",
           "testSuiteSection": "Payment Choices",
           "testCaseType": "Functional",
           "estimatedTimeInMinutes": 15,
           "customFields": {
               "url": "https://acme.app/checkout",
               "stepsWithExpectedResults": [
                   {
                       "step": 1,
                       "description": "step 1",
                       "expectedResult": "expected 1"
                   },
                   {
                       "step": 2,
                       "description": "step 2",
                       "expectedResult": "expected 2"
                   }
               ],
               "multi_select": [ "option 1", "option 2" ],
               "date": "2021-08-24",
           }
       }}'
HTTP Request
POST https://api.tuskr.live/api/tenant/<tenant-id>/test-case/import
HTTP Request Body means mandatory

The request body must be a JSON object. This object must contain the key data and its value must be the JSON object having the request details. The example below should make this clearer.

The request object should have the following details:

ParameterKeyType
ProjectprojectString. ID or name .
Test CasestestCasesJSON array of objects where every object represents a test case. Refer to the "Add test case" API call for the details of this object.
OptionsoptionsA JSON object with two keys: createMissingSuites and createMissingSections. Their values can be either true or false. If true, then if a suite or section is supplied in a test case that does not exist in the project, it will be created. If false, then if a suite or a section supplied in a test case that does not exist in the project, an error will be returned. Default is false.
Return Value

On success, an HTTP 200 response is returned and the body contains a JSON object of the test case. In case of an error, a non-200 code is returned and the body of the response contains the error message. The response object will have a rowsWithErrors property that will contain an array of errors encountered for individual test case object present in the request.

       {
           "totalTestCases": 10,
           "successCount": 9,
           "errorCount": 1,
           "rowsWithError": [
             {
               "record": 2,
               "errorMessage": "No entry found for Manager."
             }
           ]
       }
       
Example

The following call creates a test case along with some custom fields. It will also result in creation of a suite and a section.

curl --location  \
    --request POST 'https://api.tuskr.live/api/tenant/07bdb096-dac9-410b-a5fb-10b7c67ac792/test-case/import' \
    --header 'Authorization: Bearer IYguRJ3AwA41tF0fpCKvbDRySZD7We1FD4lsyyKS' \
    --header 'Content-Type: application/json' \
    --data-raw '{
            "data": {
                "project": "Acme Shopping",
                "testCases": [
                    {
                        "name": "A test case imported from API",
                        "testSuite": "New Suite",
                        "testSuiteSection": "New Section",
                        "estimatedTimeInMinutes": 20,
                        "testCaseType": "Functional",
                        "customFields": {
                            "datetype": "2022-01-18",
                            "dropdown": "option 1",
                            "string": "text data",
                            "multi": ["option 1","option 2"],
                            "stepsWithExpectedResults": [
                                {
                                    "step": 1,
                                    "description": "step 1",
                                    "expectedResult": "expected 1"
                                },
                                {
                                    "step": 2,
                                    "description": "step 2",
                                    "expectedResult": "expected 2"
                                }
                          ],
                          "integer": 10,
                          "url": "https://tuskr.app",
                          "checkbox": true,
                          "text_single_line": "dummy string data"
                        }
                    }
                ],
                "options": {
                  "createMissingSuites": true,
                  "createMissingSections": true
                }
            }
       }}'
HTTP Request
POST https://api.tuskr.live/api/tenant/<tenant-id>/test-run-result/bulk
HTTP Request Body means mandatory

The request body must be a JSON object. This object must contain the key data and its value must be the JSON object having the request details. The example below should make this clearer.

The request object should have the following details:

ParameterKeyType
Result StatusstatusString. Result status key. E.g. PASSED.
Test RuntestRunString. ID or name .
Test CasestestCasesArray of IDs, keys or names . This result will be applied to all test cases specified in this list.
Assigned ToassignedTo String. ID, name or email of the user. If present, the test case in this test run will be assigned to this user.
Commentscomments String
Time SpenttimeSpentInMinutes Integer
Custom FieldscustomFieldsA JSON object. See example.
Return Value

On success, an HTTP 200 response is returned and the body contains a JSON object of the test run result. In case of an error, a non-200 code is returned and the body of the response contains the error message.

Example

The following call marks three test cases as failed and assigns them to Peter. It also submits the custom fields.

curl --location  \
     --request POST 'https://api.tuskr.live/api/tenant/07bdb096-dac9-410b-a5fb-10b7c67ac792/test-run-result/bulk' \
     --header 'Authorization: Bearer KYguRJ3AwA41tF0fpCKvbDRySZD7We1FD4lsyyKm' \
     --header 'Content-Type: application/json' \
     --data-raw '{
             "data": {
                 "comments": "this is an example of bulk add result",
                 "timeSpentInMinutes": 10,
                 "status": "FAILED",
                 "assignedTo": "peter@mycompany.co",
                 "testRun": "Release Build 22-10-2021",
                 "testCases": ["C-2", "Pagination", "e590699d-88df-430f-b551-98753512914d"],
                 "customFields": {
                     "steps": [
                         {
                             "step": 1,
                             "description": "step 1"
                         }
                     ],
                     "text": "some text...",
                     "string": "Hello World!",
                     "stepsWithExpectedResults": [
                         {
                             "step": 1,
                             "description": "step 1",
                             "expectedResult": "expected result 1"
                         }
                     ],
                     "multi_select": [
                         "option 1",
                         "option 2"
                     ],
                     "date": "2021-08-26",
                     "integer": 108,
                     "dropdown": "option 1",
                     "checkbox": true
                 }
             }
        }'
Adding attachments

You can also attach files like screenshots and log files while creating results.

To add attachments, you will need do a POST multipart request with the body form parameter containing the JSON string representation of the request as described above, and the attachment form parameter containing the files as shown below.

The files will be attached to all result records for the specified test cases.

Only 2 attachments with max size of 5 MB each are allowed in this API call.

curl --location  \
     --request POST 'https://api.tuskr.live/api/tenant/07bdb096-dac9-410b-a5fb-10b7c67ac792/test-run-result/bulk' \
     --header 'Authorization: Bearer KYguRJ3AwA41tF0fpCKvbDRySZD7We1FD4lsyyKm' \
     -F 'body="{\"data\": {\"comments\": \"Sample comment\",\"timeSpentInMinutes\": 10,\"status\": \"FAILED\",\"testRun\": \"Alpha 3\",\"testCases\": [\"C-1\", \"Grid view\", \"4ded1648-6fc9-499b-a057-0482263d2f26\"],\"customFields\": {\"steps\": [{\"step\": 1,\"description\": \"step 1 description\"}]}}}"' \
     -F 'attachment=@"/Users/joe/screenshot.png"' \
     -F 'attachment=@"/Users/joe/error-log.txt"'