nezhahq.github.io/docs/en_US/guide/api.md

outline
deep

API Interface

Nezha Monitoring supports querying the status information of Agents using the API interface

Creating a Token

Nezha Monitoring's API interface allows for Token authentication and Cookies authentication. To create a new Token, go to the admin panel, click on the avatar in the top right corner, select "API Token," and enter the Token management page. Click "Add Token", add a custom note, and click "Add".

To delete a Token, select the corresponding Token and click the delete icon on the right.

::: warning Tokens are the authentication credentials for the API interface. They are critical to the security of your Dashboard's information, so do not share your Token with others. :::

Authentication Method

Ensure the request header contains Authorization: Token for authentication.

Token authentication method:

Request Headers:
Authorization: Token

Usage Instructions

::: warning Negative timestamps in the following examples represent 0000-00-00. This currently indicates that the Agent has never reported since the Dashboard went online, but it is not recommended to use the positive or negative value to determine the status. :::

::: tip The request method is GET, and the response format is JSON. :::

Get Server List

Request:

GET /api/v1/server/list?tag= 

Parameters:

• tag (optional): ServerTag is the server group. Provide this parameter to query only servers in that group.

Example response:

{
    "code": 0,
    "message": "success",
    "result": [
        {
            "id": 1,
            "name": "Server1",
            "tag": "Tag1",
            "last_active": 1653014667,
            "ipv4": "1.1.1.1",
            "ipv6": "",
            "valid_ip": "1.1.1.1"
        },
        {
            "id": 2,
            "name": "Server2",
            "tag": "Tag2",
            "last_active": -62135596800,
            "ipv4": "",
            "ipv6": "",
            "valid_ip": ""
        }
    ]
}

Get Server Details

Request:

GET /api/v1/server/details?id=&tag= 

Parameters:

• id (optional): ServerID, multiple IDs separated by commas. Provide this parameter to query the server corresponding to that ID and ignore the tag parameter.
• tag (optional): ServerTag, provide this parameter to query only servers in that group.

Example response:

{
    "code": 0,
    "message": "success",
    "result": [
        {
            "id": 1,
            "name": "Server1",
            "tag": "Tag1",
            "last_active": 1653015042,
            "ipv4": "1.1.1.1",
            "ipv6": "",
            "valid_ip": "1.1.1.1",
            "host": {
                "Platform": "darwin",
                "PlatformVersion": "12.3.1",
                "CPU": [
                    "Apple M1 Pro 1 Physical Core"
                ],
                "MemTotal": 17179869184,
                "DiskTotal": 2473496842240,
                "SwapTotal": 0,
                "Arch": "arm64",
                "Virtualization": "",
                "BootTime": 1652683962,
                "CountryCode": "hk",
                "Version": ""
            },
            "status": {
                "CPU": 17.33,
                "MemUsed": 14013841408,
                "SwapUsed": 0,
                "DiskUsed": 2335048912896,
                "NetInTransfer": 2710273234,
                "NetOutTransfer": 695454765,
                "NetInSpeed": 10806,
                "NetOutSpeed": 5303,
                "Uptime": 331080,
                "Load1": 5.23,
                "Load5": 4.87,
                "Load15": 3.99,
                "TcpConnCount": 195,
                "UdpConnCount": 70,
                "ProcessCount": 437
            }
        },
        {
            "id": 2,
            "name": "Server2",
            "tag": "Tag2",
            "last_active": -62135596800,
            "ipv4": "",
            "ipv6": "",
            "valid_ip": "",
            "host": {
                "Platform": "",
                "PlatformVersion": "",
                "CPU": null,
                "MemTotal": 0,
                "DiskTotal": 0,
                "SwapTotal": 0,
                "Arch": "",
                "Virtualization": "",
                "BootTime": 0,
                "CountryCode": "",
                "Version": ""
            },
            "status": {
                "CPU": 0,
                "MemUsed": 0,
                "SwapUsed": 0,
                "DiskUsed": 0,
                "NetInTransfer": 0,
                "NetOutTransfer": 0,
                "NetInSpeed": 0,
                "NetOutSpeed": 0,
                "Uptime": 0,
                "Load1": 0,
                "Load5": 0,
                "Load15": 0,
                "TcpConnCount": 0,
                "UdpConnCount": 0,
                "ProcessCount": 0
            }
        }
    ]
}

Get ICMP Ping / TCPing monitor value

This API does not require authentication, except for servers with HideForGuest option enabled.

Request:

GET /api/v1/monitor/{id}

Parameters:

• id (required): ServerID, must be an positive integer.

Example response:

{
    "code": 0,
    "message": "success",
    "result": [
        {
            "monitor_id": 1,
            "server_id": 1,
            "monitor_name": "Monitor1",
            "server_name": "Server1",
            "created_at": [
                1722142860000,
                1722142920000
            ],
            "avg_delay": [
                68.2275,
                70.1129
            ]
        },
        {
            "monitor_id": 2,
            "server_id": 1,
            "monitor_name": "Monitor2",
            "server_name": "Server1",
            "created_at": [
                1722142860000,
                1722142920000
            ],
            "avg_delay": [
                66.656,
                68.2153
            ]
        },
        {
            "monitor_id": 3,
            "server_id": 1,
            "monitor_name": "Monitor3",
            "server_name": "Server1",
            "created_at": [
                1722142860000,
                1722142920000
            ],
            "avg_delay": [
                61.4525,
                62.342
            ]
        }
    ]
}

Note: created_at corresponds with avg_delay.

Automatic Node Registration

Description: Script for automating node registration. Example code is provided below. Reference: https://github.com/naiba/nezha/pull/472

POST /api/v1/server/register?simple=1

Parameters:

• simple: (optional): Specifies the format of the response data.
  • When set to simple=1 or simple=true, the response will only include a Token string (e.g., 8GYwaxYuLfU7zl7ndC).
  • Otherwise the response will return a complete JSON object:：{"code": 200, "message": "Server created successfully","secret": "8GYwaxYuLfU7zl7ndC"}

Request Payload:

The payload can be completely empty ({}), and the system will apply the following default values:

• Name: Defaults to the node’s IP address ($IP).
• Tag: Defaults to "AutoRegister".
• Note: Defaults to an empty string ("").
• HideForGuest: Defaults to "on".

You can also customize your data:

  "Name": "abcd",        // Node name
  "Tag": "",             // Tag (optional)
  "Note": "",            // Note or description (optional)
  "HideForGuest": "on"   // Whether to hide from guests

Usage Examples

Get All Server Information

import requests

url = "http://your-dashboard/api/v1/server/list"
headers = {
    "Authorization": "your_token"
}

response = requests.get(url, headers=headers)
data = response.json()

for server in data['result']:
    print(f"Server Name: {server['name']}, Last Active: {server['last_active']}, IP: {server['valid_ip']}")

Get Specific Server Details

import requests

server_id = 1  # Replace with your server ID
url = f"http://your-dashboard/api/v1/server/details?id={server_id}"
headers = {
    "Authorization": "your_token"
}

response = requests.get(url, headers=headers)
data = response.json()

server = data['result'][0]
print(f"Server Name: {server['name']}")
print(f"CPU Usage: {server['status']['CPU']}%")
print(f"Memory Used: {server['status']['MemUsed']} bytes")
print(f"Disk Used: {server['status']['DiskUsed']} bytes")
print(f"Network In Speed: {server['status']['NetInSpeed']} bytes/s")
print(f"Network Out Speed: {server['status']['NetOutSpeed']} bytes/s")

With the above example code, you can easily obtain and process server status information, enabling automated monitoring and management.

Automatic Node Registration

1. Create a file named nezha_register.sh, and copy the following content into it:

#!/bin/bash

# Exit if NEZHA_TOKEN is not set
if [ -z "${NEZHA_TOKEN}" ]; then
    echo "NEZHA_TOKEN is not set. Exiting."
    exit 0
fi

# Set default values if variables are not set
NEZHA_PROBE_ADDRESS="${NEZHA_PROBE_ADDRESS:-probe.example.com}"
NEZHA_PROBE_PORT="${NEZHA_PROBE_PORT:-5555}"
NEZHA_DASHBOARD_URL="${NEZHA_DASHBOARD_URL:-https://nezha.example.com}"

NODE_NAME=${NODE_NAME:-$(hostname)}

# Send POST request and capture response and HTTP status code
response=$(curl -s -o response_body.json -w "%{http_code}" -X POST "${NEZHA_DASHBOARD_URL}/api/v1/server/register?simple=true" \
  -H "Content-Type: application/json" \
  -H "Authorization: ${NEZHA_TOKEN}" \
  -d "{\"Name\": \"${NODE_NAME}\"}")

# Extract HTTP status code and Nezha secret
HTTP_CODE="$response"
NEZHA_SECRET=$(cat response_body.json)
rm -f response_body.json

if [ "$HTTP_CODE" != "200" ]; then
    echo "Failed to get Nezha Secret. HTTP status code: $HTTP_CODE"
    exit 1
fi

# Additional check for NEZHA_SECRET to ensure it's not JSON-formatted (indicating failure)
if [[ "${NEZHA_SECRET:0:1}" == "{" ]]; then
    echo "Failed to get Nezha Secret. Received response: ${NEZHA_SECRET}"
    exit 1
fi

# Download and execute the install script with cleanup
curl -fsSL https://raw.githubusercontent.com/nezhahq/scripts/main/install_en.sh -o nezha.sh && \
chmod +x nezha.sh || { echo "Failed to download or make the script executable"; exit 1; }

# Clean up nezha.sh on exit
trap 'rm -f nezha.sh' EXIT

# Run the Nezha agent installation script
CMD="./nezha.sh install_agent "${NEZHA_PROBE_ADDRESS}" "${NEZHA_PROBE_PORT}" "${NEZHA_SECRET}" --tls"

echo "Run commnad : ${CMD}"

eval $CMD

2. Grant execution permission to the script: chmod +x nezha_register.sh
3. Get Token from Nezha dashboard, e.g. POXbxorKJBM8wPMKX8r2PdMblyXvpggB
4. Set Environment Variables

export NEZHA_TOKEN="POXbxorKJBM8wPMKX8r2PdMblyXvpggB" # Obtain this token from the dashboard
export NEZHA_PROBE_ADDRESS="your_probe_address"        # Set your probe address
export NEZHA_DASHBOARD_URL="https://nezha.example.com" # Replace with your dashboard URL
export NEZHA_PROBE_PORT="5555"                         # Modify this port if needed

5. Run the script to complete node registration and probe installation:

./nezha_register.sh

6. If the script runs successfully, you will see output like the following:

Run command: ./nezha.sh install_agent probe.example.com 5555 YOUR_SECRET --tls