giip

Network Topology (Net3D) API Reference

This guide gives you everything you need to push data into GIIP's Network Topology (Net3D) visualization — read it once and you can start inserting data immediately.

🔌 Go to Network Topology →

Prerequisites

ItemDescriptionHow to Obtain
SK (Secret Key)Secret key used for API authenticationAvailable from the 
lsvrdetail
(server detail) or 
corpgroup
(corporation/group management) page in the GIIP admin console
API URLYour GIIP server addressExample: 
https://your-api.azurewebsites.net
LSSNUnique session number issued after server registrationRetrieved from the response in Step 1

What is LSSN?

LSSN (Long-term Session Serial Number) is a numeric ID that identifies a single server. When you register a server for the first time via AgentAutoRegister, a unique LSSN is issued for that server. You then use this LSSN as the 

kKey
value in all subsequent KVSPut data submissions.

Flow summary:

Register server (AgentAutoRegister) → Receive LSSN → Use LSSN as kKey for netstat/db_connections submissions

Authentication

  • Content-Type: 
    application/x-www-form-urlencoded
  • Auth location: Include the SK in the 
    token
    field of the request body     — NOT in an HTTP header
  • Wrong: 
    Authorization: Bearer YOUR_SK
    (not supported)
  • Correct: Include 
    token=YOUR_SK
    in the request body

Step 1: Register the Server (AgentAutoRegister) — Obtain LSSN

Register a server with GIIP and receive an LSSN. Save this LSSN — you will need it for every subsequent call.

  • Endpoint: 
    POST https://YOUR_API_URL/api/giipApi?cmd=AgentAutoRegister
  • Content-Type: 
    application/x-www-form-urlencoded

Request Body Fields:

FieldValue
token
YOUR_SK
text
AgentAutoRegister
jsondata
Serialized JSON string (see example below)

jsondata example:

{
  "hostname": "WEB-SRV-01",
  "os": "Windows Server 2022",
  "cpu_cores": 8,
  "ipv4_local": "10.0.0.5"
}

curl example:

curl -X POST "https://YOUR_API_URL/api/giipApi?cmd=AgentAutoRegister" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     --data-urlencode "token=YOUR_SK" \
     --data-urlencode "text=AgentAutoRegister" \
     --data-urlencode 'jsondata={"hostname":"WEB-SRV-01","os":"Windows Server 2022","cpu_cores":8,"ipv4_local":"10.0.0.5"}'

Response example:

{
  "RstVal": 200,
  "RstMsg": "Success",
  "lssn": 123456
}

Important: Save the 

lssn
value from the response (e.g., 
123456
). It is used as 
kKey
in every Step 2 and Step 3 request.

Step 2: Submit Server Connections (netstat KVSPut)

Send TCP connection information from the current server to external servers.

  • Endpoint: 
    POST https://YOUR_API_URL/api/giipApi
    (no 
    cmd
    query parameter)
  • Content-Type: 
    application/x-www-form-urlencoded

Request Body Fields:

FieldValueDescription
token
YOUR_SKAuthentication key
text
KVSPut kType kKey kFactor
Literal fixed string — copy exactly as shown
jsondata
Serialized JSON string (see example below)Actual connection data

jsondata example:

{
  "kType": "lssn",
  "kKey": "123456",
  "kFactor": "netstat",
  "kValue": [
    {
      "remote_ip": "10.0.0.10",
      "remote_port": 8080,
      "process_name": "nginx.exe",
      "state": "ESTABLISHED"
    },
    {
      "remote_ip": "10.0.0.20",
      "remote_port": 3306,
      "process_name": "myapp.exe",
      "state": "ESTABLISHED"
    }
  ]
}

curl example:

curl -X POST "https://YOUR_API_URL/api/giipApi" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     --data-urlencode "token=YOUR_SK" \
     --data-urlencode "text=KVSPut kType kKey kFactor" \
     --data-urlencode 'jsondata={"kType":"lssn","kKey":"123456","kFactor":"netstat","kValue":[{"remote_ip":"10.0.0.10","remote_port":8080,"process_name":"nginx.exe","state":"ESTABLISHED"}]}'

Response example:

{
  "RstVal": 200,
  "RstMsg": "Success"
}

kValue field reference:

FieldTypeDescription
remote_ip
stringIP address of the destination server
remote_port
integerPort of the destination server
process_name
stringName of the process that owns the connection
state
stringConnection state. Only 
ESTABLISHED
entries appear as links on the topology

Note: Only entries where 

state
is 
ESTABLISHED
are rendered as connection lines in the topology view.

Step 3: Submit DB Connection Data (db_connections KVSPut)

Send query and load information from an application server to a database server.

  • Endpoint: 
    POST https://YOUR_API_URL/api/giipApi
    (same endpoint as netstat)
  • Content-Type: 
    application/x-www-form-urlencoded

Request Body Fields:

FieldValueDescription
token
YOUR_SKAuthentication key
text
KVSPut kType kKey kFactor
Literal fixed string — copy exactly as shown
jsondata
Serialized JSON string (see example below)Actual DB connection data

jsondata example:

{
  "kType": "lssn",
  "kKey": "123456",
  "kFactor": "db_connections",
  "kValue": [
    {
      "client_net_address": "10.0.0.5",
      "program_name": "MyApp.exe",
      "cpu_load": 15,
      "last_sql": "SELECT * FROM users WHERE id = 1",
      "query_hash": "0xAB12CD34"
    },
    {
      "client_net_address": "10.0.0.5",
      "program_name": "MyApp.exe",
      "cpu_load": 42,
      "last_sql": "UPDATE orders SET status = 'shipped' WHERE order_id = 9901",
      "query_hash": "0xCD56EF78"
    }
  ]
}

curl example:

curl -X POST "https://YOUR_API_URL/api/giipApi" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     --data-urlencode "token=YOUR_SK" \
     --data-urlencode "text=KVSPut kType kKey kFactor" \
     --data-urlencode 'jsondata={"kType":"lssn","kKey":"123456","kFactor":"db_connections","kValue":[{"client_net_address":"10.0.0.5","program_name":"MyApp.exe","cpu_load":15,"last_sql":"SELECT * FROM users WHERE id = 1","query_hash":"0xAB12CD34"}]}'

Response example:

{
  "RstVal": 200,
  "RstMsg": "Success"
}

kValue field reference:

FieldTypeDescription
client_net_address
stringSource server IP. Must exactly match 
tManagedDatabase.db_host
to create a DB link
program_name
stringExecutable name. Displayed as the Outgoing node label in the topology
cpu_load
integerQuery load (%). Controls link line thickness and particle speed
last_sql
stringCurrently executing SQL statement. Displayed in the detail view modal
query_hash
stringSQL statement hash. Used to group identical queries

Step 4: Retrieve DB List (ManagedDatabaseList)

Retrieve the list of managed databases registered in the project.

  • Endpoint: 
    POST https://YOUR_API_URL/api/giipApi
  • Content-Type: 
    application/x-www-form-urlencoded

Request Body Fields:

FieldValue
token
YOUR_SK
text
ManagedDatabaseList mssql
(specify db_type as needed)

curl example:

curl -X POST "https://YOUR_API_URL/api/giipApi" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     --data-urlencode "token=YOUR_SK" \
     --data-urlencode "text=ManagedDatabaseList mssql"

Response example:

{
  "RstVal": 200,
  "RstMsg": "Success",
  "data": [
    {
      "db_host": "10.0.0.30",
      "db_name": "ProductionDB",
      "db_type": "mssql"
    }
  ]
}

The SK embedded in 

token
carries the project context, so you do not need to pass 
csn
separately — the server resolves it automatically.

Full Example Scripts by Language

1. PowerShell (Windows)

# Configuration
$AT = "YOUR_SECRET_KEY"
$API_URL = "https://your-api.azurewebsites.net/api/giipApi"

# Step 1: Server Registration (AgentAutoRegister) — Obtain LSSN
$discoveryData = @{
    hostname   = $env:COMPUTERNAME
    os         = (Get-CimInstance Win32_OperatingSystem).Caption
    cpu_cores  = (Get-CimInstance Win32_Processor).NumberOfLogicalProcessors
    ipv4_local = (Get-NetIPAddress -AddressFamily IPv4 |
                  Where-Object { $_.IPAddress -ne '127.0.0.1' } |
                  Select-Object -First 1).IPAddress
} | ConvertTo-Json -Compress

$regBody = @{
    token    = $AT
    text     = "AgentAutoRegister"
    jsondata = $discoveryData
}
$resp = Invoke-RestMethod -Uri "$API_URL`?cmd=AgentAutoRegister" `
        -Method Post -ContentType "application/x-www-form-urlencoded" -Body $regBody
$lssn = $resp.lssn
Write-Host "Registered. LSSN: $lssn"

# Step 2: netstat KVSPut
$connections = Get-NetTCPConnection -State Established | Select-Object -First 100 | ForEach-Object {
    @{
        remote_ip    = $_.RemoteAddress
        remote_port  = $_.RemotePort
        state        = "ESTABLISHED"
        process_name = (Get-Process -Id $_.OwningProcess -ErrorAction SilentlyContinue).ProcessName
    }
}
$netstatPayload = @{
    kType   = "lssn"
    kKey    = "$lssn"
    kFactor = "netstat"
    kValue  = $connections
} | ConvertTo-Json -Compress -Depth 10

$putBody = @{
    token    = $AT
    text     = "KVSPut kType kKey kFactor"
    jsondata = $netstatPayload
}
$r2 = Invoke-RestMethod -Uri $API_URL -Method Post `
      -ContentType "application/x-www-form-urlencoded" -Body $putBody
Write-Host "netstat result: $($r2.RstMsg)"

# Step 3: db_connections KVSPut
$dbPayload = @{
    kType   = "lssn"
    kKey    = "$lssn"
    kFactor = "db_connections"
    kValue  = @(
        @{
            client_net_address = "10.0.0.5"
            program_name       = "MyApp.exe"
            cpu_load           = 15
            last_sql           = "SELECT * FROM users WHERE id = 1"
            query_hash         = "0xAB12CD34"
        }
    )
} | ConvertTo-Json -Compress -Depth 10

$putBody2 = @{
    token    = $AT
    text     = "KVSPut kType kKey kFactor"
    jsondata = $dbPayload
}
$r3 = Invoke-RestMethod -Uri $API_URL -Method Post `
      -ContentType "application/x-www-form-urlencoded" -Body $putBody2
Write-Host "db_connections result: $($r3.RstMsg)"

2. Bash Shell (Linux)

#!/bin/bash
AT="YOUR_SECRET_KEY"
API_URL="https://your-api.azurewebsites.net/api/giipApi"

# Step 1: Server Registration (AgentAutoRegister) — Obtain LSSN
JSON_DATA=$(cat <<EOF
{
  "hostname": "$(hostname)",
  "os": "$(grep PRETTY_NAME /etc/os-release | cut -d'"' -f2)",
  "cpu_cores": $(nproc),
  "ipv4_local": "$(hostname -I | awk '{print $1}')"
}
EOF
)
RESP=$(curl -s -X POST "$API_URL?cmd=AgentAutoRegister" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     --data-urlencode "token=$AT" \
     --data-urlencode "text=AgentAutoRegister" \
     --data-urlencode "jsondata=$JSON_DATA")
LSSN=$(echo "$RESP" | jq -r '.lssn')
echo "Registered. LSSN: $LSSN"

# Step 2: netstat KVSPut
CONNS=$(ss -tunp | awk '/ESTAB/{
  split($5,a,":");
  split($6,b,":");
  printf "{\"remote_ip\":\"%s\",\"remote_port\":%s,\"process_name\":\"unknown\",\"state\":\"ESTABLISHED\"}",a[1],a[2]
}' | paste -sd,)

NETSTAT_PAYLOAD=$(cat <<EOF
{
  "kType": "lssn",
  "kKey": "$LSSN",
  "kFactor": "netstat",
  "kValue": [$CONNS]
}
EOF
)
RESP2=$(curl -s -X POST "$API_URL" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     --data-urlencode "token=$AT" \
     --data-urlencode "text=KVSPut kType kKey kFactor" \
     --data-urlencode "jsondata=$NETSTAT_PAYLOAD")
echo "netstat result: $(echo "$RESP2" | jq -r '.RstMsg')"

# Step 3: db_connections KVSPut
DB_PAYLOAD=$(cat <<EOF
{
  "kType": "lssn",
  "kKey": "$LSSN",
  "kFactor": "db_connections",
  "kValue": [
    {
      "client_net_address": "10.0.0.5",
      "program_name": "MyApp",
      "cpu_load": 15,
      "last_sql": "SELECT * FROM users WHERE id = 1",
      "query_hash": "0xAB12CD34"
    }
  ]
}
EOF
)
RESP3=$(curl -s -X POST "$API_URL" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     --data-urlencode "token=$AT" \
     --data-urlencode "text=KVSPut kType kKey kFactor" \
     --data-urlencode "jsondata=$DB_PAYLOAD")
echo "db_connections result: $(echo "$RESP3" | jq -r '.RstMsg')"

3. Python (Cross-platform)

import json
import platform
import socket
import urllib.parse
import urllib.request

AT = "YOUR_SECRET_KEY"
BASE_URL = "https://your-api.azurewebsites.net/api/giipApi"


def api_post(url, fields):
    payload = urllib.parse.urlencode(fields).encode("utf-8")
    req = urllib.request.Request(
        url,
        data=payload,
        headers={"Content-Type": "application/x-www-form-urlencoded; charset=utf-8"},
    )
    with urllib.request.urlopen(req) as f:
        return json.loads(f.read().decode("utf-8"))


# Step 1: Server Registration (AgentAutoRegister) — Obtain LSSN
registration_data = {
    "hostname": socket.gethostname(),
    "os": platform.platform(),
    "cpu_cores": 8,
    "ipv4_local": socket.gethostbyname(socket.gethostname()),
}
resp = api_post(
    f"{BASE_URL}?cmd=AgentAutoRegister",
    {
        "token": AT,
        "text": "AgentAutoRegister",
        "jsondata": json.dumps(registration_data),
    },
)
lssn = resp.get("lssn")
print(f"Registered. LSSN: {lssn}")

# Step 2: netstat KVSPut
netstat_payload = {
    "kType": "lssn",
    "kKey": str(lssn),
    "kFactor": "netstat",
    "kValue": [
        {
            "remote_ip": "10.0.0.10",
            "remote_port": 8080,
            "state": "ESTABLISHED",
            "process_name": "myapp",
        }
    ],
}
resp2 = api_post(
    BASE_URL,
    {
        "token": AT,
        "text": "KVSPut kType kKey kFactor",
        "jsondata": json.dumps(netstat_payload),
    },
)
print(f"netstat result: {resp2.get('RstMsg')}")

# Step 3: db_connections KVSPut
db_payload = {
    "kType": "lssn",
    "kKey": str(lssn),
    "kFactor": "db_connections",
    "kValue": [
        {
            "client_net_address": "10.0.0.5",
            "program_name": "MyApp.exe",
            "cpu_load": 15,
            "last_sql": "SELECT * FROM users WHERE id = 1",
            "query_hash": "0xAB12CD34",
        }
    ],
}
resp3 = api_post(
    BASE_URL,
    {
        "token": AT,
        "text": "KVSPut kType kKey kFactor",
        "jsondata": json.dumps(db_payload),
    },
)
print(f"db_connections result: {resp3.get('RstMsg')}")

Verification

After running a script, follow these steps to confirm data was received correctly.

  1. Server registration: Go to 
    Core Management > Server Inventory
    and confirm the server appears with the correct hostname.
  2. DB mapping: Verify that 
    client_net_address
    exactly matches the 
    db_host
    value in 
    tManagedDatabase
    .
  3. Topology viewer: Navigate to 
    /admin/network-topology
    and check whether connection lines between nodes are active. Data is typically reflected within 1–2 minutes of transmission.

Data Integrity Rules

Verify the following conditions before or after inserting data.

  1. IP mapping: The 
    tLSvr.ips
    field must be a JSON array in the form 
    [{"CIDR":"10.0.0.5/24"}]
    . A plain string causes the node to appear as 'External' in the topology.
  2. DB host match: The 
    client_net_address
    in 
    db_connections
    must be an exact text match (including case and whitespace) of 
    tManagedDatabase.db_host
    for a DB link to be created.
  3. JSON Depth: When serializing jsondata that contains a 
    kValue
    array, use Depth 10 or higher. Insufficient depth truncates nested objects.
  4. state value: Only 
    netstat
    entries where 
    state
    equals 
    ESTABLISHED
    are rendered as connection lines in the topology.

Troubleshooting

Response RstVal is not 200

RstValMeaningAction
401Authentication failedVerify the 
token
value (SK). Confirm it is in the request body, not an HTTP header
400Bad requestVerify the 
text
field is exactly 
KVSPut kType kKey kFactor
(literal string)
500Server errorValidate jsondata is well-formed JSON. Check for unescaped quotes inside the string

No connection lines appear in the topology

  1. Confirm the 
    state
    value in 
    netstat
    kValue items is exactly 
    ESTABLISHED
    (uppercase).
  2. Confirm 
    client_net_address
    in 
    db_connections
    is an exact match of the DB host IP registered in GIIP.
  3. Confirm 
    tLSvr.ips
    is a JSON array (
    [{"CIDR":"..."}]
    ), not a plain string.

LSSN was lost

Call AgentAutoRegister again with the same 

hostname
. The server returns the existing LSSN as long as the hostname is unique per server.

jsondata is being truncated in curl

Use 

--data-urlencode
instead of 
-d
. This safely URL-encodes JSON strings that contain special characters. For very large payloads, switch to the 
giipApiSk3
endpoint (see below).

Python NameError for undefined variable

This guide's Python examples use a single variable named 

AT
. Do not mix in a variable named 
SK
— it is not defined in these scripts.

High-fidelity Logging Endpoint (Sk3)

When transmitting thousands of connection entries or when you need detailed error diagnostics, use the 

giipApiSk3
endpoint.

  • Endpoint: 
    https://giipfaw.azurewebsites.net/api/giipApiSk3
  • Benefits: Prevents data truncation for large jsondata payloads; automatically records detailed agent environment information and stack traces on error for faster topology debugging.
  • Usage: Use the same request format as the standard endpoint — just change the URL.

Related Documents

Version: 1.4 Last Updated: 2026-06-19 Source: 

giipv3/public/help/api-network-topology.en.md

← Previous
Network & Security Policy API
Next →
System Management API