Other API

11.1 Other

11.1.1 View Version Information of HugeGraph

Method & Url

1GET http://localhost:8080/versions

Response Status

1200

Response Body

1{
2    "versions": {
3        "version": "v1",
4        "core": "1.7.0",
5        "gremlin": "3.5.1",
6        "api": "0.72.0.0"
7    }
8}

11.1.2 View the profile of the server

Returns the service name, the core version, the documentation links and the API groups served by this node.

Method & Url

1GET http://localhost:8080/

Response Status

1200

Response Body

The swagger_ui value is derived from restserver.url, and apis lists the API groups registered on this node, sorted by name.

 1{
 2    "service": "hugegraph",
 3    "version": "1.7.0",
 4    "doc": "https://hugegraph.apache.org/docs/",
 5    "api_doc": "https://hugegraph.apache.org/docs/clients/",
 6    "swagger_ui": "http://127.0.0.1:8080/swagger-ui/index.html",
 7    "apis": [
 8        "arthas",
 9        "auth",
10        "cypher",
11        "filter",
12        "graph",
13        "gremlin",
14        "job",
15        "metrics",
16        "profile",
17        "raft",
18        "schema",
19        "space",
20        "traversers",
21        "variables"
22    ]
23}

11.1.3 List all APIs of the server

Lists every registered resource method, grouped by API group and resource class. Each entry carries the url, the HTTP method and the query parameters with their types and default values.

Method & Url

1GET http://localhost:8080/apis

Response Status

1200

Response Body

The response is long, the following fragment shows the shape:

 1{
 2    "apis": {
 3        "schema": {
 4            "PropertyKeyAPI": [
 5                {
 6                    "url": "graphspaces/{graphspace}/graphs/{graph}/schema/propertykeys",
 7                    "method": "GET",
 8                    "parameters": [
 9                        {
10                            "name": "names",
11                            "type": "java.util.List<java.lang.String>",
12                            "default_value": null
13                        }
14                    ]
15                }
16            ]
17        }
18    }
19}

11.1.4 View and switch the exception trace stack

Whether the error responses of the server carry the exception stack in the exception and cause fields is decided by the exception.allow_trace option (default true). The switch below is a node-wide runtime override: while it is on, the stack is always included, no matter what the option says. GET reports the state of that override, which starts as false.

Method & Url

1GET http://localhost:8080/exception/trace

Response Status

1200

Response Body

1{
2    "trace": false
3}

Method & Url

1PUT http://localhost:8080/exception/trace

Request Body

1true

Response Status

1200

Response Body

1{
2    "trace": true
3}

11.1.5 Manage the IP allowlist, this operation requires administrator privileges

The allowlist is only enforced when it is switched on, see the white_ip.status option (default disable).

List the allowlist

Method & Url

1GET http://localhost:8080/whiteiplist

Response Status

1200

Response Body

1{
2    "whiteIpList": [
3        "127.0.0.1"
4    ]
5}

Add IPs to or remove IPs from the allowlist

Params

• ips: list of IPv4 addresses
• action: load to add, remove to delete

Method & Url

1POST http://localhost:8080/whiteiplist

Request Body

1{
2    "ips": [
3        "10.0.0.1",
4        "10.0.0.2"
5    ],
6    "action": "load"
7}

Response Status

1202

Response Body

existed_ips are the addresses already in the list, added_ips are the newly added ones, and illegal_ips is only returned when some addresses are not valid IPv4 addresses. For action=remove the response carries removed_ips and non_existed_ips instead.

1{
2    "existed_ips": [],
3    "added_ips": [
4        "10.0.0.1",
5        "10.0.0.2"
6    ]
7}

Enable or disable the allowlist

Params

• status: true to enable, false to disable

Method & Url

1PUT http://localhost:8080/whiteiplist?status=true

Response Status

1200

Response Body

1{
2    "WhiteIpListOpen": true
3}

11.1.6 Start the Arthas agent

Starting with HugeGraph 1.8.0, Server and Store bundle Arthas 4.1.5 (PD does not embed an Arthas agent). You can attach it to a running JVM for live troubleshooting via the local script or the administrator HTTP endpoint.

Activation & Diagnostics

1# Run on the host as the service OS user (uses bundled agent offline, no restart needed)
2bin/arthas.sh
3
4# Container environments (official images bundle JDK 17)
5docker exec -it <container> bin/arthas.sh

1# Specify target JVM PID and custom telnet port (multi-instance on host)
2bin/arthas.sh --pid <PID> --telnet-port 3659
3
4# Specify remote bind address and native authentication credentials
5bin/arthas.sh --target-ip 0.0.0.0 --username admin --password '<password>'
6
7# Non-interactive single-command batch execution
8bin/arthas.sh --command version

1# 1. Invoke REST API to attach diagnostic agent (requires Server auth; default ports 8562/8561 on 127.0.0.1)
2curl -u admin:pa -X PUT http://127.0.0.1:8080/arthas
3
4# 2. Connect to the active agent using the local script
5bin/arthas.sh --telnet-port 8562

Operational Notes & Security Configuration

• Session Exit & Cleanup: The local script automatically stops Arthas and releases ports when exiting (via quit, stop, or --command completion), leaving the service JVM running. If activated via HTTP API only, execute stop in the console to unload the agent.
• Authentication & Security: Enable native authentication before exposing diagnostic ports beyond loopback. Supply credentials via --username/--password in the script or set JVM properties -Darthas.username and -Darthas.password. For full authentication behavior and options, see Arthas Authentication Documentation.
• Disabling Dangerous Commands: In rest-server.properties, configure arthas.disabled_commands with a comma-separated list (e.g., jad,mc). Keep session and stop enabled so tooling can manage the agent lifecycle. See Arthas Commands for command usage.

HTTP Response Body

A successful activation returns HTTP 200 and the applied configuration:

1{
2    "arthas.telnetPort": "8562",
3    "arthas.httpPort": "8561",
4    "arthas.ip": "127.0.0.1",
5    "arthas.disabledCommands": ""
6}