About API

Zephyr Enterprise exposes its data via a REST API. You can use the API to:

• Import data from other tools to Zephyr.
• 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:

https://zephyrenterprisev3.docs.apiary.io

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

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

• Migrate Data to Zephyr Enterprise
• 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.