Working with Postman

6.3.1 Introduction

Postman is a popular tool for API testing. VNISH Firmware provides a REST API, accessible on every miner. This guide will show you how to configure Postman to work with this API, starting from the very first environment setup.

6.3.2 Installation

Download and install the Postman desktop application from the official website, or use the Postman web version in your browser.

6.3.3 Obtaining and Importing the API Specification

The VNISH API is described in OpenAPI format. You can view and download the documentation directly on the miner:

• in the firmware web interface: Tech Support → API section;
• or by opening http://<MINER_IP>/docs in your browser. The obtained specification file (JSON) is used for import into Postman, eliminating the need to create all requests manually: Importing the API specification into Postman

1. In Postman, click the «Import» icon.
2. Select the xminer-api JSON specification and upload it.
3. Postman will create an xminer-api collection, organizing all endpoints into folders.

Important: Postman groups requests not by tags from the specification (auth, mining, etc.), but by the first URL segment.

6.3.4 Environment Setup

In Postman, there are two levels of variables that should be separated:

• Global: values that are the same for all miners with VNISH firmware.
• Environment: values unique to a specific miner.

Step 1. Global Variable

1. Open the Environments tab in the right panel. Select Globals.
2. In the variables table, click on the Add variable row.
3. Create a variable:

• Variable: BASE_PATH
• Value: /api/v1

4. Save (Ctrl+S or the save button in the top right corner). Setting up a global variable in Postman This is the common base API path, identical for any miner running VNISH.

Step 2. Environment for a Specific Miner

1. On the Environments tab, create a new environment (e.g., My Miner).
2. Add a variable:

• Variable: MINER_IP
• Value: The miner's IP address with the protocol specified, for example http://<MINER_IP>

3. Also create an empty AUTH_TOKEN variable. It will be automatically populated after login.

How to configure its automatic population is described in the section «Configuring Postman for automatic bearer token retrieval and substitution».

4. Save the environment and select it as active from the environment dropdown list in the top right corner of the Postman web interface — without this, variables will not be substituted into requests. Setting up an environment for a specific miner in Postman

Step 3. baseUrl Variable in the Collection

When importing the specification, Postman automatically creates a baseUrl variable in the collection, which is used to construct the path for all requests ({{baseUrl}}/unlock, {{baseUrl}}/status, etc.). By default, it only contains the base path without the miner's address (/api/v1), so it needs to be reconfigured.

1. Open the xminer-api collection → Variables tab.
2. Find the baseUrl row.
3. In the Value column, replace the value with:

   {{MINER_IP}}{{BASE_PATH}}
   

4. Save the changes. Now baseUrl is automatically assembled from the MINER_IP environment variable and the BASE_PATH global variable, and the final address looks like this: http://<MINER_IP>/api/v1.

If you change the miner or its IP address, simply update the MINER_IP value in the corresponding environment. All requests in the collection will automatically pick up the new address, without manual editing of each request.

6.3.5 Configuring Postman for Automatic Bearer Token Retrieval and Substitution

To obtain a token via /unlock and configure Postman to automatically substitute this token into all subsequent requests, without manual copying each time.

Step 1. Check Active Environment

Ensure that the My Miner environment is selected in the top right corner of Postman.

Step 2. Create the unlock Request

• Method POST, URL: {{baseUrl}}/unlock.
• Tab Body > raw > type JSON: Insert the JSON below as the message:

{"pw":"device_password"}

Step 3. Auto-save Token Script

Copy and paste the script below into the Scripts > Post-response tab:

pm.environment.unset('AUTH_TOKEN');

pm.test('Status code is 200', function () {
    pm.response.to.have.status(200);
});

const json = pm.response.json();
pm.environment.set('AUTH_TOKEN', json.token);

The script clears the old AUTH_TOKEN value, verifies that the server responded with 200 OK, extracts the token field from the response body, and saves it to the AUTH_TOKEN environment variable.

Step 4. Save and Send Request

Save and send the request. If the password is correct, a 200 OK response will be received, and AUTH_TOKEN in the My Miner environment will be automatically populated (you can check this in the request variables panel).

Step 5. Configure Collection Authorization

Open the xminer-api collection → Authorization tab → type Bearer Token → in the Token field, enter {{AUTH_TOKEN}}. Now all requests in the collection that inherit authorization from the collection will automatically send the required header.

Step 6. Using and Refreshing the Token

Use the other requests as usual. When the session expires, send {{baseUrl}}/unlock again, and the script will refresh the token.

6.3.6 How to Get a cURL Request from Postman

If an error occurs while working with the API, developers or support may ask you to provide the request as a curl command. You can get a ready-made curl command directly from Postman in a few steps, without manually rewriting the request:

1. Open the desired request in the collection.
2. To the right of the Send button, click the </> (Code) icon — it opens a menu with ready-made request code in various languages.
3. In the dropdown list, find the cURL option. Getting a cURL request from Postman