> For the complete documentation index, see [llms.txt](https://docs.qyrus.com/api-testing/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.qyrus.com/api-testing/project-setup/pre-requisite-api.md).

# Pre-requisite-API

Pre-request APIs run before a dependent API test. They can perform setup work—such as authentication or test-data creation—and extract values from their responses into reusable variables.

When a test references an extracted variable, Qyrus runs the associated pre-request API and substitutes the response value into the test.

> **Data use notice:** Do not enter production or sensitive data. Use only non-confidential, synthetic, or anonymized data.

## Table of Contents

* [Open Pre-request Variables](#open-pre-request-variables)
* [Add a pre-request API](#add-a-pre-request-api)
* [Configure the request](#configure-the-request)
* [Create variables with the Data Handler](#create-variables-with-the-data-handler)
  * [Data Handler types](#data-handler-types)
* [Use the Path Extractor tool](#use-the-path-extractor-tool)
* [Use a pre-request variable](#use-a-pre-request-variable)
* [Save, send, edit, clone, or delete an API](#save-send-edit-clone-or-delete-an-api)
* [Export a pre-request API to another workspace](#export-a-pre-request-api-to-another-workspace)
* [Review execution results](#review-execution-results)

## Open Pre-request Variables

1. Open an API Testing project.
2. Open **Setup** in the top navigation bar, or expand **Setup** in the Home sidebar.
3. Select **Pre-Request Variables**.

The left panel lists configured pre-request APIs. Use **Search APIs** to find an API, select an entry to edit it, or select **New API** to add one.

## Add a pre-request API

Select **New API**, then choose one of the available sources:

* **Test Suites**: Select one or more APIs from an existing test suite.
* **Import URL**: Import an API definition from a supported URL.
* **Create manually**: Define a new API request directly in the editor.
* **Upload file**: Import APIs from a supported local definition or collection file.
* **From Playground**: Reuse an API created in API Playground.

When selecting from **Test Suites**, choose a suite, select the required APIs, and then select **Continue**.

![Add APIs dialog](https://2173886669-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FrWgLy70uByJZz2Zz3InN%2Fuploads%2Fgit-blob-d3acefa7e314589cc53c8c9886d8359abf3c80aa%2FAdd-Pre-Request-APIs.png?alt=media)

## Configure the request

The pre-request API editor contains the following tabs:

* **Details**: Configure the API type, HTTP method, URL, protocol, address, port, context path, parameters, and headers.
* **Auth**: Configure the authentication method and credentials required by the API.
* **Body**: Enter the request payload for methods that support a body.
* **Data Handler**: Extract response values into reusable variables.
* **Settings**: Configure request options such as the client certificate, URL encoding, and request timeout where available.

In **Details**, choose REST or another supported API type, select the HTTP method, and enter the request URL. The expanded URL section displays its protocol, address, port, and context path components.

Use **Params** to add path or query parameters and **Headers** to add request headers. The plus icon adds a row, the delete icon removes it, and the drag handle changes row order.

![Pre-request API editor](https://2173886669-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FrWgLy70uByJZz2Zz3InN%2Fuploads%2Fgit-blob-71f9b1bd33d0e7336b00cda176a0cfb90dbf94d9%2FPre-Request-API-Editor.png?alt=media)

## Create variables with the Data Handler

The **Data Handler** converts response values into variables that other API tests can reference.

1. Open the pre-request API and select **Data Handler**.
2. Enter a unique **Variable Name**.
3. Enter the response **Path Reference**.
4. Select the Data Handler **Type** that matches the value to extract.
5. Use the plus icon to add another extractor or the delete icon to remove one.
6. Select **Save**.

![Pre-request API Data Handler](https://2173886669-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FrWgLy70uByJZz2Zz3InN%2Fuploads%2Fgit-blob-edf19fdbbab475b4811278ed24a32efeca91c789%2FPre-Request-Data-Handler.png?alt=media)

### Data Handler types

The Data Handler supports five extraction types:

| Type           | Use                                                          | Path Reference                                                                                      |
| -------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- |
| **TEXT**       | Capture a value from a plain-text response.                  | Enter the text reference required for the response value.                                           |
| **JSONPATH**   | Extract a value from a JSON response.                        | Enter a JSONPath expression, such as `$.id` or `$.customer.name`.                                   |
| **XPATH**      | Extract a value from an XML or SOAP response.                | Enter an XPath expression, such as `//customer/id`.                                                 |
| **HEADER**     | Extract a value from an HTTP response header.                | Enter the response-header name, such as `Authorization` or `Content-Type`.                          |
| **JAVASCRIPT** | Derive or transform a value with supported JavaScript logic. | Define the required `executeJs(response, headers)` function and add the extraction logic inside it. |

![The five Pre-request Data Handler types](https://2173886669-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FrWgLy70uByJZz2Zz3InN%2Fuploads%2Fgit-blob-c852335b758e97830f774d258b4319ab274a9f8a%2FPre-Request-Data-Handler-Types.png?alt=media)

Choose the type according to where the value exists in the response. **Path Extractors** assists with JSONPath and XPath expressions; header, text, and JavaScript handlers are configured directly in the row.

#### JavaScript syntax

For a **JAVASCRIPT** Data Handler, use the following function structure:

```javascript
var executeJs = function(response,headers){
//Write your code here
}
```

* `response` provides the pre-request API response for the script to process.
* `headers` provides the response headers.
* Add the required extraction or transformation logic inside `executeJs`.

Keep the function name and parameters unchanged so Qyrus can execute the handler.

Example JSONPath variable:

* Variable Name: `test`
* Path Reference: `$.name`
* Type: `JSONPATH`

![JSONPath dynamic variable](https://2173886669-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FrWgLy70uByJZz2Zz3InN%2Fuploads%2Fgit-blob-75739bc8bb09438a3823699d0d4e88a2ce5b87f5%2FJSONPath-Dynamic-Variable.png?alt=media)

Use JSONPath only with JSON responses and XPath only with XML responses. For HEADER, use the exact response-header name. Validate JavaScript handlers by sending the pre-request API and confirming the resulting variable value. Variable names must be unique across the project's pre-request APIs.

Recommended names use letters, numbers, and underscores, start with a letter, and do not include surrounding `#` characters. Examples include `access_token`, `customerId`, and `order_id_123`.

## Use the Path Extractor tool

The Path Extractor helps identify a JSONPath or XPath without writing it manually.

1. Send the pre-request API so a response is available.
2. Open **Data Handler**.
3. Select **Path Extractors**.
4. Review the JSON or XML response in the left pane.
5. Select the required node in the structured response pane.
6. Copy the generated path and use it as the **Path Reference**.

![Path Extractor tool](https://2173886669-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FrWgLy70uByJZz2Zz3InN%2Fuploads%2Fgit-blob-82a4127ad6ce2e6b2083097c50bdbf52b747eb89%2FPath-Extractor-Tool.png?alt=media)

Verify that the generated path selects the expected value before saving the variable, especially when the response contains arrays or repeated XML elements.

## Use a pre-request variable

First, create the variable in the pre-request API's **Data Handler**. For example, the following configuration extracts the response's `id` property:

* **Variable Name:** `requestValue`
* **Path Reference:** `$.id`
* **Type:** `JSONPATH`

![Extract a variable from the pre-request response](https://2173886669-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FrWgLy70uByJZz2Zz3InN%2Fuploads%2Fgit-blob-a887f43500485326abab6a27d7114a45d4b6438d%2FExtract-Pre-Request-Variable.png?alt=media)

Select **Save** after adding the extractor. Then open the dependent API script and wrap the variable name with `#` characters wherever variable substitution is supported:

```
#access_token#
#customerId#
#order_id_123#
#requestValue#
```

For example, an extracted token can be used in a request header:

```
Authorization: Bearer #access_token#
```

The example below uses `#requestValue#` as the value of the `url` query parameter. The resulting request URL contains `url=#requestValue#` until execution, when Qyrus substitutes the value extracted by the pre-request API.

![Use a pre-request variable in an API script](https://2173886669-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FrWgLy70uByJZz2Zz3InN%2Fuploads%2Fgit-blob-451a773fac2084e61b98fd794dc67d609292470e%2FUse-Pre-Request-Variable-in-Script.png?alt=media)

At execution time, Qyrus runs the relevant pre-request API, extracts the configured response value, and replaces the variable reference in the dependent test.

## Save, send, edit, clone, or delete an API

* Select **Save** after changing request configuration or Data Handler variables.
* Select **Send** to execute the currently selected pre-request API and inspect its response.
* To edit an API, select it in the left panel, make the required changes, and select **Save**.
* To clone an API, open its three-dot menu and select **Clone**, as you would for a Suite API. Review the copied request and Data Handler configuration before using it, and keep extracted variable names unique across the project.
* To delete APIs, select their checkboxes in the left panel and use the delete icon. Confirm the action when prompted.

Before deleting a pre-request API, remove or replace variables that depend on it. Otherwise, dependent tests can fail because their values are no longer generated.

Pre-request APIs use the same API action pattern as [Suite APIs](/api-testing/build/test-suites.md#script-actions).

After editing, select **Send** and check the response before using the API in a dependent test. If extraction fails, confirm that the response format matches the Data Handler type and that the configured path selects an existing value. Check variable names for duplicates before saving a new extractor.

## Export a pre-request API to another workspace

Use **Export Pre-Request API to Workspace** to copy a configured pre-request API into another workspace that you can access.

1. Select the required API from the **Pre-Request Variables** list.
2. Open the API's export option.
3. In the **Export Pre-Request API to Workspace** dialog, verify the HTTP method and API name shown under **Exporting Pre-Request API**.
4. Choose the destination from **Select Workspace**.
5. Select **Export**.

![Export a pre-request API to another workspace](https://2173886669-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FrWgLy70uByJZz2Zz3InN%2Fuploads%2Fgit-blob-be2cea3160acc410a492c4d122fe05eafb56e9e8%2FExport-Pre-Request-API.png?alt=media)

After exporting, open **Pre-Request Variables** in the destination workspace and confirm that the API and its configuration are available. Review workspace-specific values, certificates, and other dependencies before using the exported API.

## Review execution results

Pre-request API execution details are associated with the dependent test run. Use the relevant report's details view to review the pre-request call, response, extracted values, and any failure that prevented the dependent test from running correctly.

## Related topics

* [Global Variables and Environments](/api-testing/project-setup/global-and-environment.md)
* [Certificates](/api-testing/project-setup/certificate.md)
* [Project Settings](/api-testing/project-setup/project-set-up.md)

Continue to [Certificates](/api-testing/project-setup/certificate.md) to configure client-certificate authentication.