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

Item	Description	How to Obtain
SK (Secret Key)	Secret key used for API authentication	Available from the lsvrdetail (server detail) or corpgroup (corporation/group management) page in the GIIP admin console
API URL	Your GIIP server address	Example: https://your-api.azurewebsites.net
LSSN	Unique session number issued after server registration	Retrieved 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:

Field	Value
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:

Field	Value	Description
token	YOUR_SK	Authentication 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:

Field	Type	Description
remote_ip	string	IP address of the destination server
remote_port	integer	Port of the destination server
process_name	string	Name of the process that owns the connection
state	string	Connection 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:

Field	Value	Description
token	YOUR_SK	Authentication 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:

Field	Type	Description
client_net_address	string	Source server IP. Must exactly match tManagedDatabase.db_host to create a DB link
program_name	string	Executable name. Displayed as the Outgoing node label in the topology
cpu_load	integer	Query load (%). Controls link line thickness and particle speed
last_sql	string	Currently executing SQL statement. Displayed in the detail view modal
query_hash	string	SQL 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:

Field	Value
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

The full PowerShell / Bash / Python example scripts have been moved to a separate guide for length.

📘 Network Topology (Net3D) Full Example Scripts by Language

---

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

RstVal	Meaning	Action
401	Authentication failed	Verify the token value (SK). Confirm it is in the request body, not an HTTP header
400	Bad request	Verify the text field is exactly KVSPut kType kKey kFactor (literal string)
500	Server error	Validate 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

• API Result Codes Guide (RstVal)

---

Version: 1.4 Last Updated: 2026-06-19 Source: giipv3/public/help/api-network-topology.en.md