Zephyr REST API
About API
Zephyr Enterprise exposes its data via a REST API. You can use the API to:
Integrate Zephyr with other applications.
Get information about users, projects, releases, test case repositories and the underlying folders, test cases, custom fields, execution cycles.
Create new test case folders, test cases, requirements, execution cycles, execution phases.
Add/modify/delete attachments and phases of existing execution cycles.
Assign test execution schedules.
Update test cases and test case execution status.
Create an execution cycle and update the status of a test case execution run.
Run quick search and Advanced Search (use ZQL).
And more.
Reference
An API reference in the API Blueprint format is available here:
Base URL
The base URL for API calls is:
http(s)://SERVER[:PORT]/flex/services/rest/latest
or in case of Zephyr Enterprise Cloud instances:
https://YOUR_SUBDOMAIN.yourzephyr.com/flex/services/rest/latest
JSON
The API uses JSON as the data format for most requests and responses. POST and PUT request containing a JSON request body must include the Content-Type header:
Content-Type: application/json
Authentication
Most API operations require authentication. Zephyr Enterprise API supports the following methods of authenticating requests:
API tokens (supported since v. 6.6)
Basic authentication
Cookie authentication
Important
If your Zephyr Enterprise instance uses single sign-on, you must use API tokens. If Zephyr is configured with internal authentication, you can use any of the API authentication methods.
API tokens (v. 6.6 and later)
API tokens allow a client application to impersonate a user without providing the user's actual password. To learn how to create an API token, see Create and Manage API Tokens in Zephyr.
The API token must be sent in the Authorization request header as follows:
Authorization: Bearer YOUR_API_TOKEN
If you use cURL to make requests, you can send this header like this:
curl -H "Authorization: Bearer YOUR_API_TOKEN" ...
Basic authentication
The API supports Basic authentication which uses your Zephyr Enterprise username and password. Send the username and password as a Base64-encoded string in the Authorization header:
Authorization: Basic base64(username + ':' + password)
If you use cURL to send requests, use the -u flag to specify your username and password:
curl -u "username:password" http://...
Note
Basic authentication requires that the username and password consist of ASCII characters. If they contain non-ASCII characters, use an API token instead.
Cookie authentication
This method uses HTTP cookies to authenticate requests and maintain session information.
The first thing you need to do is to get a cookie. To do that, send a GET request to
http(s)://SERVER[:PORT]/flex/services/rest/latest/manifest
with a Basic authentication header containing your Zephyr username and password.
If the username and password are valid, you will get a 200 OK response with the Set-Cookie header containing a cookie named token:
Set-Cookie: token=793395c0-7c34-44a2-b219-abc80121d686; Max-Age=5400; Expires=Thu, 06-Aug-2020 12:35:27 GMT; Path=/flex; Secure; HttpOnly
You need to send this cookie in the Cookie header in subsequent requests:
Cookie: token=793395c0-7c34-44a2-b219-abc80121d686
Cookies expire after 90 minutes, after which you will get a 401 response from the API. At this point, you will need to get a new cookie for use in subsequent requests.
Use cases
Manage Parser Templates (used to parse XML reports created by test automation tools like JUnit)
Got questions?
Ask your Zephyr API questions in our Community, or contact Support for assistance.