Zephyr Squad Server REST API

Applies to Zephyr Squad Server 9.0.1 and 4.8, last modified on August 12, 2022

Zephyr Squad Server exposes its data via a built-in REST API which lets you access the data programmatically and build your own integrations. You can use the API to:

  • Get information about projects, releases, tests, and execution cycles.

  • Create new tests and test execution cycles.

  • Update tests and test execution status.

  • Add attachments to existing execution cycles.

  • And more.

For example, you can build an integration that would create a test in a separate tool or system and add it to Zephyr Squad, or create a test execution cycle and update the status of a test execution run after it has been executed in an automation tool.

Note: The API is available out of the box since v. 5.6.0 and 4.5.0. In earlier versions of Zephyr Squad Server, access to the API was provided by an additional plugin, ZAPI, which has since been retired. Customers using those earlier versions need to upgrade Zephyr Squad Server to continue using the API.

Base URL

The base URL for API calls is:

{JIRA-BASE-URL}/rest/zapi/latest
   or
{JIRA-BASE-URL}/rest/zapi/1.0

latest is an alias for 1.0, so these URLs are equivalent to each other.

{JIRA-BASE-URL} is the base URL of your Jira Server. Note that this URL may include additional components (also called context path) after the host name. This depends on the settings of your Jira instance. For example:

Jira URL Context path Zephyr Squad Server API base URL
http://198.51.100.0:9800 {empty} http://198.51.100.0:9800/rest/zapi/latest
http://198.51.100.0:9800 /jira http://198.51.100.0:9800/jira/rest/zapi/latest

JSON format

The API uses JSON as the data format for most requests and responses. POST and PUT requests containing a JSON request body must include the Content-Type header:

Content-Type: application/json

Authentication

All requests to the Zephyr Squad API must be authenticated. The API supports the same authentication methods as Jira Server itself:

You must use one of these methods in your API requests.

Also, note that the authenticated user must have the appropriate permissions to perform the desired operations.

Jira Server v. 8.14 and later support personal access tokens that allow client applications to impersonate a user without providing the user’s actual password. The token must be sent in the Authorization request header as follows:

Raw HTTP request

Authorization: Bearer YOUR_TOKEN

cURL

curl -H "Authorization: Bearer YOUR_TOKEN" ...

The API supports Basic authentication using a Jira Server username and password. Send the username and password as a Base64-encoded string in the Authorization header:

Raw HTTP request

Authorization: Basic base64(username + ':' + password)

# Example for username=myuser, password=p@55w0rd
Authorization: Basic bXl1c2VyOnBANTV3MHJk

cURL

curl -u "username:password" ...

For details, see Basic authentication in the Jira Server documentation.

This method uses HTTP cookies to authenticate requests and maintain session information.

The first thing you need to do is to get a session cookie. To do this, send a POST request to Jira Server’s /rest/auth/1/session endpoint:

Raw HTTP request

POST JIRA_BASE_URL/rest/auth/1/session
Content-Type: application/json

{ "username": "myuser", "password": "p@55w0rd" }

cURL (Windows)

curl -X POST JIRA_BASE_URL/rest/auth/1/session -H "Content-Type: application/json" -d "{ \"username\": \"myuser\", \"password\": \"p@55w0rd\" }

cURL (Bash)

curl -X POST JIRA_BASE_URL/rest/auth/1/session \
     -H 'Content-Type: application/json' \
     -d '{ "username": "myuser", "password": "p@55w0rd" }'

If the username and password are valid, you will get a 200 OK response with the Set-Cookie header containing a cookie named JSESSIONID:

Set-Cookie: JSESSIONID=6E3487971234567896704A9EB4AE501F; Path=/; HttpOnly

You need to send this cookie in the Cookie header in subsequent requests. For example:

Raw HTTP request

Cookie: JSESSIONID=6E3487971234567896704A9EB4AE501F

cURL

curl -b "JSESSIONID=6E3487971234567896704A9EB4AE501F;" ...

For details, see Cookie-based authentication in the Jira Server documentation.

See OAuth in the Jira Server documentation to learn how to authenticate API calls using OAuth.

Reference

The complete API reference is available at:

https://zephyrsquadserver.docs.apiary.io

The reference also contains code examples for cURL, Node.js, Python, C#, Java, and many other languages.

How to

Got questions?

Visit the Zephyr Squad Community to ask questions or search for existing solutions.

See Also

Terms and Concepts

Highlight search results