NAV

PractiTest API V2

Welcome to the PractiTest’s REST API V2!

The REST API is designed for developers who want to integrate PractiTest into their application, synchronize issue trackers or develop any other tool integration with PractiTest. The API also enables organizations to update their automated test results into PractiTest.

We have language bindings in Shell, Ruby, Python, Java and C#! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

JSON API

All along this api we’ve embraced JSON API standards, for share conventions and to save you (and us) precious time.

API rate limit

PT has active policies that limit the number of API calls that can be made per minute by each account.

If an account performs more than 30 API calls in a single minute you will get an error indicating this issue. The error will stop any further calls from reaching the server during that minute, but once the minute passes, you will be able to continue sending calls, there is nothing else that needs to be done (other than solving the the problem of multiple / parallel API calls ).

The idea behind this policy is to help users detect possible issues where the API is being implemented incorrectly, as well as to limit potential disruptions to our service due to this type of incorrect API implementations.

If you have any reason to believe that you need a higher rate limit, please contact our support.

Base URL

Sometimes you may see in the description of resource [BASE_URL]. The reason is that this is dynamic and may change, depends on which datacenter you’re working on.

If your account is hosted in US servers (url is https://prod.practitest.com), then the BASE_URL should be: https://api.practitest.com For EU servers, the BASE_URL is: https://eu1-prod-api.practitest.app/

Assigned To

You can assign an entity to a User or to a Group using the assigned-to-id and assigned-to-type. When you want to assign an entity to a Group, you need to make sure “Assign to Group” is enabled in your Project General Settings.

assigned-to-id and assigned-to-type are not required. If only assigned-to-id is passed, then type will be considered as user. So when assign to a group is desired, “assigned-to-type: group” must be passed.

Code examples

We put popular languages code examples under Github. Please feel free to view, and pull request if you have any updates: PractiTest Api Code Examples in Github.

Python

GET example for retrieving all projects

POST example for creating a new instance

PUT example for updating a specific instance

DELETE example for deleting a specific instance

POST example (with attachments) for Python version 2 for uploading test results to PractiTest with files

POST example (with attachments) for Python version 3 for uploading test results to PractiTest with files

Ruby

GET example for retrieving all projects

POST example for creating a new instance

PUT example for updating a specific instance

DELETE example for deleting a specific instance

POST example (with attachments) for uploading test results to PractiTest with files

Selenium example with POST request for uploading test results to PractiTest with steps

Java

GET example for retrieving all projects

POST example for creating a new instance

PUT example for updating a specific instance

DELETE example for deleting a specific instance

POST example (with attachments) for uploading test results to PractiTest with files

C sharp (.Net)

GET example for retrieving all projects will be added soon.

POST example for creating a new instance

PUT example for updating a specific instance

DELETE example for deleting a specific instance

POST example (with attachments) for uploading test results to PractiTest with files

Authentication

Authentication Options

# Basic authentication:
    curl -H "Content-Type: application/json" \
     -u YOUR_EMAIL:YOUR_TOKEN  \
    https://api.practitest.com/api/v2/projects.json
# IS THE SAME AS (as parameters):
    curl -H "Content-Type: application/json" \
    https://api.practitest.com/api/v2/projects.json?developer_email=YOUR_EMAIL&api_token=YOUR_TOKEN
# IS THE SAME AS (via header):
    curl -H "Content-Type: application/json" \
    -H "PTToken: YOUR_TOKEN" \
    https://api.practitest.com/api/v2/projects.json

Make sure to replace YOUR_TOKEN with your API token.

PractiTest uses API tokens for authentication. You can create a new API token by going to the Account Settings - “API Tokens”, or going to your personal settings for Personal Tokens. Please visit API tokens for more information. API expects the API-token to be included in all API requests to the server. There are three ways to authenticate to PractiTest API V2 (you can choose anyone of the three):

API Token types

This command: https://api.practitest.com/api/v2/projects.json?api_token=xx&developer_email=admin%40pt.com&page[number]=1&page[size]=2", returns JSON structured like below:

{
  "data": [
    {
      "id": "4581",
      "type": "projects",
      "attributes": {
        "name": "Sanity check (Rails 4)",
        "created-at": "2016-07-28T13:34:51Z",
        "automation-support": false,
        "enable-delete-issues": false,
        "time-management-support": false
      }
    },
    {
      "id": "4578",
      "type": "projects",
      "attributes": {
        "name": "Sanity Check (screen captures)",
        "created-at": "2016-06-20T11:32:52Z",
        "automation-support": false,
        "enable-delete-issues": true,
        "time-management-support": false
      }
    }
  ],
  "links": {
    "self": "https://api.practitest.com/api/v2/projects.json?api_token=afb913899fc295e809255fbdb4fbc1fb37296250&developer_email=admin%40pt.com&page%5Bnumber%5D=1&page%5Bsize%5D=2",
    "next": "https://api.practitest.com/api/v2/projects.json?api_token=afb913899fc295e809255fbdb4fbc1fb37296250&developer_email=admin%40pt.com&page%5Bnumber%5D=2&page%5Bsize%5D=2",
    "last": "https://api.practitest.com/api/v2/projects.json?api_token=afb913899fc295e809255fbdb4fbc1fb37296250&developer_email=admin%40pt.com&page%5Bnumber%5D=3&page%5Bsize%5D=2"
  },
  "meta": {
    "current-page": 1,
    "next-page": 2,
    "prev-page": null,
    "total-pages": 3,
    "total-count": 5
  }
}

PractiTest supports two types of API Tokens: Personal API Tokens (PAT), and Account tokens.

Personal Api Token - PAT

This token type was introduced in May 2020, and is being gradually supported in all the API resources; for each resource, there is a separate description for this token type.

When working with the Personal API Token, each user has its own token. PractiTest will provide access to API resources based on the PAT user’s permissions. By default, actions made with PAT will be recorded as the PAT owner’s actions (unless Impersonation is in use)

For example -> in the Projects API request, with Account Token, you may list all projects in the account; PAT allows you to show only the projects in the account that the specific user has access to.

If 'Impersonation’ is enabled by the account owner to the PAT user, the PAT user will have the ability to impersonate someone else with this token. For example:

This doesn’t give the impersonating PAT user the ability to override permissions. For example: If a PAT user is not permitted to change an issue according to the project workflow, he will not be able to do so, no matter if the user has the impersonation attribute enabled or not.

Account API Token

This is the most powerful API token type, with access to all projects in the account, and all the API resources described in this document.

Pagination

Get all resources supports paginations, for example, to retrive projects:

HTTP Request

GET http://api.practitest.com/api/v2/projects.json

Pagination Parameters

Parameter Default Description
page[number] 1 the page number starting from 1
page[size] 100 number of entities displayed on a page, the maximum is 100 entities displayed per page

Projects

GET all projects

This endpoint retrieves all projects.

HTTP Request

GET https://api.practitest.com/api/v2/projects.json

Query Parameters

Parameter Default Description
page[number] 1 the page number starting from 1
page[size] 100 number of entities displayed per page

Note: The example query parameters above use unencoded [ and ] characters simply for readability. In practice, these characters must be percent-encoded as page%5Bnumber%5D and page%5Bsize%5D

Here’s the examples of the JSON requests and responses that you may get when submitting a GET request

Remember, you can see examples in the dark area to the right.

PAT Support

Shows user’s projects of the account.

Show a specific project

curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
https://api.practitest.com/api/v2/projects/22.json

This command returns JSON structured like below:


{
  "data": {
    "id": "22",
    "type": "projects",
    "attributes": {
      "name": "Verticals",
      "created-at": "2021-10-04T12:01:05Z",
      "automation-support": true,
      "enable-delete-issues": false,
      "time-management-support": true
    }
  }
}

This endpoint shows a specific project

HTTP Request

GET https://api.practitest.com/api/v2/projects/PROJECT_ID.json

Groups

GET all groups in your project

    curl -H "Content-Type: application/json" \
    -u YOUR_EMAIL:YOUR_TOKEN \
    https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/groups.json

This command: https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/groups.json?developer_email=YOUR_EMAIL&api_token=YOUR_TOKEN,
OR
this command: curl -H “Content-Type:application/json” \ -H “PTToken: YOUR_TOKEN” \ https://api.practitest.com/api/v2/projects/4566/groups.json ,
returns JSON structured like below:

{
  "data": [
    {
      "id": "353",
      "type": "groups",
      "attributes": {
        "name": "Administrators",
        "created-at": "2020-12-09T17:00:24+02:00"
      }
    },
    {
      "id": "355",
      "type": "groups",
      "attributes": {
        "name": "Developers",
        "created-at": "2020-12-09T17:00:24+02:00"
      }
    },
    {
      "id": "354",
      "type": "groups",
      "attributes": {
        "name": "Testers",
        "created-at": "2020-12-09T17:00:24+02:00"
      }
    }
  ],
  "links": {},
  "meta": {
    "current-page": 1,
    "next-page": null,
    "prev-page": null,
    "total-pages": 1,
    "total-count": 3
  }
}

This endpoint retrieves all groups for specific project.

HTTP Request

https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/groups.json

PAT Support

Supported - if the user has the permissions to edit Groups

Show Group information

    curl -H "Content-Type: application/json" \
    -u YOUR_EMAIL:YOUR_TOKEN \
    https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/groups/GROUP_ID.json

This command: https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/groups/322.json?developer_email=YOUR_EMAIL&api_token=YOUR_TOKEN,
OR
this command: curl -H “Content-Type:application/json” \ -H “PTToken: YOUR_TOKEN” \ https://api.practitest.com/api/v2/projects/4566/groups/322.json ,
returns JSON structured like below:

{
  "data": {
    "id": "6",
    "type": "groups",
    "attributes": {
      "name": "Testers",
      "created-at": "2019-04-18T17:03:39+03:00",
      "permissions": [
        {
          "title": "Requirements - View",
          "description": "View Requirements",
          "allowed": true
        },
        {
          "title": "Requirements - Editor",
          "description": "Create, Edit and View Requirements",
          "allowed": true
        },
        {
          "title": "Requirements - Admin",
          "description": "Create, Edit, Delete and View Requirements",
          "allowed": true
        },
        {
          "title": "Tests - View",
          "description": "View Tests, View Runs",
          "allowed": true
        },
        {
          "title": "Runs",
          "description": "View Tests, Run Tests, View and Edit Instances & Runs",
          "allowed": true
        },
        {
          "title": "Runs - Admin",
          "description": "Same as Runs, with the option to Delete Instances and Runs",
          "allowed": true
        },
        {
          "title": "Tests - Editor",
          "description": "Create, Edit and View Tests; Run Tests; View and Edit Instances & Runs",
          "allowed": true
        },
        {
          "title": "Tests - Admin",
          "description": "Create, Edit, Delete and View Tests; Run Tests; View, Edit and Delete Runs, Create TestSets permutations",
          "allowed": true
        },
        {
          "title": "Issues - View",
          "description": "View Issues",
          "allowed": true
        },
        {
          "title": "Issues - Status Modifier",
          "description": "View Issues; Change Issue Status (by workflow transitions; Add comments to Issues",
          "allowed": true
        },
        {
          "title": "Issues - Editor",
          "description": "Create, Edit and View Issues",
          "allowed": true
        },
        {
          "title": "Issues - Admin",
          "description": "Create, Edit, Delete and View Issues. Delete on specific projects.",
          "allowed": false
        },
        {
          "title": "Reports",
          "description": "View, Create, Edit and Delete Reports",
          "allowed": true
        },
        {
          "title": "Dashboard Customization",
          "description": "Customize dashboard items",
          "allowed": false
        },
        {
          "title": "Dashboard - Private",
          "description": "Customize a private dashboard",
          "allowed": false
        },
        {
          "title": "Customization",
          "description": "Customize Custom fields",
          "allowed": false
        },
        {
          "title": "All Custom Views",
          "description": "Edit all custom views",
          "allowed": false
        },
        {
          "title": "Notification List",
          "description": "Enable users to add OTHER users to a notification list of an entity.",
          "allowed": false
        },
        {
          "title": "Workflow",
          "description": "Customize Issue status workflow",
          "allowed": false
        },
        {
          "title": "Project, Users & Permissions, Integrations",
          "description": "Add and Delete Users & Groups, Customize Permissions, Change Project Name and Logo, Set Integrations and Webhooks",
          "allowed": false
        }
      ]
    }
  }
}

This endpoint shows a specific group in your project.

HTTP Request

https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/groups/GROUP_ID.json

PAT Support

Supported - if the user has the permissions to edit Groups

Users

GET all users in your account

curl -H "Content-Type: application/json" \
-u YOUR_EMAIL:YOUR_TOKEN  \
https://api.practitest.com/api/v2/users.json
# IS THE SAME AS:
curl -H "Content-Type: application/json" \
https://api.practitest.com/api/v2/users.json?developer_email=YOUR_EMAIL&api_token=YOUR_TOKEN

Query Parameters - pagination

string token = "xxx";
string developerEmail = "my@email.address";

var request = WebRequest.Create("https://api.practitest.com/api/v2/users.json");
//request.PreAuthenticate = true;
string authInfo = Convert.ToBase64String(Encoding.Default.GetBytes(developerEmail + ":" + token));
request.Headers["Authorization"] = "Basic " + authInfo;

var response = request.GetResponse();
Console.WriteLine(response.Headers);

This command: https://api.practitest.com/api/v2/users.json?api_token=YOUR_TOKEN&developer_email=YOUR_EMAIL, returns JSON structured like below:

{
  "data": [
    {
      "id": "53811",
      "type": "users",
      "attributes": {
        "first-name": null,
        "last-name": null,
        "display-name": "chris.z@rd.com",
        "email": "chris.z@rd.com",
        "time-zone": "UTC",
        "created-at": "2016-05-30T16:45:02+03:00"
      }
    },
    {
      "id": "538724",
      "type": "users",
      "attributes": {
        "first-name": null,
        "last-name": null,
        "display-name": "monica@gmail.com",
        "email": "monica@gmail.com",
        "time-zone": "UTC",
        "created-at": "2016-06-20T14:35:19+03:00"
      }
    },
    {
      "id": "539467",
      "type": "users",
      "attributes": {
        "first-name": null,
        "last-name": null,
        "display-name": "pascal@most.com",
        "email": "pascal@most.com",
        "time-zone": "UTC",
        "created-at": "2016-07-07T17:44:15+03:00"
      }
    },
    {
      "id": "539598",
      "type": "users",
      "attributes": {
        "first-name": null,
        "last-name": null,
        "display-name": "phillip.rik@pt.com",
        "email": "phillip.rik@pt.com",
        "time-zone": "UTC",
        "created-at": "2016-07-27T15:08:14+03:00"
      }
    },
    {
      "id": "539976",
      "type": "users",
      "attributes": {
        "first-name": null,
        "last-name": null,
        "display-name": "beck735306@pt.com",
        "email": "beck735306@pt.com",
        "time-zone": "UTC",
        "created-at": "2016-08-08T15:05:13+03:00"
      }
    }
  ],
  "links": {},
  "meta": {
    "current-page": 1,
    "next-page": null,
    "prev-page": null,
    "total-pages": 1,
    "total-count": 5
  }
}

This endpoint retrieves all users.

HTTP Request

https://api.practitest.com/api/v2/users.json

Query Parameters - pagination

Parameters* Description
email Filter a user by email address
active Get only active users, if equal to ‘true’.

Here’s the examples of the JSON requests and response that you may get when submitting a GET request

PAT Support

Shows list of users only to projects that a user belongs to.

Add a user

# creates a user:
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
-X POST https://api.practitest.com/api/v2/users.json \
-d '{"data": {"attributes": {"email": "NEW_USER_EMAIL", "first-name": "FIRST_NAME", "last-name": "LAST_NAME", "display-name": "DISPLAY_NAME"}}}'


This endpoint creates a new User.
Will return 422 if user already exists.

HTTP Request

POST https://api.practitest.com/api/v2/users.json

Parameters Description required?
data/attributes/email email true
data/attributes/first-name First Name false
data/attributes/last-name Last Name false
data/attributes/display-name Display name of the user in the system false

This command returns JSON structured like below:

{
  "data": {
    "id": "22",
    "type": "users",
    "attributes": {
      "first-name": "Stas",
      "last-name": "Krichevsky",
      "display-name": "Stas Krichevsky",
      "email": "stask+test@practitest.com",
      "time-zone": null,
      "created-at": "2019-07-10T20:18:34Z"
    }
  }
}

Show a specific user

curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
https://api.practitest.com/api/v2/users/22.json

Query Parameters - pagination

This command returns JSON structured like below:

{
  "data": {
    "id": "22",
    "type": "users",
    "attributes": {
      "first-name": "Stas",
      "last-name": "Krichevsky",
      "display-name": "Stas Krichevsky",
      "email": "stask+test@practitest.com",
      "time-zone": null,
      "created-at": "2019-07-10T20:18:34Z"
    }
  }
}

This endpoint shows a specific user

HTTP Request

GET https://api.practitest.com/api/v2/users/USER_ID.json

Update a user

curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
-X PUT https://api.practitest.com/api/v2/users/USER_ID.json
-d '{"data": {"attributes": {"display-name": "NEW_DISPLAY_NAME"}}}'

This endpoint updates a specific user.

HTTP Request

PUT https://api.practitest.com/api/v2/users/USER_ID.json

Parameters

Available parameters Description
data/attributes/first-name First Name
data/attributes/last-name Last Name
data/attributes/display-name Display name of the user in the system

Users Projects

GET List all projects the user has access to

curl -H "Content-Type: application/json" \
-u YOUR_EMAIL:YOUR_TOKEN  \
https://api.practitest.com/api/v2/users/USER_ID/projects.json
# IS THE SAME AS:
curl -H "Content-Type: application/json" \
https://api.practitest.com/api/v2/users/USER_ID/projects.json?developer_email=YOUR_EMAIL&api_token=YOUR_TOKEN

This command returns JSON structured like below:

{
  "data": [
    {
      "id": "2",
      "type": "projects",
      "attributes": {
        "name": "jira cloud",
        "created-at": "2019-04-18T14:03:38Z",
        "automation-support": false,
        "enable-delete-issues": false,
        "time-management-support": true,
        "groups": [
          {
            "id": 5,
            "name": "Administrators"
          }
        ]
      }
    }
  ],
  "links": {
    "self": "http://localhost:3000/api/v2/users/2/projects.json?page%5Bnumber%5D=1&page%5Bsize%5D=100",
    "first": "http://localhost:3000/api/v2/users/2/projects.json?page%5Bnumber%5D=1&page%5Bsize%5D=100",
    "prev": null,
    "next": null,
    "last": "http://localhost:3000/api/v2/users/2/projects.json?page%5Bnumber%5D=1&page%5Bsize%5D=100"
  },
  "meta": {
    "current-page": 1,
    "next-page": null,
    "prev-page": null,
    "total-pages": 1,
    "total-count": 1
  }
}

This endpoint retrieves all projects that the user has access to.

HTTP Request

https://api.practitest.com/api/v2/users/USER_ID/projects.json

Query Parameters - pagination

Here’s the examples of the JSON requests and response that you may get when submitting a GET request

Update a user project (add user access to specific project and group)

curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
-X PUT https://api.practitest.com/api/v2/users/USER_ID/projects.json
-d '{"data": {"projects": [{"id": 2, "groups": [{"id": 5}]}]}}'

Add access to specific project and group.

Adds the user to groups of a project. Multiple projects and multiple groups can be specified. All projects you want to give this user access to should be specified. If the user had access to projects A and B and you call this endpoint again with only project B, access to A will be revoked.

HTTP Request

PUT https://api.practitest.com/api/v2/users/USER_ID/groups.json

Parameters

Parameters Description required?
data/projects An array of projects ids and groups ids for each true

projects and groups array - for example: [{"id": 2, "groups": [{"id": 5}, {"id": 6}]}, {"id": 4, "groups": [{"id": 11}]}] - means -> add the user to project #2 and groups #5 and #6, in addition add the user to project #4 and to group #11

Delete a user projects (revoke access)

curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
-X DELETE https://api.practitest.com/api/v2/users/USER_ID/projects.json

Revokes access to all project for specific user.

HTTP Request

DELETE https://api.practitest.com/api/v2/users/USER_ID/projects.json

Attachments

GET attachments for an entity

curl -H "Content-Type:application/json" \
-H "PTToken: YOUR_TOKEN" \
https://api.practitest.com/api/v2/projects/4566/attachments.json?entity=issue&entity-id=34222

{
  "data": [
  {
    "id":"14635",
    "type":"attachments",
    "attributes":{
      "name":"Screen_Shot_2020-05-25_at_15.32.46.png",
      "size":66220
      }
   }]
}

This endpoint retrieves all Attachments for a specific entity .

HTTP Request

GET [BASE_URL]/api/v2/projects/:project-id/attachments.json?entity=ENTITY&entity-id=ENTITY_ID

Query Parameters - pagination

Parameters* Description
entity The entity type: can be one of the following: requirement, test, testset, instance, step, step-run, issue
entity-id the entity id

Show a specific attachment

curl -H "PTToken: YOUR_TOKEN" \
-L https://api.practitest.com/api/v2/projects/4508/attachments/14635 --output downloaded.jpg

This will enables to download the attachment for local reporting.

HTTP Request

GET [BASE_URL]/api/v2/projects/:project-id/attachments/:attachment-id

Query Parameters

Parameters* Description
attachment-id The id that was retrieved from index method

Output

Returns binary attachment (you will need to use -L option in curl to follow redirects).

Create an attachment

# create an attachment
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
-X POST https://api.practitest.com/api/v2/projects/4566/attachments.json \
-d '{"entity": "issue", "entity-id": 23232, "data": { "type": "attachments",  "files": { "data": [ { "filename": "test_data.csv", "content_encoded": "whatever encoded data here.." } ] }  }}'

This endpoint creates attachment to an entity.

HTTP Request

POST https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/attachments.json

Parameters

Parameters Description required?
entity-id The id of the entity which the attachment relates to true
entity Any of: requirement, test, testset, instance, step, step-run, issue true
data/files/data attachments array (filename, and content_encoded) true

PAT Support

Supported - if the user has the permissions to edit the entity.

Delete a specific attachment

# create an attachment
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
-X DELETE https://api.practitest.com/api/v2/projects/4566/attachments/2322.json \

This endpoint creates attachment to an entity.

HTTP Request

DELETE https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/attachments/2322.json

Project Fields

GET all SYSTEM & CUSTOM fields in your project

curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
https://api.practitest.com/api/v2/projects/4566/fields.json

This command: https://api.practitest.com/api/v2/projects/4566/fields.json?api_token=xx&developer_email=admin%40pt.com&page[number]=1&page[size]=2", returns JSON structured like below:

{
  "data": [
    {
      "id": 88769,
      "type": "SystemField",
      "name": "Status",
      "field_format": "list",
      "possible_values": null,
      "uniq_name": "issue_status",
      "entities": [
        "Issue"
      ]
    },
    {
      "id": 48633,
      "type": "CustomField",
      "name": "Test Level",
      "field_format": "list",
      "possible_values": [
        "Blah",
        "Regression",
        "Relieve",
        "Sanity"
      ],
      "uniq_name": "___f_48633",
      "entities": [
        "TestSet",
        "Test"
      ]
    },
    {
      "id": 48634,
      "type": "CustomField",
      "name": "Testing Environment",
      "field_format": "list",
      "possible_values": [
        "Production",
        "Testing Lab",
        "Customer"
      ],
      "uniq_name": "___f_48634",
      "entities": [
        "Issue"
      ]
    },
    {
      "id": 48635,
      "type": "CustomField",
      "name": "Testing Project",
      "field_format": "linkedlist",
      "possible_values": {
        "Production": [
          "ASIA",
          "EUROPE",
          "AMERICA"
        ],
        "Testing Lab": [
          "Lab1",
          "Lab2",
          "Lab3"
        ],
        "Customer": [
          "ABC",
          "CBS",
          "NBC",
          "CNN"
        ]
      },
      "uniq_name": "___f_48635",
      "entities": [
        "Issue"
      ]
    }
  ]
}

This endpoint retrieves all fields.

HTTP Request

GET https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/fields.json

Query Parameters - pagination

Here’s the example of the JSON request and response that you may get when submitting a GET request

Remember, you can see examples in the dark area to the right.

PAT Support

Supported - if the user has the permissions to customize fields

Custom Fields

GET all custom fields in your project

curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
https://api.practitest.com/api/v2/projects/4566/custom_fields.json

This command: https://api.practitest.com/api/v2/projects/4566/custom_fields.json?api_token=xx&developer_email=admin%40pt.com&page[number]=1&page[size]=2", returns JSON structured like below:

{
  "data": [
    {
      "id": "45916",
      "type": "custom-fields",
      "attributes": {
        "name": "che",
        "field-format": "multilist",
        "project-id": 4566,
        "possible-values": [
          "dog",
          "cat"
        ],
        "parent-list-id": null,
        "possible-values-parent-cf-id": 45911,
        "created-at": "2016-12-19T14:00:45+02:00",
        "updated-at": "2016-12-19T14:00:45+02:00"
      }
    },
    {
      "id": "459187",
      "type": "custom-fields",
      "attributes": {
        "name": "Multilist (Dec 19th)",
        "field-format": "multilist",
        "project-id": 4566,
        "possible-values": [
          "one",
          "two",
          "three"
        ],
        "parent-list-id": null,
        "possible-values-parent-cf-id": null,
        "created-at": "2016-12-19T12:41:51+02:00",
        "updated-at": "2016-12-19T12:41:51+02:00"
      }
    }
  ],
  "links": {
    "self": "https://api.practitest.com/api/v2/projects/4566/custom_fields.json?api_token=a519a5d2ea4fad48e24ae929b03c753c68fb799c&developer_email=christine%40pt.com&page%5Bnumber%5D=1&page%5Bsize%5D=2",
    "next": "https://api.practitest.com/api/v2/projects/4566/custom_fields.json?api_token=a519a5d2ea4fad48e24ae929b03c753c68fb799c&developer_email=christine%40pt.com&page%5Bnumber%5D=2&page%5Bsize%5D=2",
    "last": "https://api.practitest.com/api/v2/projects/4566/custom_fields.json?api_token=a519a5d2ea4fad48e24ae929b03c753c68fb799c&developer_email=christine%40pt.com&page%5Bnumber%5D=19&page%5Bsize%5D=2"
  },
  "meta": {
    "current-page": 1,
    "next-page": 2,
    "prev-page": null,
    "total-pages": 19,
    "total-count": 37
  }
}

This endpoint retrieves all custom fields.

HTTP Request

GET https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/custom_fields.json

Query Parameters - pagination

Here’s the example of the JSON request and response that you may get when submitting a GET request

PAT Support

Supported - if the user has the permissions to customize fields

GET a specific custom field in your project

curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
https://api.practitest.com/api/v2/projects/4566/custom_fields/45893.json

This command: https://api.practitest.com/api/v2/projects/4566/custom_fields/45893.json?api_token=YOUR_TOKEN&developer_email=YOUR_EMAIL, returns JSON structured like below:

{
  "data": {
    "id": "45893",
    "type": "custom-fields",
    "attributes": {
      "name": "Test API2",
      "field-format": "list",
      "project-id": 4566,
      "possible-values": [
        "one",
        "five"
      ],
      "parent-list-id": null,
      "possible-values-parent-cf-id": null,
      "created-at": "2016-12-08T18:26:54+02:00",
      "updated-at": "2016-12-19T16:53:28+02:00"
    }
  }
}

This endpoint retrieves a specific custom field.

HTTP Request

GET https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/custom_fields/YOUR_CUSTOM_FIELD_ID.json

Here’s the example of the JSON request and response that you may get when submitting a GET request

PAT Support

Supported - if the user has the permissions to customize fields

PUT a specific custom field in your project

curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
-X PUT https://api.practitest.com/api/v2/projects/4566/custom_fields/45893.json \
-d '{"data": { "type": "custom_fields", "attributes": {"name":"Test API3", "possible-values": ["one","six"]}  } }'

The above command returns JSON structured like below:

{
  "data": {
    "id": "45893",
    "type": "custom-fields",
    "attributes": {
      "name": "Test API3",
      "field-format": "list",
      "project-id": 4566,
      "possible-values": [
        "one",
        "six"
      ],
      "parent-list-id": null,
      "possible-values-parent-cf-id": null,
      "created-at": "2016-12-08T18:26:54+02:00",
      "updated-at": "2016-12-20T14:39:24+02:00"
    }
  }
}

This endpoint updates a specific custom field.

HTTP Request

PUT https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/custom_fields/YOUR_CUSTOM_FIELD_ID.json

Query Parameters - pagination

Parameter Description
data/attributes/name the name of a custom field
data/attributes/possible-values values that can be set for a custom field
data/attributes/parent-list-id the id of a parent list that can be set for a “linked list” custom field
data/attributes/possible-values-parent-cf-id the id of an existing list where you can take values for a custom field

Here’s the example of the JSON request and response that you may get when submitting a PUT request

PAT Support

Supported - if the user has the permissions to customize fields

Requirements

GET all Requirements in your project

# Some request examples:

# Get all requirements of project #4566:
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
https://api.practitest.com/api/v2/projects/4566/requirements.json

# Get all requirements of project #4566, where filter-id is 323 and name is like login
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
https://api.practitest.com/api/v2/projects/4566/requirements.json?filter-id=323&name_like=login

# Get all requirements of project #4566, where autofilter filter-id is 323 and value is 1.5
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
https://api.practitest.com/api/v2/projects/4566/requirements.json?filter-id=323&autofilter-value=1.5

# Get all Requirements with display ids 2,4 from project #4566
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
https://api.practitest.com/api/v2/projects/4566/requirements.json?display-ids=2,4

# Get all requirements of project #4566 with linked entities
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
https://api.practitest.com/api/v2/projects/4566/requirements.json?relationships=true

This command: https://api.practitest.com/api/v2/projects/4566/requirements.json?api_token=xx&developer_email=admin%40pt.com&page[number]=1&page[size]=2", returns JSON structured like below:

{
  "data": [
    {
      "id": "1850360",
      "type": "requirements",
      "attributes": {
        "project-id": 1230,
        "display-id": 205,
        "name": "first name",
        "instances-count": 0,
        "run-status": "FAILED",
        "last-run": "2017-01-27T13:35:25+00:00",
        "assigned-to-id": null,
        "assigned-to-type": null,
        "planned-execution": null,
        "version": null,
        "priority": null,
        "custom-fields": {
        "---f-8282": "High",
        },
        "folder-id": null,
        "created-at": "2017-01-27T12:19:46+00:00",
        "updated-at": "2017-01-27T12:24:07+00:00"
    }
  }
  ],
  "links": {
    "self": "https://api.practitest.com/api/v2/projects/1282/requirements.json?api_token=YOUR_TOKEN
YOUR_TOKEN&developer_email=your_EMAIL&name_like=Issuer3&page%5Bnumber%5D=1&page%5Bsize%5D=6&set_filter_id=70859&set_ids=96530",
    "next": "https://api.practitest.com/api/v2/projects/1282/requirements.json?api_token=YOUR_TOKEN&developer_email=your_EMAIL&name_like=Issuer3&page%5Bnumber%5D=2&page%5Bsize%5D=6&set_filter_id=70859&set_ids=96530",
    "last": "https://api.practitest.com/api/v2/projects/1282/requirements.json?api_token=YOUR_TOKEN&developer_email=your_EMAIL&name_like=Issuer3&page%5Bnumber%5D=3&page%5Bsize%5D=6&set_filter_id=70859&set_ids=96530"
  },
  "meta": {
    "current-page": 1,
    "next-page": 2,
    "prev-page": null,
    "total-pages": 5,
    "total-count": 13
  }
}

This endpoint retrieves all Requirements.

HTTP Request

GET https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/requirements.json

Query Parameters - pagination

Parameters* Description
filter-id the Requirement’s filter id -> showing requirements that are in this filter
autofilter-value if filter is an auto-filter, you can provide the 1st level filter value
sub-autofilter-value if filter is a 2-level auto-filter, and you provided the 1st level autofilter-value, you can provide the 2nd level filter value
filter-user-id if filter uses current_user criteria in it, you should provide which is the this user (list of user ids)
display-ids filter Requirements with display-ids (separated by commas)
name_exact filter by Requirement name exact match; case sensitive!
name_like filter by Requirement name: case insensitive, phrase can be inside the name
relationships shows entities linked to requirements, should be equal to true

PAT Support

Supported - if the user has the permissions to view Requirements

Create a Requirement

# create a Requirement
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
-X POST https://api.practitest.com/api/v2/projects/4566/requirements.json \
-d '{"data": { "type": "requirements", "attributes": {"name": "one", "author-id": 4370, "priority": "highest", "custom-fields": { "---f-22": "Windows", "---f-24": ["ClientA", "ClientB"]}}  } }'

# create a Requirement with 2 test-ids:
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
-X POST https://api.practitest.com/api/v2/projects/4566/requirements.json \
-d '{"data": { "type": "requirements", "attributes": {"name": "one", "author-id": 4370, "priority": "highest"}, "traceability": {"test-ids": [32222,53333]} }}'

This endpoint creates a Requirement in your project.

HTTP Request

POST https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/requirements.json

Parameters Description required?
data/attributes/name name true
data/attributes/description description false
data/attributes/author-id user-id of author true (unless using PAT)
data/attributes/assigned-to-id user or group assigned-to id (not Display ID) - users list groups list false
data/attributes/assigned-to-type assigned-to type (user or group) false
data/attributes/version string of the requirement’s version false
data/attributes/priority string of the requirement’s priority false
data/attributes/custom-fields a hash of custom-fields with their value false
data/attributes/parent-id a parent’s requirement id false
data/traceability/test-ids an array of test-ids to add to the traceability of the new requirement false
data/attributes/tags an array of tags false

You can find at the right area (shell) an example of the request

PAT Support

Supported - if the user has the permissions to create a Requirement (Requirements - Editor)

The “author-id” parameter is not required, and can only be used (and override PAT user) if it has “impersonation” enabled

Show a specific Requirement

curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
https://api.practitest.com/api/v2/projects/4566/requirements/45893.json

This command: https://api.practitest.com/api/v2/projects/4566/requirements/45893.json?api_token=YOUR_TOKEN&developer_email=YOUR_EMAIL, returns JSON structured like below:

{
  "data": {
    "id": "1850344",
    "type": "requirements",
    "attributes": {
      "project-id": 1230,
      "display-id": 205,
      "name": "first name",
      "instances-count": 0,
      "run-status": "FAILED",
      "last-run": "2017-01-27T13:35:25+00:00",
      "assigned-to-id": null,
      "assigned-to-type": null,
      "planned-execution": null,
      "version": null,
      "priority": null,
      "custom-fields": {
      "---f-8282": "High",
      },
      "folder-id": null,
      "created-at": "2017-01-27T12:19:46+00:00",
      "updated-at": "2017-01-27T12:24:07+00:00"
  }
}
}

This endpoint shows a specific Requirement in your project.

HTTP Request

GET https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/requirements/YOUR_REQUIREMENT_ID.json

Here’s the example of the JSON request and response

Parameters* Description
relationships shows entities linked to requirements, should be equal to true

PAT Support

Supported - if the user has the permissions to view Requirements

Update a specific Requirement

curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
-X PUT https://api.practitest.com/api/v2/projects/4566/requirements/45893.json \
-d '{"data": { "type": "requirements", "attributes": {"priority": "highest", "custom-fields": { "---f-22": "Windows", "---f-24": ["ClientA", "ClientB"]}}  } }'

# some more examples:
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN  \
-X PUT https://api.practitest.com/api/v2/projects/4566/requirements/98019.json \
-d '{"data": { "type": "requirements", "attributes": {"parent-id": 32213, "priority": "2-high", "version": "1.5", "custom-fields": { "---f-45510": "5381"}}  } }'

curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN  \
-X PUT https://api.practitest.com/api/v2/projects/4566/requirements/98019.json \
-d '{"data": { "type": "requirements", "attributes": {"version": "1.5", "custom-fields": { "---f-45390": "Chrome"}}  } }'
{
  "data": {
    "id": "45893",
    "type": "requirements",
    "attributes": {
      ...
      "priority": "highest",
      "custom-fields": {
        "---f-22":"my text one",
        "---f-24": ["ClientA", ["ClientB"]]
      },
      ...
      "created-at": "2015-11-17T09:29:22+00:00",
      "updated-at": "2015-11-17T09:29:22+00:00"
    }
  }
}

This endpoint updates a specific Requirement.

HTTP Request

PUT https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/requirements/REQUIREMENT_ID.json

Parameters

Available parameters Description
data/attributes/name name
data/attributes/description description
data/attributes/assigned-to-id user or group assigned-to id (not Display ID) - users list groups list
data/attributes/assigned-to-type assigned-to type (user or group)
data/attributes/version string of the requirement’s version
data/attributes/priority string of the requirement’s priority
data/attributes/custom-fields a hash of custom-fields with their value
data/attributes/parent-id a parent’s requirement id
data/attributes/tags an array of tags
data/attributes/updated-by-user-id ID (not Display ID) of the user who made a change - users list

You can find at the right area an example of the JSON request and response

PAT Support

Supported - if the user has the permissions to edit a Requirements (Requirements - Editor)

History of a change by PAT user will be created automatically.

The “updated-by-user-id” parameter can only be used (and override PAT user) if it has “impersonation” enabled.

Delete a specific Requirement

curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
-X DELETE https://api.practitest.com/api/v2/projects/4566/requirements/45893.json

This endpoint deletes a specific Requirement.

HTTP Request

DELETE https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/requirements/YOUR_REQUIREMENT_ID.json

You can find at the right area an example of the JSON request and response

PAT Support

Supported - if the user has the permissions to delete Requirements

Requirement traceability

GET all tests linked to a specific requirement

This endpoint retrieves all tests linked to a specific requirement

HTTP Request

GET https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/requirements/YOUR_REQUIREMENT_ID/relationships/tests.json

PAT Support

Supported - if the user has the permissions to view Requirements

Replace linked tests for a specific requirement

# Some request examples:

# Replace tests linked to the requirement in project #4566:
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
-X PATCH https://api.practitest.com/api/v2/projects/4566/requirements/73365/relationships/tests.json \
-d '{"data": [{ "id": TEST_ID, "type": "tests" },{ "id": ANOTHER_TEST_ID, "type": "tests" }]}'

This endpoint replaces linked tests for a specific requirement

HTTP Request

PATCH https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/requirements/YOUR_REQUIREMENT_ID/relationships/tests.json

You can find at the right area an example of the JSON request and response

PAT Support

Supported - if the user has the permissions to edit Requirements

# Some request examples:

# Add tests linked to the requirement in project #4566:
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
-X POST https://api.practitest.com/api/v2/projects/4566/requirements/73365/relationships/tests.json \
-d '{"data": [{ "id": TEST_ID, "type": "tests" },{ "id": ANOTHER_TEST_ID, "type": "tests" }]}'

This endpoint links tests to a specific requirement

HTTP Request

POST http://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/requirements/YOUR_REQUIREMENT_ID/relationships/tests.json

PAT Support

Supported - if the user has the permissions to edit Requirements

Delete linked tests for a specific requirement

# Some request examples:

# Remove tests linked to the requirement in project #4566:
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
-X DELETE https://api.practitest.com/api/v2/projects/4566/requirements/73365/relationships/tests.json \
-d '{"data": [{ "id": TEST_ID, "type": "tests" },{ "id": ANOTHER_TEST_ID, "type": "tests" }]}'

This endpoint removes linked tests for a specific requirement

HTTP Request

DELETE https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/requirements/YOUR_REQUIREMENT_ID/relationships/tests.json

You can find at the right area an example of the JSON request and response

PAT Support

Supported - if the user has the permissions to edit Requirements

GET all issues linked to a specific requirement

This endpoint retrieves all issues linked to a specific requirement

HTTP Request

GET https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/requirements/YOUR_REQUIREMENT_ID/relationships/issues.json

PAT Support

Supported - if the user has the permissions to view Requirements

Replace linked issues for a specific requirement

# Some request examples:

# Replace tests linked to the requirement in project #4566:
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
-X PATCH https://api.practitest.com/api/v2/projects/4566/requirements/73365/relationships/issues.json \
-d '{"data": [{ "id": ISSUE_ID, "type": "issues" },{ "id": ANOTHER_ISSUE_ID, "type": "issues" }]}'

This endpoint replaces linked issues for a specific requirement

HTTP Request

PATCH https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/requirements/YOUR_REQUIREMENT_ID/relationships/issues.json

You can find at the right area an example of the JSON request and response

PAT Support

Supported - if the user has the permissions to edit Requirements

# Some request examples:

# Add tests linked to the requirement in project #4566:
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
-X POST https://api.practitest.com/api/v2/projects/4566/requirements/73365/relationships/issues.json \
-d '{"data": [{ "id": ISSUE_ID, "type": "issues" },{ "id": ANOTHER_ISSUE_ID, "type": "issues" }]}'

This endpoint links issues to a specific requirement

HTTP Request

POST http://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/requirements/YOUR_REQUIREMENT_ID/relationships/issues.json

PAT Support

Supported - if the user has the permissions to edit Requirements

Delete linked issues for a specific requirement

# Some request examples:

# Remove tests linked to the requirement in project #4566:
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
-X DELETE https://api.practitest.com/api/v2/projects/4566/requirements/73365/relationships/issues.json \
-d '{"data": [{ "id": ISSUE_ID, "type": "issues" },{ "id": ANOTHER_ISSUE_ID, "type": "issues" }]}'

This endpoint removes linked issues for a specific requirement

HTTP Request

DELETE https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/requirements/YOUR_REQUIREMENT_ID/relationships/issues.json

You can find at the right area an example of the JSON request and response

PAT Support

Supported - if the user has the permissions to edit Requirements

Tests

GET all tests in your project

# Some request examples:

# Get all tests of project #4566:
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
https://api.practitest.com/api/v2/projects/4566/tests.json

# Get all tests of project #4566, where filter-id is 323 and name is like login
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
https://api.practitest.com/api/v2/projects/4566/tests.json?filter-id=323&name_like=login

# Get all tests of project #4566, where autofilter filter-id is 323 and value is 1.5
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
https://api.practitest.com/api/v2/projects/4566/tests.json?filter-id=323&autofilter-value=1.5

# Get all tests with display ids 2,4 from project #4566
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
https://api.practitest.com/api/v2/projects/4566/tests.json?display-ids=2,4

# Get all tests with linked entities from project #4566
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
https://api.practitest.com/api/v2/projects/4566/tests.json?relationships=true

This command: https://api.practitest.com/api/v2/projects/4566/tests.json?api_token=xx&developer_email=admin%40pt.com&page[number]=1&page[size]=2", returns JSON structured like below:

{
  "data": [
    {
      "id": "1850360",
      "type": "tests",
      "attributes": {
        "project-id": 1230,
        "display-id": 205,
        "name": "first name",
        "description": "My description",
        "steps-count": 0,
        "status": "Ready",
        "run-status": "FAILED",
        "last-run": "2017-01-27T13:35:25+00:00",
        "author-id": 3596,
        "assigned-to-id": null,
        "assigned-to-type": null,
        "cloned-from-id": null,
        "planned-execution": null,
        "version": null,
        "priority": null,
        "duration-estimate": "00:00:00",
        "test-type":"ScriptedTest",
        "custom-fields": {
        "---f-8282": "High",
        },
        "folder-id": null,
        "created-at": "2017-01-27T12:19:46+00:00",
        "updated-at": "2017-01-27T12:24:07+00:00"
    }
  }
  ],
  "links": {
    "self": "https://api.practitest.com/api/v2/projects/1282/tests.json?api_token=YOUR_TOKEN
YOUR_TOKEN&developer_email=your_EMAIL&name_like=Issuer3&page%5Bnumber%5D=1&page%5Bsize%5D=6&set_filter_id=70859&set_ids=96530",
    "next": "https://api.practitest.com/api/v2/projects/1282/tests.json?api_token=YOUR_TOKEN&developer_email=your_EMAIL&name_like=Issuer3&page%5Bnumber%5D=2&page%5Bsize%5D=6&set_filter_id=70859&set_ids=96530",
    "last": "https://api.practitest.com/api/v2/projects/1282/tests.json?api_token=YOUR_TOKEN&developer_email=your_EMAIL&name_like=Issuer3&page%5Bnumber%5D=3&page%5Bsize%5D=6&set_filter_id=70859&set_ids=96530"
  },
  "meta": {
    "current-page": 1,
    "next-page": 2,
    "prev-page": null,
    "total-pages": 5,
    "total-count": 13
  }
}

This endpoint retrieves all tests.

HTTP Request

GET https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/tests.json

Query Parameters - pagination

Parameters* Description
filter-id the test’s filter id -> showing tests that are in this filter of the Test Library
autofilter-value if filter is an auto-filter, you can provide the 1st level filter value
sub-autofilter-value if filter is a 2-level auto-filter, and you provided the 1st level autofilter-value, you can provide the 2nd level filter value
filter-user-id if filter uses current_user criteria in it, you should provide which is the this user (list of user ids)
display-ids filter tests with display-ids (separated by commas)
name_exact filter by test name exact match; case sensitive!
name_like filter by test name: case insensitive, phrase can be inside the name
relationships shows entities linked to tests, should be equal to true

PAT Support

Supported - if the user has the permissions to view Tests

Create a test

# create a test
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
-X POST https://api.practitest.com/api/v2/projects/4566/tests.json \
-d '{"data": { "type": "tests", "attributes": {"name": "one", "author-id": 22, "priority": "highest", "custom-fields": { "---f-22": "Windows", "---f-24": ["ClientA", "ClientB"]}}  } }'

# create a test with 2 steps:
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
-X POST https://api.practitest.com/api/v2/projects/4566/tests.json \
-d '{"data": { "type": "tests", "attributes": {"name": "one", "author-id": 22, "priority": "highest"}, "steps": {"data": [{"name": "step one", "description": "Step 1 description", "expected-results": "result"}, {"name": "step two", "expected-results": "result2"}] }}}'

# create an automated type test with automated fields
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
-X POST https://api.practitest.com/api/v2/projects/4566/tests.json \
-d '{"data": { "type": "tests", "attributes": {"name": "one", "author-id": "2", "test-type": "ApiTest", "automated-fields": {"automated_test_design": "Test one design"}}  } }'

# create a BDD test with scenario field
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
-X POST https://api.practitest.com/api/v2/projects/4566/tests.json \
-d '{"data": { "type": "tests", "attributes": {"name": "BDD test", "author-id": "2", "test-type": "BDDTest", "scenario": "Scenario: BDD Test \r\n  Given I run the step\r\n  Then it ran" } } }'

# create a BDD test with scenario field with gherkin scenario outline (examples) content 
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
-X POST https://api.practitest.com/api/v2/projects/4566/tests.json \
-d '{"data": { "type": "tests", "attributes": {"name": "BDD with Scenario Outline", "author-id": "2", "test-type": "BDDTest", "scenario": "Scenario Outline: BDD with Scenario Outline \r\n  Given I run the step with <param1> and <param2>\r\n  Examples: \r\n  | param1 | param2 |\n\r  | val1a | val2a |\n\r  | val1b | val2b |" } } }'

This endpoint creates a test in your project.

HTTP Request

POST https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/tests.json

Parameters

Parameters Description required?
data/attributes/name name true
data/attributes/author-id user-id of author - users list true (unless using PAT)
data/attributes/description Test description false
data/attributes/test-type By default - ApiTest. Options: ScriptedTest, ApiTest, FireCracker, xBotTest, EggplantTest, BDDTest false
data/attributes/assigned-to-id user or group assigned-to id (not Display ID) - users list groups list false
data/attributes/assigned-to-type assigned-to type (user or group) false
data/attributes/planned-execution date field of planned-execution false
data/attributes/status string of status (not run status) false
data/attributes/version string of test version false
data/attributes/priority string of test priority false
data/attributes/custom-fields a hash of custom-fields with their value false
data/attributes/automated-fields a hash of Automation Info fields with their value. available fields: automated_test_design, script_repository, num_of_results, suite_path, client_type, script_path, results_path, script_name false
data/steps/data* an array of steps override the exit code false
data/attributes/tags an array of tags false

You can find at the right area (shell) an example of the request

PAT Support

Supported - if the user has the permissions to create Tests.

The “author-id” parameter is not required, and can only be used (and override PAT user) if it has “impersonation” enabled

Show a specific test

curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
https://api.practitest.com/api/v2/projects/4566/tests/45893.json

This command: https://api.practitest.com/api/v2/projects/4566/tests/45893.json?api_token=YOUR_TOKEN&developer_email=YOUR_EMAIL, returns JSON structured like below:

{
  "data": {
    "id": "1850344",
    "type": "tests",
    "attributes": {
      "project-id": 1230,
      "display-id": 205,
      "name": "first name",
      "description": "My description",
      "steps-count": 0,
      "status": "Ready",
      "run-status": "FAILED",
      "last-run": "2017-01-27T13:35:25+00:00",
      "author-id": 3596,
      "assigned-to-id": null,
      "assigned-to-type": null,
      "cloned-from-id": null,
      "planned-execution": null,
      "version": null,
      "priority": null,
      "duration-estimate": "00:00:00",
      "test-type":"ScriptedTest",
      "custom-fields": {
      "---f-8282": "High",
      },
      "folder-id": null,
      "created-at": "2017-01-27T12:19:46+00:00",
      "updated-at": "2017-01-27T12:24:07+00:00"
  }
}
}

This endpoint shows a specific test in your project.

HTTP Request

GET https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/tests/YOUR_TEST_ID.json

Here’s the example of the JSON request and response

Parameters* Description
relationships shows entities linked to tests, should be equal to true

PAT Support

Supported - if the user has the permissions to view Tests

Update a specific test

curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
-X PUT https://api.practitest.com/api/v2/projects/4566/tests/45893.json \
-d '{"data": { "type": "tests", "attributes": {"planned-execution":"2017-03-01T12:43:31Z", "priority": "highest", "custom-fields": { "---f-22": "Windows", "---f-24": ["ClientA", "ClientB"]}}  } }'

# some more examples:
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN  \
-X PUT https://api.practitest.com/api/v2/projects/4566/tests/98019.json \
-d '{"data": { "type": "tests", "attributes": {"planned-execution":"2017-03-05T12:43:31Z", "priority": "2-high", "version": "1.5", "custom-fields": { "---f-45510": "5381"}}  } }'

curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN  \
-X PUT https://api.practitest.com/api/v2/projects/4566/tests/98019.json \
-d '{"data": { "type": "tests", "attributes": {"version": "1.5", "custom-fields": { "---f-45390": "Chrome"}}  } }'

{
  "data": {
    "id": "45893",
    "type": "tests",
    "attributes": {
      ...
      "planned-execution": "2017-03-01T12:43:31Z",
      "priority": "highest",
      "custom-fields": {
        "---f-22":"my text one",
        "---f-24": ["ClientA", ["ClientB"]]
      },
      ...
      "created-at": "2015-11-17T09:29:22+00:00",
      "updated-at": "2015-11-17T09:29:22+00:00"
    }
  }
}

This endpoint updates a specific test.

HTTP Request

PUT https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/tests/TEST_ID.json

Parameters

Available parameters Description
data/attributes/name name
data/attributes/description Test description
data/attributes/test-type By default - ApiTest. Options: ScriptedTest, ApiTest, FireCracker, xBotTest, EggplantTest, BDDTest
data/attributes/assigned-to-id user or group assigned-to id (not Display ID) - users list groups list
data/attributes/assigned-to-type assigned-to type (user or group)
data/attributes/planned-execution date field of planned-execution
data/attributes/status string of status (not run status)
data/attributes/version string of test version
data/attributes/priority string of test priority
data/attributes/custom-fields a hash of custom-fields with their value
data/attributes/automated-fields a hash of Automation Info fields with their value. available fields: automated_test_design, script_repository, num_of_results, suite_path, client_type, script_path, results_path, script_name
data/attributes/tags an array of tags
data/attributes/updated-by-user-id ID (not Display ID) of the user who made a change - users list

You can find at the right area an example of the JSON request and response

PAT Support

Supported - if the user has the permissions to edit Tests.

History of a change by PAT user will be created automatically.

The “updated-by-user-id” parameter can only be used (and override PAT user) if it has “impersonation” enabled.

Delete a specific test

curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
-X DELETE https://api.practitest.com/api/v2/projects/4566/tests/45893.json

This endpoint deletes a specific test.

HTTP Request

DELETE https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/tests/YOUR_TEST_ID.json

You can find at the right area an example of the JSON request and response

PAT Support

Supported - if the user has the permissions to delete Tests.

Run statuses count

curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
https://api.practitest.com/api/v2/projects/4566/tests/run_statuses_count.json
{
  "data":{
    "type":"tests",
    "run-statuses-count":{
      "PASSED":0,
      "FAILED":0,
      "NOT COMPLETED":0,
      "NO RUN":2,
      "BLOCKED":0
    }
  }
}

This gives statistics data of run statuses of your project’s tests

HTTP Request

GET https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/tests/run_statuses_count.json

You can find at the right area an example of the JSON request and response

PAT Support

Supported - if the user has the permissions to view Tests

Test traceability

GET all requirements linked to a specific test

This endpoint retrieves all requirements linked to a specific test

HTTP Request

GET https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/tests/YOUR_TEST_ID/relationships/requirements.json

PAT Support

Supported - if the user has the permissions to view Tests

Replace linked requirements for a specific test

# Some request examples:

# Replace requirements linked to the test in project #4566:
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
-X PATCH https://api.practitest.com/api/v2/projects/4566/tests/73365/relationships/requirements.json \
-d '{"data": [{ "id": REQUIREMENT_ID, "type": "requirements" },{ "id": ANOTHER_REQUIREMENT_ID, "type": "requirements" }]}'

This endpoint replaces linked requirements for a specific test

HTTP Request

PATCH https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/tests/YOUR_TEST_ID/relationships/requirements.json

You can find at the right area an example of the JSON request and response

PAT Support

Supported - if the user has the permissions to edit Tests

# Some request examples:

# Add requirements linked to the test in project #4566:
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
-X POST https://api.practitest.com/api/v2/projects/4566/tests/73365/relationships/requirements.json \
-d '{"data": [{ "id": REQUIREMENT_ID, "type": "requirements" },{ "id": ANOTHER_REQUIREMENT_ID, "type": "requirements" }]}'

This endpoint links requirements to a specific test

HTTP Request

POST http://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/tests/YOUR_TEST_ID/relationships/requirements.json

You can find at the right area an example of the JSON request and response

PAT Support

Supported - if the user has the permissions to edit Tests

Delete linked requirements for a specific test

# Some request examples:

# Remove requirements linked to the test in project #4566:
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
-X DELETE https://api.practitest.com/api/v2/projects/4566/tests/73365/relationships/requirements.json \
-d '{"data": [{ "id": REQUIREMENT_ID, "type": "requirements" },{ "id": ANOTHER_REQUIREMENT_ID, "type": "requirements" }]}'

This endpoint removes linked requirements for a specific test

HTTP Request

DELETE https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/tests/YOUR_TEST_ID/relationships/requirements.json

You can find at the right area an example of the JSON request and response

PAT Support

Supported - if the user has the permissions to edit Tests

Steps

GET all steps in your project

# Some request examples:

# Get all steps of project #4566:
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
https://api.practitest.com/api/v2/projects/4566/steps.json

# Get all steps of project #4566, where name is like login
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
https://api.practitest.com/api/v2/projects/4566/steps.json?name_like=login

# Get all steps with test ids 23223,43121 from project #4566
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
https://api.practitest.com/api/v2/projects/4566/steps.json?test-ids=23223,43121

This command: https://api.practitest.com/api/v2/projects/4566/steps.json?test-ids=257245api_token=xx&developer_email=admin%40pt.com", returns JSON structured like below:

{
  "data": [
    {
      "id": "1443767",
      "type": "steps",
      "attributes": {
        "project-id": 914,
        "kind": "ManualStep",
        "test-id": 257245,
        "test-to-call-id": null,
        "name": "login",
        "description": "login to the first page",
        "expected-results": "you should be able to login",
        "position": 1,
        "created-at": "2015-01-29T20:17:54+00:00",
        "updated-at": "2015-01-29T20:17:54+00:00"
      }
    },
    {
      "id": "1443768",
      "type": "steps",
      "attributes": {
        "project-id": 914,
        "kind": "ManualStep",
        "test-id": 257245,
        "test-to-call-id": null,
        "name": "dashboard page",
        "description": "goto dashboard page, see graphs",
        "expected-results": "validate all graphs are equal",
        "position": 2,
        "created-at": "2015-01-29T20:17:54+00:00",
        "updated-at": "2015-01-29T20:17:54+00:00"
      }
    },
    {
      "id": "1443769",
      "type": "steps",
      "attributes": {
        "project-id": 914,
        "kind": "CallToTest",
        "test-id": 257245,
        "test-to-call-id": 97733,
        "name": "Call To Test #2: dashboard testing",
        "description": "",
        "expected-results": "",
        "position": 3,
        "created-at": "2015-01-29T20:17:55+00:00",
        "updated-at": "2015-01-29T20:17:55+00:00"
      }
    }
  ],
  "links": {},
  "meta": {
  "current-page": 1,
  "next-page": null,
  "prev-page": null,
  "total-pages": 1,
  "total-count": 3
  }
}

This endpoint retrieves all steps.

HTTP Request

GET https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/steps.json

Query Parameters - pagination

Parameters* Description
test-ids filter steps with test-ids (separated by commas)
name_exact filter by step name exact match; case sensitive!
name_like filter by step name: case insensitive, phrase can be inside the name

PAT Support

Supported - if the user has the permissions to view Tests

Create a step

# create a step
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
-X POST https://api.practitest.com/api/v2/projects/4566/steps.json \
-d '{"data": { "type": "steps", "attributes": {"test-id": 9510, "steps": [{"name": "Step 1 from API", "description":  "New Step description", "expected-results": "Step created"}] }  }}'

# create 3 steps:
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
-X POST https://api.practitest.com/api/v2/projects/4566/steps.json \
-d '{"data": { "type": "steps", "attributes":  {"test-id": 9510, "steps": [{"name": "Step 1", "description":  "New description 1", "expected-results": ""}, {"name": "Step 2", "description":  "New description 2", "expected-results": "WOW!"}, {"name": "Step 3", "description":  "New description 3", "expected-results": "my expected results"}] }  }}'

This endpoint creates steps in your project.

HTTP Request

POST https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/steps.json

Parameters

Parameters Description
data/attributes/test-id Test system-id
data/attributes/steps an array of steps

PAT Support

Supported - if the user has the permissions to edit Tests.

Show a specific step

curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
https://api.practitest.com/api/v2/projects/4566/steps/45893.json

This command: https://api.practitest.com/api/v2/projects/4566/steps/1443768.json?api_token=YOUR_TOKEN&developer_email=YOUR_EMAIL, returns JSON structured like below:

{
  "data": {
    "id": "1443768",
    "type": "steps",
    "attributes": {
      "project-id": 914,
      "kind": "ManualStep",
      "test-id": 257245,
      "test-to-call-id": null,
      "name": "dashboard page",
      "description": "goto dashboard page, see graphs",
      "expected-results": "validate all graphs are equal",
      "position": 2,
      "created-at": "2015-01-29T20:17:54+00:00",
      "updated-at": "2015-01-29T20:17:54+00:00"
    }
  }
}

This endpoint shows a specific step in your project.

HTTP Request

GET https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/steps/YOUR_STEP_ID.json

In the right area see the example of the JSON request and response

PAT Support

Supported - if the user has the permissions to view Tests

Update a specific step

curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
-X PUT https://api.practitest.com/api/v2/projects/4566/steps/45893.json
-d '{"data": { "type": "steps", "attributes": {"name": "Updated step name", "description": "a new description", "expected-results": "New expected results"}  }}'

{
  "data": {
    "id": "45893",
    "type": "steps",
    "attributes": {
      "project-id": 4566,
      "kind": "ManualStep",
      "test-id": 9510,
      "test-to-call-id": null,
      "name": "Updated step name",
      "description": "a new description",
      "expected-results": "New expected results",
      "position": 8,
      "created-at": "2021-05-19T15:08:20Z",
      "updated-at": "2021-05-27T15:08:47Z"
    }
  }
}

This endpoint updates a specific step.

HTTP Request

PUT https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/steps/STEP_ID.json

In the right area see the example of the JSON request and response

Parameters

Available parameters Description
data/attributes/name Step name
data/attributes/description Step description
data/attributes/expected-results Expected results of the step

You can find at the right area an example of the JSON request and response

PAT Support

Supported - if the user has the permissions to edit Tests

Delete a specific step

curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
-X DELETE https://api.practitest.com/api/v2/projects/4566/steps/45893.json

This endpoint deletes a specific step.

HTTP Request

DELETE https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/steps/YOUR_STEP_ID.json

You can find at the right area an example of the JSON request and response

PAT Support

Supported - if the user has the permissions to edit Tests

TestSets

GET all TestSets in your project

# Some request examples:

# Get all sets of project #4566:
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
https://api.practitest.com/api/v2/projects/4566/sets.json

# Get all sets of project #4566, where filter-id is 323 and name is like login
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
https://api.practitest.com/api/v2/projects/4566/sets.json?filter-id=323&name_like=login

# Get all sets of project #4566, where autofilter filter-id is 323 and value is 1.5
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
https://api.practitest.com/api/v2/projects/4566/sets.json?filter-id=323&autofilter-value=1.5

# Get all TestSets with display ids 2,4 from project #4566
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
https://api.practitest.com/api/v2/projects/4566/sets.json?display-ids=2,4

This command: https://api.practitest.com/api/v2/projects/4566/sets.json?api_token=xx&developer_email=admin%40pt.com&page[number]=1&page[size]=2", returns JSON structured like below:

{
  "data": [
    {
      "id": "1850360",
      "type": "sets",
      "attributes": {
        "project-id": 1230,
        "display-id": 205,
        "name": "first name",
        "description": "description",
        "instances-count": 0,
        "run-status": "FAILED",
        "last-run": "2017-01-27T13:35:25+00:00",
        "assigned-to-id": null,
        "assigned-to-type": null,
        "planned-execution": null,
        "version": null,
        "priority": null,
        "custom-fields": {
        "---f-8282": "High",
        },
        "folder-id": null,
        "created-at": "2017-01-27T12:19:46+00:00",
        "updated-at": "2017-01-27T12:24:07+00:00"
    }
  }
  ],
  "links": {
    "self": "https://api.practitest.com/api/v2/projects/1282/sets.json?api_token=YOUR_TOKEN
YOUR_TOKEN&developer_email=your_EMAIL&name_like=Issuer3&page%5Bnumber%5D=1&page%5Bsize%5D=6&set_filter_id=70859&set_ids=96530",
    "next": "https://api.practitest.com/api/v2/projects/1282/sets.json?api_token=YOUR_TOKEN&developer_email=your_EMAIL&name_like=Issuer3&page%5Bnumber%5D=2&page%5Bsize%5D=6&set_filter_id=70859&set_ids=96530",
    "last": "https://api.practitest.com/api/v2/projects/1282/sets.json?api_token=YOUR_TOKEN&developer_email=your_EMAIL&name_like=Issuer3&page%5Bnumber%5D=3&page%5Bsize%5D=6&set_filter_id=70859&set_ids=96530"
  },
  "meta": {
    "current-page": 1,
    "next-page": 2,
    "prev-page": null,
    "total-pages": 5,
    "total-count": 13
  }
}

This endpoint retrieves all TestSets.

HTTP Request

GET https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/sets.json

Query Parameters - pagination

Parameters* Description
filter-id the TestSet’s filter id -> showing TestSets that are in this filter
autofilter-value if filter is an auto-filter, you can provide the 1st level filter value
sub-autofilter-value if filter is a 2-level auto-filter, and you provided the 1st level autofilter-value, you can provide the 2nd level filter value
filter-user-id if filter uses current_user criteria in it, you should provide which is the this user (list of user ids)
display-ids filter TestSets with display-ids (separated by commas)
name_exact filter by TestSet name exact match; case sensitive!
name_like filter by TestSet name: case insensitive, phrase can be inside the name

PAT Support

Supported - if the user has the permissions to view Runs / TestSets

Create a TestSet

# create a Test Set
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
-X POST https://api.practitest.com/api/v2/projects/4566/sets.json \
-d '{"data": { "type": "sets", "attributes": {"name": "one", "description": "description", "priority": "highest", "custom-fields": { "---f-22": "Windows", "---f-24": ["ClientA", "ClientB"]}}  } }'

# create a Test Set with author
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
-X POST https://api.practitest.com/api/v2/projects/4566/sets.json \
-d '{"data": { "type": "sets", "attributes": {"name": "New TestSet with author", "description": "description", "author-id": 4370, "priority": "highest"}  } }'

# create a Test Set with 2 test-ids to become instances:
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
-X POST https://api.practitest.com/api/v2/projects/4566/sets.json \
-d '{"data": { "type": "sets", "attributes": {"name": "one", "description": "description", "priority": "highest"}, "instances": {"test-ids": [32222,53333]} }}'

This endpoint creates a TestSet in your project.

HTTP Request

POST https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/sets.json

Parameters

Parameters Description required?
data/attributes/name name true
data/attributes/assigned-to-id user or group assigned-to id (not Display ID) - users list groups list false
data/attributes/author-id author user id (not Display ID) - users list false
data/attributes/assigned-to-type assigned-to type (user or group) false
data/attributes/planned-execution date field of planned-execution false
data/attributes/status string of status (not run status) false
data/attributes/version string of TestSet version false
data/attributes/priority string of TestSet priority false
data/attributes/custom-fields a hash of custom-fields with their value false
data/instances/test-ids an array of test-ids to add as instances to the new TestSet false
data/attributes/tags an array of tags false

You can find at the right area (shell) an example of the request

PAT Support

Supported - if the user has the permissions to run Tests, view and edit Instances / TestSets

Show a specific TestSet

curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
https://api.practitest.com/api/v2/projects/4566/sets/45893.json

This command: https://api.practitest.com/api/v2/projects/4566/sets/45893.json?api_token=YOUR_TOKEN&developer_email=YOUR_EMAIL, returns JSON structured like below:

{
  "data": {
    "id": "1850344",
    "type": "sets",
    "attributes": {
      "project-id": 1230,
      "display-id": 205,
      "name": "first name",
      "description": "description",
      "instances-count": 0,
      "run-status": "FAILED",
      "last-run": "2017-01-27T13:35:25+00:00",
      "assigned-to-id": null,
      "assigned-to-type": null,
      "planned-execution": null,
      "version": null,
      "priority": null,
      "custom-fields": {
      "---f-8282": "High",
      },
      "folder-id": null,
      "created-at": "2017-01-27T12:19:46+00:00",
      "updated-at": "2017-01-27T12:24:07+00:00"
  }
}
}

This endpoint shows a specific TestSet in your project.

HTTP Request

GET https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/sets/YOUR_SET_ID.json

Here’s the example of the JSON request and response

PAT Support

Supported - if the user has the permissions to view Runs / TestSets

Update a specific TestSet

curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
-X PUT https://api.practitest.com/api/v2/projects/4566/sets/45893.json \
-d '{"data": { "type": "sets", "attributes": {"planned-execution":"2017-03-01T12:43:31Z", "description": "description", "priority": "highest", "custom-fields": { "---f-22": "Windows", "---f-24": ["ClientA", "ClientB"]}}  } }'

# some more examples:
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN  \
-X PUT https://api.practitest.com/api/v2/projects/4566/sets/98019.json \
-d '{"data": { "type": "sets", "attributes": {"planned-execution":"2017-03-05T12:43:31Z", "description": "description", "priority": "2-high", "version": "1.5", "custom-fields": { "---f-45510": "5381"}}  } }'

curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN  \
-X PUT https://api.practitest.com/api/v2/projects/4566/sets/98019.json \
-d '{"data": { "type": "sets", "attributes": {"version": "1.5", "description": "description", "custom-fields": { "---f-45390": "Chrome"}}  } }'

{
  "data": {
    "id": "45893",
    "type": "sets",
    "attributes": {
      ...
      "planned-execution": "2017-03-01T12:43:31Z",
      "priority": "highest",
      "description": "description",
      "custom-fields": {
        "---f-22":"my text one",
        "---f-24": ["ClientA", ["ClientB"]]
      },
      ...
      "created-at": "2015-11-17T09:29:22+00:00",
      "updated-at": "2015-11-17T09:29:22+00:00"
    }
  }
}

This endpoint updates a specific TestSet.

HTTP Request

PUT https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/sets/SET_ID.json

Parameters

Available parameters Description
data/attributes/name name
data/attributes/assigned-to-id user or group assigned-to id (not Display ID) - users list groups list
data/attributes/assigned-to-type assigned-to type (user or group)
data/attributes/planned-execution date field of planned-execution
data/attributes/version string of TestSet version
data/attributes/priority string of TestSet priority
data/attributes/custom-fields a hash of custom-fields with their value
data/attributes/tags an array of tags

You can find at the right area an example of the JSON request and response

PAT Support

Supported - if the user has the permissions to run Tests, view and edit Instances / TestSets

Delete a specific TestSet

curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
-X DELETE https://api.practitest.com/api/v2/projects/4566/sets/45893.json

This endpoint deletes a specific TestSet.

HTTP Request

DELETE https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/sets/YOUR_SET_ID.json

You can find at the right area an example of the JSON request and response

PAT Support

Supported - if the user has the permissions to delete Instances / TestSets (Runs - Admin)

Clone a TestSet

curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
-X POST https://api.practitest.com/api/v2/projects/4566/sets/45893/clone.json \
-d '{"data": { "type": "sets", "attributes": {"name": "my new cloned TestSet", "planned-execution":"2017-03-01T12:43:31Z", "priority": "highest", "custom-fields": { "---f-8282": "High", "---f-24": ["ClientA", "ClientB"]}}  } }'
{
  "data": {
    "id": "1850344",
    "type": "sets",
    "attributes": {
      "project-id": 1230,
      "display-id": 205,
      "name": "my new cloned testSet",
      "description": "description",
      "instances-count": 5,
      "run-status": "NO RUN",
      "last-run": null,
      "assigned-to-id": null,
      "assigned-to-type": null,
      "planned-execution": "2017-03-01T12:43:31Z",
      "version": null,
      "priority": "highest",
      "custom-fields": {
        "---f-8282": "High",
        "---f-24": ["ClientA", "ClientB"]
      },
      "folder-id": null,
      "created-at": "2017-01-27T12:19:46+00:00",
      "updated-at": "2017-01-27T12:24:07+00:00"
    }
  }
}

This clones a single TestSet, with new empty instances. Additional parameters can be applied if you need to change attributes

HTTP Request

POST https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/sets/SET_ID/clone.json

Parameters

Available parameters Description
data/attributes/name name
data/attributes/assigned-to-id user or group assigned-to id (not Display ID) - users list groups list
data/attributes/assigned-to-type assigned-to type (user or group)
data/attributes/planned-execution date field of planned-execution
data/attributes/version string of TestSet version
data/attributes/priority string of TestSet priority
data/attributes/custom-fields a hash of custom-fields with their value
data/attributes/tags an array of tags

You can find at the right area an example of the JSON request and response

PAT Support

Supported - if the user has the permissions to run Tests, view and edit Instances / TestSets

Instances

GET all instances in your project

# Some request examples:

# Get all instances of project #4566:
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
https://api.practitest.com/api/v2/projects/4566/instances.json

# Get all instances of project #4566, where TestSet filter-id is 323 and Instance name is like login
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
https://api.practitest.com/api/v2/projects/4566/instances.json?set-filter-id=323&name_like=login

# Get all instances of project #4566, of Test-ids 1111 where they belong to TestSets 32321 or 223254
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
https://api.practitest.com/api/v2/projects/4566/instances.json?test-ids=1111&set-ids=32321,223254

# Get all instances of project #4566, of Test display ids 1,2,3
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
https://api.practitest.com/api/v2/projects/4566/instances.json?test-display-ids=1,2,3

This command: https://api.practitest.com/api/v2/projects/4566/instances.json?api_token=xx&developer_email=admin%40pt.com&page[number]=1&page[size]=2", returns JSON structured like below:

{
  "data": [
    {
      "id": "1850360",
      "type": "instances",
      "attributes": {
        "name": "User login",
        "project-id": 1282,
        "set-id": 96530,
        "set-display-id": 117,
        "test-id": 369093,
        "test-display-id": 2372,
        "custom-fields": {
          "---f-2640": "my text one",
          "---f-2641": ["foo0"]
        },
        "display-id": "117:19",
        "tester-id": 4825,
        "priority": null,
        "last-run-duration": "00:00:00",
        "last-run": "2015-11-18T07:46:57+00:00",
        "run-status": "PASSED",
        "planned-execution": null,
        "version": null,
        "assigned-to-id": null,
        "assigned-to-type": null,
        "created-at": "2015-11-17T09:29:22+00:00",
        "updated-at": "2015-11-17T09:29:22+00:00"
      }
    },
    {
      "id": "1850361",
      "type": "instances",
      "attributes": {
        "name": "User delete",
        "project-id": 1282,
        "set-id": 96530,
        "set-display-id": 117,
        "test-id": 369094,
        "test-display-id": 2373,
        "custom-fields": {},
        "display-id": "117:20",
        "tester-id": 4825,
        "priority": null,
        "last-run-duration": "00:00:00",
        "last-run": "2015-11-19T04:42:30+00:00",
        "run-status": "PASSED",
        "planned-execution": null,
        "version": null,
        "assigned-to-id": null,
        "assigned-to-type": null,
        "created-at": "2015-11-17T09:29:22+00:00",
        "updated-at": "2015-11-17T09:29:22+00:00"
      }
    }
  ],
  "links": {
    "self": "https://api.practitest.com/api/v2/projects/1282/instances.json?api_token=b28a2be5e18491c7779e224ac60c4f815407d923&developer_email=dkd%40dkd.com&name_like=Issuer3&page%5Bnumber%5D=1&page%5Bsize%5D=6&set_filter_id=70859&set_ids=96530",
    "next": "https://api.practitest.com/api/v2/projects/1282/instances.json?api_token=b28a2be5e18491c7779e224ac60c4f815407d923&developer_email=dkd%40dkd.com&name_like=Issuer3&page%5Bnumber%5D=2&page%5Bsize%5D=6&set_filter_id=70859&set_ids=96530",
    "last": "https://api.practitest.com/api/v2/projects/1282/instances.json?api_token=b28a2be5e18491c7779e224ac60c4f815407d923&developer_email=dkd%40dkd.com&name_like=Issuer3&page%5Bnumber%5D=3&page%5Bsize%5D=6&set_filter_id=70859&set_ids=96530"
  },
  "meta": {
    "current-page": 1,
    "next-page": 2,
    "prev-page": null,
    "total-pages": 5,
    "total-count": 13
  }
}

This endpoint retrieves all instances.

HTTP Request

GET https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/instances.json

Query Parameters - pagination

Parameters* Description
set-filter-id the testSet’s filter id -> showing instances of TestSets which are in this filter
set-filter-user-id if filter uses current_user criteria in it, you should provide which is the this user (list of user ids)
test-ids filter instances that are related to a certain test_id (NOT display-id!)
set-ids filter by TestSets ids, separated by comma (system-id)
name_exact filter by instance name exact match; case sensitive!
name_like filter by instance name: case insensitive, phrase can be inside the name
display-id filter instances based on an instance display-id (can be used to convert display to system id)
test-display-ids filter instances based on a certain or multiple Test display-ids (comma separated)

PAT Support

Supported - if the user has the permissions to view runs / instances

Create an instance

curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
-X POST https://api.practitest.com/api/v2/projects/4566/instances.json \
-d '{"data": { "type": "instances", "attributes": {"test-id": 233, "set-id": 33, "priority": "highest", "custom-fields": { "---f-22": "Windows", "---f-24": ["ClientA", "ClientB"]}}  } }'

# example with creating multiple instances
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
-X POST https://api.practitest.com/api/v2/projects/4520/instances.json \
-d '{"data": [{ "type": "instances", "attributes": {"test-id": 72926, "set-id": 22140}}, { "type": "instances", "attributes": {"test-id": 72927, "set-id": 22140}}, { "type": "instances", "attributes": {"test-id": 72927, "set-id": 22141}}]}'

This endpoint creates an instance in your project.

HTTP Request

POST https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/instances.json

Parameters

Parameters Description required?
data/attributes/set-id TestSet id (not display id) true
data/attributes/test-id* Test id (not display id) true
data/attributes/planned-execution date field of planned-execution false
data/attributes/version string of instance version false
data/attributes/priority string of instance priority false
data/attributes/assigned-to-id user or group assigned-to id (not Display ID) - users list groups list false
data/attributes/assigned-to-type assigned-to type (user or group) false
data/attributes/custom-fields a hash of custom-fields with their value false

You can find at the right area (shell) an example of the request

PAT Support

Supported - if the user has the permissions to create instances

Show a specific instance

curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
https://api.practitest.com/api/v2/projects/4566/instances/45893.json

This command: https://api.practitest.com/api/v2/projects/4566/instances/45893.json?api_token=YOUR_TOKEN&developer_email=YOUR_EMAIL, returns JSON structured like below:

{
  "data": {
    "id": "1850344",
    "type": "instances",
    "attributes": {
      "name": "SmokeTest_ECR_Purchase&ReversalIssuer30",
      "project-id": 1282,
      "set-id": 96530,
      "set-display-id": 117,
      "test-id": 369077,
      "test-display-id": 2356,
      "custom-fields": {},
      "display-id": "117:3",
      "tester-id": 4825,
      "priority": null,
      "last-run-duration": "00:00:00",
      "last-run": "2015-11-18T04:57:21+00:00",
      "run-status": "PASSED",
      "planned-execution": null,
      "version": null,
      "assigned-to-id": null,
      "assigned-to-type": null,
      "created-at": "2015-11-17T09:29:22+00:00",
      "updated-at": "2015-11-17T09:29:22+00:00"
    }
  }
}

This endpoint shows a specific instance in your project.

HTTP Request

GET https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/instances/YOUR_INSTANCE_ID.json

Here’s the example of the JSON request and response

PAT Support

Supported - if the user has the permissions to view runs / instances

Update a specific instance

curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
-X PUT https://api.practitest.com/api/v2/projects/4566/instances/45893.json \
-d '{"data": { "type": "instances", "attributes": {"planned-execution":"2017-03-01T12:43:31Z", "priority": "highest", "custom-fields": { "---f-22": "Windows", "---f-24": ["ClientA", "ClientB"]}}  } }'

# some more examples:
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN  \
-X PUT https://api.practitest.com/api/v2/projects/4566/instances/98019.json \
-d '{"data": { "type": "instances", "attributes": {"planned-execution":"2017-03-05T12:43:31Z", "priority": "2-high", "version": "1.5", "custom-fields": { "---f-45510": "5381"}}  } }'

curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN  \
-X PUT https://api.practitest.com/api/v2/projects/4566/instances/98019.json \
-d '{"data": { "type": "instances", "attributes": {"version": "1.5", "custom-fields": { "---f-45390": "Chrome"}}  } }'

{
  "data": {
    "id": "45893",
    "type": "instances",
    "attributes": {
      ...
      "planned-execution": "2017-03-01T12:43:31Z",
      "priority": "highest",
      "custom-fields": {
        "---f-22":"my text one",
        "---f-24": ["ClientA", ["ClientB"]]
      },
      ...
      "created-at": "2015-11-17T09:29:22+00:00",
      "updated-at": "2015-11-17T09:29:22+00:00"
    }
  }
}

This endpoint updates a specific instance.

HTTP Request

PUT https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/instances/YOUR_INSTANCE_ID.json

Parameters

Available parameters Description
data/attributes/planned-execution date field of planned-execution
data/attributes/version string of instance version
data/attributes/priority string of instance priority
data/attributes/assigned-to-id user or group assigned-to id (not Display ID) - users list groups list
data/attributes/assigned-to-type assigned-to type (user or group)
data/attributes/custom-fields a hash of custom-fields with their value

You can find at the right area an example of the JSON request and response

PAT Support

Supported - if the user has the permissions to edit instances

Delete a specific instance

curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
-X DELETE https://api.practitest.com/api/v2/projects/4566/instances/45893.json

This endpoint deletes a specific instance.

HTTP Request

DELETE https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/instances/YOUR_INSTANCE_ID.json

You can find at the right area an example of the JSON request and response

PAT Support

Supported - if the user has the permissions to delete instances (Runs - Admin)

Runs

GET all runs in your project

# Some request examples:

# Get all runs of project #4566:

curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
https://api.practitest.com/api/v2/projects/4566/runs.json

# Get all runs of project #4566, of Test-ids 80895

curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
https://api.practitest.com/api/v2/projects/4566/runs.json?test-ids=80895

This command: https://api.practitest.com/api/v2/projects/4566/runs.json?api_token=xx&developer_email=admin%40pt.com&page[number]=1&page[size]=2", returns JSON structured like below:

{
   "data":[
      {
         "id":"49676",
         "type":"runs",
         "attributes":{
            "project-id":4566,
            "status":"NO RUN",
            "tester-id":5380,
            "instance-id":98016,
            "preconditions": null,
            "version": "2",
            "test-id":80893,
            "run-type":"ManualRun",
            "custom-fields":{
              "---f-47889": "Mac"
            },
            "automated-execution-output":null,
            "run-duration":"00:53:20",
            "created-at":"2017-03-07T11:10:42+02:00",
            "updated-at":"2017-03-07T12:04:44+02:00"
         }
      },
      {
         "id":"49663",
         "type":"runs",
         "attributes":{
            "project-id":4566,
            "status":"NOT COMPLETED",
            "tester-id":5380,
            "instance-id":98016,
            "preconditions": null,
            "version": "1.5",
            "test-id":80893,
            "run-type":"ManualRun",
            "custom-fields":{

            },
            "automated-execution-output":null,
            "run-duration":"00:00:00",
            "created-at":"2017-02-21T13:25:34+02:00",
            "updated-at":"2017-02-21T13:25:34+02:00"
         }
      }
   ],
   "links":{
      "self":"https://api.practitest.com/api/v2/projects/4566/runs.json?api_token=xx&developer_email=pt%40gmail.com&page%5Bnumber%5D=1&page%5Bsize%5D=2",
      "next":"https://api.practitest.com/api/v2/projects/4566/runs.json?api_token=xx&developer_email=pt%40gmail.com&page%5Bnumber%5D=2&page%5Bsize%5D=2",
      "last":"https://api.practitest.com/api/v2/projects/4566/runs.json?api_token=xx&developer_email=pt%40gmail.com&page%5Bnumber%5D=41&page%5Bsize%5D=2"
   },
   "meta":{
      "current-page":1,
      "next-page":2,
      "prev-page":null,
      "total-pages":41,
      "total-count":81
   }
}

This endpoint retrieves all runs.

HTTP Request

GET https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/runs.json

Query Parameters - pagination

Parameters* Description
test-ids filters runs that are related to a certain test_id/ids, separated by comma (NOT display-id!)
set-ids filter by TestSets ids, separated by comma (NOT display-id)
instance-ids filter by Instances ids, separated by comma (NOT display-id)
run-type: ‘AutomatedRun ManualRun’
set-filter-id the testSet’s filter id -> showing runs of TestSets which are in this filter
set-filter-user-id if filter uses current_user criteria in it, you should provide which is the this user (list of user ids)
updated-hours-ago showing runs that were updated # hours ago

PAT Support

Supported - if the user has the permissions to view runs

Create a run

# upload test results with a file attachment
curl -H "Content-Type:application/json" \
   -u test@pt.com:YOUR TOKEN \
   -X POST https://api.practitest.com/api/v2/projects/1/runs.json \
   -d '{"data": { "type": "instances", "attributes": {"instance-id": 3254471, "exit-code": 0 }, "files": {"data": [{"filename": "one.log", "content_encoded": "'"$( base64 /tmp/one.log)"'" }, {"filename": "two.log", "content_encoded": "'"$( base64 /tmp/two.log)"'" }]} }  }'

# upload test results with a file attachment to a specific step
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
-X POST https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/runs.json \
-d '{"data": {"type": "instances", "attributes": {"instance-id": 124356}, "steps": {"data": [{"name": "step one", "expected-results": "result", "status": "FAILED", "files": {"data":[{"filename": "log.html", "content_encoded": "'"$(base64 /tmp/log.html) "'" }] }}, {"name": "step two", "expected-results": "result2", "status": "PASSED"} ] }}}'


# upload test results with the automated-execution-output
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
-X POST https://api.practitest.com/api/v2/projects/4566/runs.json \
-d '{"data": { "type": "instances", "attributes": {"instance-id": 98142, "exit-code": 0, "automated-execution-output": "THIS IS MY OUTPUT" }}} '

# example with steps
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
-X POST https://api.practitest.com/api/v2/projects/4566/runs.json \
-d '{"data": {"type": "instances", "attributes": {"instance-id": 98142}, "steps": {"data": [{"name": "step one", "expected-results": "result", "status": "FAILED"}, {"name": "step two", "expected-results": "result2", "status": "PASSED"}] }}}'

# example with custom-fields
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN  \
-X POST https://api.practitest.com/api/v2/projects/4566/runs.json \
-d '{"data": { "type": "instances", "attributes": {"instance-id": 98142, "exit-code": 0, "custom-fields": { "---f-45293": "Win" }}}} '

# example with the double quotes and the backslash
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN  \
-X POST https://api.practitest.com/api/v2/projects/4566/runs.json \
-d "{\"data\": { \"type\": \"instances\", \"attributes\": {\"instance-id\": 13691064, \"exit-code\": 0 }, \"files\": {\"data\": [{\"filename\": \"one.log\", \"content_encoded\": \"$( base64 /tmp/one.log )\" }]} } }"

# example with updating multiple instances with results
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN  \
-X POST https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/runs.json \
-d '{"data": [{ "type": "instances", "attributes": {"instance-id": 105716, "exit-code": 0, "automated-execution-output": "THIS IS MY OUTPUT"}}, { "type": "instances", "attributes": {"instance-id": 105717, "exit-code": 0, "automated-execution-output": "THIS IS MY OUTPUT"}}]}'


# example for ManualTest run
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
-X POST https://api.practitest.com/api/v2/projects/4566/runs.json \
-d '{"data": {"type": "instances", "attributes": {"instance-id": 98142}, "run-type": "ManualRun", "tester-id": 333, "steps": {"data": [{"name": "step one", "expected-results": "result", "status": "FAILED"}, {"name": "step two", "expected-results": "result2", "status": "PASSED"}] }}}'


This endpoint upload new run results to your project.

HTTP Request

POST https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/runs.json

Parameters

Parameters Description required?
data/attributes/instance-id* Instance id (not display-id) true
data/attributes/exit-code 0 for passed, otherwise failed false
data/attributes/run-type AutomatedRun, ManualRun (default is AutomatedRun) false
data/attributes/run-date date field of run-date - ManualRun only false
data/attributes/tester-id tester user-id - used - ManualRun only true for ManualRun (unless using PAT)
data/attributes/run-duration (HH:MM:SS), to update the run duration of a specific instance false
data/attributes/automated-execution-output text output string that will be shown in ‘Execution output’ field (up to 255 characters) - AutomatedRun only false
data/attributes/version string of Run version false
data/attributes/custom-fields a hash of custom-fields with their value false
data/steps/data** an array of steps override the exit code false
data/files/data*** an array of files false
data/steps/data/files/data**** an array of files false

** Steps array includes steps json hash, with these attributes: name, description, expected-results, actual-results, status. Status can be one of the following: PASSED, FAILED, BLOCKED, NO RUN, N/A When using steps, the exit-code is ignored, and it calculates it according to the steps status.

*** Files would be as attachments in your automated test runs. It’s a json hash that has two attributes: filename, and content_encoded. We expect to get the file content encoded as BASE64. See code examples: shell with curl to your right, Ruby example here, Python version 2 example here, Python version 3 example here, Java example here, C sharp (.Net) example here.

**** This parameter allows to attach files to specific step/s.

PAT Support

Supported - if the user has the permissions to run tests

Step Runs

GET all step runs in your project

# Some request examples:

# Get all step runs of project #4566:
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
https://api.practitest.com/api/v2/projects/4566/step_runs.json

# Get all step runs of project #4566, where name is like login
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
https://api.practitest.com/api/v2/projects/4566/step_runs.json?name_like=login

# Get all step runs with run ids 23223,43121 from project #4566
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
https://api.practitest.com/api/v2/projects/4566/step_runs.json?run-ids=23223,43121

This command: https://api.practitest.com/api/v2/projects/4566/steps.json?test-ids=257245api_token=xx&developer_email=admin%40pt.com", returns JSON structured like below:

{
  "data": [
    {
      "id": "374393",
      "type": "step-runs",
      "attributes": {
        "project-id": 4849,
        "run-id": 66126,
        "name": "Login to the system",
        "description": "Open your browser, go to the site http://www.test-test.com and log into the system",
        "expected-results": "You are taken to the personal landing page",
        "actual-results": null,
        "status": "NO RUN",
        "position": 1,
        "created-at": "2020-08-18T15:58:06+03:00",
        "updated-at": "2020-08-18T15:58:06+03:00"
      }
    },
    {
    "id": "374394",
    "type": "step-runs",
    "attributes": {
      "project-id": 4849,
      "run-id": 66126,
      "name": "Go to the User Management Tab",
      "description": "In the upper right corner, press the Users Definition Icon to be taken to this area of the application",
      "expected-results": "Based on your permissions you are taken to the users tab and you can see all the users in the system",
      "actual-results": null,
      "status": "NO RUN",
      "position": 2,
      "created-at": "2020-08-18T15:58:06+03:00",
      "updated-at": "2020-08-18T  15:58:06+03:00"
      }
    }
  ],
  "links": {},
  "meta": {
  "current-page": 1,
  "next-page": null,
  "prev-page": null,
  "total-pages": 1,
  "total-count": 2
  }
}

This endpoint retrieves all step runs.

HTTP Request

GET [BASE_URL]/api/v2/projects/YOUR_PROJECT_ID/step_runs.json

Query Parameters - pagination

Parameters* Description
run-ids filter step runs with run-ids (separated by commas)
name_exact filter by step runs name exact match; case sensitive!
name_like filter by step runs name: case insensitive, phrase can be inside the name
status filter by step runs name by status; case sensitive!

PAT Support

Supported - if the user has the permissions to view Runs

Issues

GET all Issues in your project

# Some request examples:

# Get all issues of project #4566:
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
https://api.practitest.com/api/v2/projects/4566/issues.json

# Get all issues of project #4566, where filter-id is 323 and title is like login
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
https://api.practitest.com/api/v2/projects/4566/issues.json?filter-id=323&title_like=login

# Get all issues of project #4566, where autofilter filter-id is 323 and value is 1.5
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
https://api.practitest.com/api/v2/projects/4566/issues.json?filter-id=323&autofilter-value=1.5

# Get all issues with display ids 2,4 from project #4566
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
https://api.practitest.com/api/v2/projects/4566/issues.json?display-ids=2,4

# Get all issues with linked entities from project #4566
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
https://api.practitest.com/api/v2/projects/4566/issues.json?relationships=true

This command: https://api.practitest.com/api/v2/projects/4566/issues.json?api_token=xx&developer_email=admin%40pt.com&page[number]=1&page[size]=2", returns JSON structured like below:

{
  "data": [
    {
      "id": "1850360",
      "type": "issues",
      "attributes": {
        "project-id": 1230,
        "display-id": 205,
        "title": "first name",
        "instances-count": 0,
        "run-status": "FAILED",
        "last-run": "2017-01-27T13:35:25+00:00",
        "assigned-to-id": null,
        "assigned-to-type": null,
        "planned-execution": null,
        "version": null,
        "priority": null,
        "custom-fields": {
        "---f-8282": "High",
        },
        "folder-id": null,
        "created-at": "2017-01-27T12:19:46+00:00",
        "updated-at": "2017-01-27T12:24:07+00:00"
    }
  }
  ],
  "links": {
    "self": "https://api.practitest.com/api/v2/projects/1282/issues.json?api_token=YOUR_TOKEN
YOUR_TOKEN&developer_email=your_EMAIL&name_like=Issuer3&page%5Bnumber%5D=1&page%5Bsize%5D=6&set_filter_id=70859&set_ids=96530",
    "next": "https://api.practitest.com/api/v2/projects/1282/issues.json?api_token=YOUR_TOKEN&developer_email=your_EMAIL&title_like=Issuer3&page%5Bnumber%5D=2&page%5Bsize%5D=6&set_filter_id=70859&set_ids=96530",
    "last": "https://api.practitest.com/api/v2/projects/1282/issues.json?api_token=YOUR_TOKEN&developer_email=your_EMAIL&title_like=Issuer3&page%5Bnumber%5D=3&page%5Bsize%5D=6&set_filter_id=70859&set_ids=96530"
  },
  "meta": {
    "current-page": 1,
    "next-page": 2,
    "prev-page": null,
    "total-pages": 5,
    "total-count": 13
  }
}

This endpoint retrieves all Issues.

HTTP Request

GET https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/issues.json

Query Parameters - pagination

Parameters* Description
filter-id the Issues filter id -> showing Issues that are in this filter
autofilter-value if filter is an auto-filter, you can provide the 1st level filter value
sub-autofilter-value if filter is a 2-level auto-filter, and you provided the 1st level autofilter-value, you can provide the 2nd level filter value
filter-user-id if filter uses current_user criteria in it, you should provide which is the this user (list of user ids)
display-ids filter Issues with display-ids (separated by commas)
title_exact filter by Issue name exact match; case sensitive!
title_like filter by Issue name: case insensitive, phrase can be inside the name
relationships shows entities linked to issues, should be equal to true

PAT Support

Supported - if the user has the permissions to view Issues

Create an Issue

# create an issue
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
-X POST https://api.practitest.com/api/v2/projects/4566/issues.json \
-d '{"data": { "type": "issues", "attributes": {"title": "one", "author-id": 4370, "priority": "highest", "custom-fields": { "---f-22": "Windows", "---f-24": ["ClientA", "ClientB"]}}  } }'

# create an issue with description and issue type:
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
-X POST https://api.practitest.com/api/v2/projects/4566/issues.json \
-d '{"data": { "type": "issues", "attributes": {"title": "TEST Issue", "description": "description", "author-id": 5863, "priority": "2-high", "issue-type": "task"}  } }'

This endpoint creates an Issue in your project.

HTTP Request

POST https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/issues.json

Parameters Description required?
data/attributes/title name true
data/attributes/description description false
data/attributes/author-id user-id of author true (unless using PAT)
data/attributes/assigned-to-id user or group assigned-to id (not Display ID) - users list groups list false
data/attributes/assigned-to-type assigned-to type (user or group) false
data/attributes/version string of the issue’s version false
data/attributes/priority string of the issue’s priority false
data/attributes/custom-fields a hash of custom-fields with their value false
data/attributes/issue-type issue type false
data/attributes/tags an array of tags false

You can find at the right area (shell) an example of the request

PAT Support

Supported - if the user has the permissions to create an Issue

Show a specific Issue

curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
https://api.practitest.com/api/v2/projects/4566/issues/45893.json

This command: https://api.practitest.com/api/v2/projects/4566/issues/45893.json?api_token=YOUR_TOKEN&developer_email=YOUR_EMAIL, returns JSON structured like below:

{
  "data": {
    "id": "1850344",
    "type": "issues",
    "attributes": {
      "project-id": 1230,
      "display-id": 205,
      "title": "first name",
      "instances-count": 0,
      "run-status": "FAILED",
      "last-run": "2017-01-27T13:35:25+00:00",
      "assigned-to-id": null,
      "assigned-to-type": null,
      "planned-execution": null,
      "version": null,
      "priority": null,
      "custom-fields": {
      "---f-8282": "High",
      },
      "folder-id": null,
      "created-at": "2017-01-27T12:19:46+00:00",
      "updated-at": "2017-01-27T12:24:07+00:00"
  }
}
}

This endpoint shows a specific Issue in your project.

HTTP Request

GET https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/issues/YOUR_ISSUE_ID.json

Here’s the example of the JSON request and response

Parameters* Description
relationships shows entities linked to issues, should be equal to true

PAT Support

Supported - if the user has the permissions to view Issues

Update a specific Issue

curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
-X PUT https://api.practitest.com/api/v2/projects/4566/issues/45893.json \
-d '{"data": { "type": "issues", "attributes": {"priority": "highest", "custom-fields": { "---f-22": "Windows", "---f-24": ["ClientA", "ClientB"]}}  } }'

# some more examples:
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN  \
-X PUT https://api.practitest.com/api/v2/projects/4566/issues/98019.json \
-d '{"data": { "type": "issues", "attributes": {"priority": "2-high", "version": "1.5", "issue-type": "task" }  } }'
{
  "data": {
    "id": "45893",
    "type": "issues",
    "attributes": {
      ...
      "priority": "highest",
      "custom-fields": {
        "---f-22":"my text one",
        "---f-24": ["ClientA", ["ClientB"]]
      },
      ...
      "created-at": "2015-11-17T09:29:22+00:00",
      "updated-at": "2015-11-17T09:29:22+00:00"
    }
  }
}

This endpoint updates a specific Issue.

HTTP Request

PUT https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/issues/ISSUE_ID.json

Parameters

Available parameters Description
data/attributes/title name
data/attributes/description description
data/attributes/assigned-to-id user or group assigned-to id (not Display ID) - users list groups list
data/attributes/assigned-to-type assigned-to type (user or group)
data/attributes/version string of the issue’s version
data/attributes/priority string of the issue’s priority
data/attributes/custom-fields a hash of custom-fields with their value
data/attributes/issue-type issue type
data/attributes/tags an array of tags
data/attributes/updated-by-user-id ID (not Display ID) of the user who made a change - users list

You can find at the right area an example of the JSON request and response

PAT Support

Supported - if the user has the permissions to edit an Issue

History of a change by PAT user will be created automatically.

The “updated-by-user-id” parameter can only be used (and override PAT user) if it has “impersonation” enabled.

Update an Issue Status

curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
-X PUT https://api.practitest.com/api/v2/projects/PROJECT_ID/issues/ISSUE_ID/update_status.json \
-d '{"data": { "type": "issues", "attributes": {"status-name": "fixed", "user-id": 6519}}}'
{
  "data": {
    "id": "154397",
    "type": "issues",
    "attributes": {
      "project-id": 4803,
      "display-id": 35,
      "title": "Picture test",
      "issue-type": "defect",
      "description": "new desc",
      "status-name": "fixed",
      "status-resolution": null,
      "author-id": 5380,
      "assigned-to-id": 6519,
      "version": null,
      "priority": "2-high",
      "closed-at": null,
      "closed-by-id": null,
      "cloned-from-id": null,
      "external-id": null,
      "custom-fields": {
        "---f-47543": "bla"
      },
      "tags": [],
      "created-at": "2019-04-16T13:27:07+03:00",
      "updated-at": "2019-04-22T17:53:04+03:00"
    }
  }
}

This endpoint updates an Issue Status.

HTTP Request

PUT https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/issues/ISSUE_ID/update_status.json

Parameters

Parameters Description Required?
data/attributes/status-name issue transition status from the Workflow true
data/attributes/user-id* user id (not Display ID) - users list true (unless using PAT)

You can find at the right area an example of the JSON request and response

PAT Support

Supported - if the user has the permissions to update Issue Status

The “user-id” parameter can only be used (and override PAT user) if it has “impersonation” enabled.

Delete a specific Issue

curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
-X DELETE https://api.practitest.com/api/v2/projects/4566/issues/45893.json

This endpoint deletes a specific Issue.

HTTP Request

DELETE https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/issues/YOUR_ISSUE_ID.json

You can find at the right area an example of the JSON request and response

PAT Support

Supported - if the user has the permissions to delete Issues

Issue traceability

GET all requirements linked to a specific issue

This endpoint retrieves all requirements linked to a specific issue

HTTP Request

GET https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/issues/YOUR_ISSUE_ID/relationships/requirements.json

PAT Support

Supported - if the user has the permissions to view Issues

Replace linked requirements for a specific issue

# Request example:

# Replace requirements linked to the issue in project #4566:
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
-X PATCH https://api.practitest.com/api/v2/projects/4566/issues/73365/relationships/requirements.json \
-d '{"data": [{ "id": REQUIREMENT_ID, "type": "requirements" },{ "id": ANOTHER_REQUIREMENT_ID, "type": "requirements" }]}'

This endpoint replaces linked requirements for a specific issue

HTTP Request

PATCH https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/issues/YOUR_ISSUE_ID/relationships/requirements.json

You can find at the right area an example of the JSON request and response

PAT Support

Supported - if the user has the permissions to edit Issues

# Request example:

# Add requirements linked to the issue in project #4566:
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
-X POST https://api.practitest.com/api/v2/projects/4566/issues/73365/relationships/requirements.json \
-d '{"data": [{ "id": REQUIREMENT_ID, "type": "requirements" },{ "id": ANOTHER_REQUIREMENT_ID, "type": "requirements" }]}'

This endpoint links requirements to a specific issue

HTTP Request

POST http://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/issues/YOUR_ISSUE_ID/relationships/requirements.json

You can find at the right area an example of the JSON request and response

PAT Support

Supported - if the user has the permissions to edit Issues

Delete linked requirements for a specific issue

# Request example:

# Remove requirements linked to the issue in project #4566:
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
-X DELETE https://api.practitest.com/api/v2/projects/4566/issues/73365/relationships/requirements.json \
-d '{"data": [{ "id": REQUIREMENT_ID, "type": "requirements" },{ "id": ANOTHER_REQUIREMENT_ID, "type": "requirements" }]}'

This endpoint removes linked requirements for a specific issue

HTTP Request

DELETE https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/issues/YOUR_ISSUE_ID/relationships/requirements.json

You can find at the right area an example of the JSON request and response

PAT Support

Supported - if the user has the permissions to edit Issues

GET all issues linked to a specific issue

This endpoint retrieves all issues linked to a specific issue

HTTP Request

GET https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/issues/YOUR_ISSUE_ID/relationships/issues.json

PAT Support

Supported - if the user has the permissions to view Issues

Replace linked issues for a specific issue

# Request example:

# Replace issues linked to the issue in project #4566:
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
-X PATCH https://api.practitest.com/api/v2/projects/4566/issues/73365/relationships/issues.json \
-d '{"data": [{ "id": ISSUE_ID, "type": "issues" },{ "id": ANOTHER_ISSUE_ID, "type": "issues" }]}'

This endpoint replaces linked issues for a specific issue

HTTP Request

PATCH https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/issues/YOUR_ISSUE_ID/relationships/issues.json

PAT Support

Supported - if the user has the permissions to edit Issues

# Request example:

# Add issues linked to the issue in project #4566:
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
-X POST https://api.practitest.com/api/v2/projects/4566/issues/73365/relationships/issues.json \
-d '{"data": [{ "id": ISSUE_ID, "type": "issues" },{ "id": ANOTHER_ISSUE_ID, "type": "issues" }]}'

This endpoint links issues to a specific issue

HTTP Request

POST http://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/issues/YOUR_ISSUE_ID/relationships/issues.json

You can find at the right area an example of the JSON request and response

PAT Support

Supported - if the user has the permissions to edit Issues

Delete linked issues for a specific issue

# Request example:

# Remove issues linked to the issue in project #4566:
curl -H "Content-Type:application/json" \
-u YOUR_EMAIL:YOUR_TOKEN \
-X DELETE https://api.practitest.com/api/v2/projects/4566/issues/73365/relationships/issues.json \
-d '{"data": [{ "id": ISSUE_ID, "type": "issues" },{ "id": ANOTHER_ISSUE_ID, "type": "issues" }]}'

This endpoint removes linked issues for a specific issue

HTTP Request

DELETE https://api.practitest.com/api/v2/projects/YOUR_PROJECT_ID/issues/YOUR_ISSUE_ID/relationships/issues.json

You can find at the right area an example of the JSON request and response

PAT Support

Supported - if the user has the permissions to edit Issues

Errors

The API uses the following error codes:

Error Code Meaning
400 Bad Request – General request error
401 Unauthorized – Your API key is wrong
403 Forbidden – Your API token is not authorized for this operation
404 Not Found – The specified resource could not be found - please check your project_id
405 Method Not Allowed – You tried to access a resource with an invalid method
406 Not Acceptable – You requested a format that isn’t json
422 Unprocessable Entity - Your parameter values are wrong or missing.
429 Too Many Requests – You’re requesting too many resources! Slow down!
500 Internal Server Error – General server error - there was a problem with the request.
503 Service Unavailable – We’re temporarially offline for maintenance. Please try again later.