Xray uses Jira issues for implementing Test, Pre-Condition, Test Set, Test Execution, and Test Plan entities. Therefore, these entities may be created or updated using Jira's native REST API, taking into consideration Xray's custom fields.

The Xray REST API provides additional endpoints specifically made for dealing with test entities/fields and importing execution results from automated processes.


The authentication is based on Jira's REST API authentication, so you can use  HTTP basic authentication using some user credentials. 

example of a API request with "curl" using basic authentication
curl -H "Accept: application/json" -u jira_username:jira_password https://jiraserver.example.com/rest/raven/1.0/api/test/CALC-1880/step

Jira 8.14 introduced the concept of Personal Access Tokens, which Xray takes advantage of. These tokens can be created in the user's profile section in Jira and have an expiration date; they can also be revoked at any moment (more information here).

To use them in Jira's and in Xray REST API calls, we need to use the HTTP header "Authorization" with the "Bearer <token>" value.

example of a API request with "curl" using Personal Access Tokens
curl -H "Accept: application/json" -H "Authorization: Bearer MDkzNjIyMTEwNjQzOqb+ApTGm3af+z3eGdcyDm7xHv6R" https://jiraserver.example.com/rest/raven/1.0/api/test/CALC-1880/step

It is also possible to use OAuth (see more information here).

Version and URI

The Xray REST API has 2 versions: v1.0 and v2.0. New versions of the API are created whenever there are breaking changes that can have a big impact on current integrations.

The URIs for resources have the following structure:


For example, http://yourserver/rest/raven/2.0/api/test/TEST-123/step

Note that the latest version of the Xray REST API is version 2.0. All endpoints from version 1.0 are available in version 2.0 unless they have been deprecated and removed intentionally.

You can also use "<latest>" as the API version. This will default to the latest version that is v2.0.

Check out the documentation for each version:

There's a GitHub repository with many source code snippets, showcasing usage of the API with examples implemented in different languages (e.g., JavaScript, Java, Python).

Besides, there is another one with some Postman collections that can exemplify how to invoke these APIs, in this case using the Postman tool.

These repositories are maintained by Xray and the community; they may not be fully up-to-date but are for sure a great quick starter.

Feel free to check them out and if you have suggestions or find any problem, please raise an issue on the respective GitHub project!

  • No labels