KVS (Key-Value Store) API Guide (v2.0)

Complete API reference for writing and querying infrastructure status data (factors) through GIIP's flexible KVS (Key-Value Store).

🔌 Go to KVS List →

📋 Overview

KVS is a general-purpose key-value store that holds time-series and structured data collected by agents — performance metrics, network connections, inventory, process lists, and more.

API Role Authentication Endpoint

KVSPut

Record data (write)

API	Role	Authentication	Endpoint
KVSPut	Record data (write)	Body `token` field (SK)	`giipApiSk2` / `giipApiSk3`
KVSFactorLast	Retrieve latest 1 record	AK header or Body `token` (SK)	`giipApi` (AK) / `giipApiSk2` (SK)
KVSFactorList	Retrieve history list	`x-giip-ak` / `x-giip-sk` header	`giipApi`

Body

token

field (SK)

giipApiSk2

giipApiSk3

KVSFactorLast

Retrieve latest 1 record

AK header or Body

token

(SK)

giipApi

(AK) /

giipApiSk2

(SK)

KVSFactorList

Retrieve history list

x-giip-ak

x-giip-sk

header

giipApi

🔑 Prerequisites

You need two things before using the KVS API.

1. SK (Secret Key)

The

sk

field value in your

giipAgent.cfg

file. Pass this as the

token

field in the request body for KVSPut.

How to obtain: Find the SK on the
lsvrdetail
(server detail) or
corpgroup
(corporation/group management) page in the GIIP admin console.

// giipAgent.cfg example
{
  "sk": "your-secret-key-here"
}

2. LSSN (Server Sequence Number)

The value of the

tLSvr.LSsn

column. Used as

kKey

when

kType

"lssn"

For how to obtain your SK and LSSN, see the Network Topology API Guide.

✍️ KVSPut — Write Data

Concept

KVSPut

is the write API that stores data collected by agents into the KVS. The combination of

kType

kKey

kFactor

identifies the storage location, and

kValue

holds the actual payload.

Request Structure

Endpoint:

POST https://YOUR_API_URL/api/giipApiSk2

(or

giipApiSk3

)

Content-Type:
```
application/x-www-form-urlencoded
```

Body Field Required Description

Body Field	Required	Description
`token`	✅	SK value (the `sk` field in `giipAgent.cfg` )
`text`	✅	Literal string: `KVSPut kType kKey kFactor` (send this exact string, not variables)
`jsondata`	✅	JSON string: `{"kType":"...","kKey":"...","kFactor":"...","kValue":...}`

token

✅

SK value (the

sk

field in

giipAgent.cfg

)

text

✅

Literal string:

KVSPut kType kKey kFactor

(send this exact string, not variables)

jsondata

✅

JSON string:

{"kType":"...","kKey":"...","kFactor":"...","kValue":...}

Important: The
text
field must contain the fixed string
KVSPut kType kKey kFactor
literally. All actual identifiers go inside
jsondata
.

jsondata Field Reference

Field	Type	Description	Example
`kType`	string	Key type ( `"lssn"` or `"database"` )	`"lssn"`
`kKey`	string	Server LSSN or DB ID (must be a numeric string)	`"123456"`
`kFactor`	string	Data category name	`"netstat"`
`kValue`	any	Actual data to store (JSON array or object)	`[{...}]`

kType / kKey Rules

kType	Meaning	kKey Value
`"lssn"`	Server-level data	`tLSvr.LSsn` column value (numeric string)
`"database"`	Database-level data	`tManagedDatabase.mdb_id` column value (numeric string)

kKey must be a numeric string. Hostnames (
"myserver"
) and UUIDs (
"abc-123-..."
) are not accepted.

Common kFactor Values

kFactor	Description	kValue Format
`netstat`	TCP connections between servers	`[{remote_ip, remote_port, process_name, state}]`
`db_connections`	Database connection info	`[{client_net_address, program_name, cpu_load, last_sql}]`
`heartbeat`	Agent liveness signal	`{"status":"alive","timestamp":"..."}`
`netinv`	Server inventory	`{hostname, os, cpu_cores, ipv4_local}`
`processlist`	Running process list	`[{pid, name, cpu_percent, memory_mb}]`
`custom_factor`	User-defined data	Free-form JSON

Code Examples

The examples below write

netstat

data for server LSSN

. Replace

YOUR_API_URL

and

YOUR_SK

with real values.

curl

curl -X POST "https://YOUR_API_URL/api/giipApiSk2" \
  -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.5","remote_port":5432,"process_name":"python","state":"ESTABLISHED"}]}'

PowerShell

$body = @{
    token    = "YOUR_SK"
    text     = "KVSPut kType kKey kFactor"
    jsondata = '{"kType":"lssn","kKey":"123456","kFactor":"netstat","kValue":[{"remote_ip":"10.0.0.5","remote_port":5432,"process_name":"python","state":"ESTABLISHED"}]}'
}

$response = Invoke-RestMethod `
    -Method Post `
    -Uri "https://YOUR_API_URL/api/giipApiSk2" `
    -ContentType "application/x-www-form-urlencoded" `
    -Body $body

$response | ConvertTo-Json

Bash

SK="YOUR_SK"
API_URL="https://YOUR_API_URL/api/giipApiSk2"

JSONDATA=$(cat <<'EOF'
{
  "kType": "lssn",
  "kKey": "123456",
  "kFactor": "netstat",
  "kValue": [
    {
      "remote_ip": "10.0.0.5",
      "remote_port": 5432,
      "process_name": "python",
      "state": "ESTABLISHED"
    }
  ]
}
EOF
)

curl -X POST "$API_URL" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "token=$SK" \
  --data-urlencode "text=KVSPut kType kKey kFactor" \
  --data-urlencode "jsondata=$JSONDATA"

Python

import requests
import json

API_URL = "https://YOUR_API_URL/api/giipApiSk2"
SK = "YOUR_SK"

kv_data = {
    "kType": "lssn",
    "kKey": "123456",
    "kFactor": "netstat",
    "kValue": [
        {
            "remote_ip": "10.0.0.5",
            "remote_port": 5432,
            "process_name": "python",
            "state": "ESTABLISHED"
        }
    ]
}

payload = {
    "token": SK,
    "text": "KVSPut kType kKey kFactor",
    "jsondata": json.dumps(kv_data)
}

response = requests.post(
    API_URL,
    data=payload,
    headers={"Content-Type": "application/x-www-form-urlencoded"}
)

print(response.json())

Response Interpretation

Success

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

Failure example

{
  "RstVal": 401,
  "RstMsg": "Unauthorized"
}

See the API Result Codes Guide for the full list of response codes.

🔍 KVSFactorLast — Query Latest Data

Returns the single most recent record for a specified factor on a given source.

Authentication

Header:
```
x-giip-ak: YOUR_AK
```
/
```
x-giip-sk: YOUR_SK
```

Request Format

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

text=KVSFactorLast <factorType>, <lssn>, <factor>

Examples

Query the latest

netstat

data for LSSN

curl -X POST "https://YOUR_API_URL/api/giipApi" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "x-giip-ak: YOUR_AK" \
  -H "x-giip-sk: YOUR_SK" \
  --data-urlencode "text=KVSFactorLast lssn, 123456, netstat"

PowerShell:

$headers = @{
    "x-giip-ak" = "YOUR_AK"
    "x-giip-sk" = "YOUR_SK"
}

$body = @{
    text = "KVSFactorLast lssn, 123456, netstat"
}

Invoke-RestMethod `
    -Method Post `
    -Uri "https://YOUR_API_URL/api/giipApi" `
    -Headers $headers `
    -ContentType "application/x-www-form-urlencoded" `
    -Body $body

SK-Based Query (

giipApiSk2

)

Query KVS data using only SK, without an AK, for servers in the same corporate group (CGSn).

curl -X POST "https://YOUR_API_URL/api/giipApiSk2" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "token=YOUR_SK" \
  --data-urlencode "text=KVSFactorLast lssn, 123456, netstat"

Invoke-RestMethod `
    -Method Post `
    -Uri "https://YOUR_API_URL/api/giipApiSk2" `
    -ContentType "application/x-www-form-urlencoded" `
    -Body @{
        token = "YOUR_SK"
        text  = "KVSFactorLast lssn, 123456, netstat"
    }

Scope: Only servers belonging to the SK's CGSn (corporate group) can be queried.

📜 KVSFactorList — Query History

Returns a list of historical records matching specified conditions. Use

as the factor name to retrieve all factors for a given source.

Request Format

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

text=KVSFactorList <factorType>, <lssn>, <factor>

Examples

Query all factor history for LSSN

curl -X POST "https://YOUR_API_URL/api/giipApi" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "x-giip-ak: YOUR_AK" \
  -H "x-giip-sk: YOUR_SK" \
  --data-urlencode "text=KVSFactorList lssn, 123456, *"

Query only

heartbeat

history:

curl -X POST "https://YOUR_API_URL/api/giipApi" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "x-giip-ak: YOUR_AK" \
  -H "x-giip-sk: YOUR_SK" \
  --data-urlencode "text=KVSFactorList lssn, 123456, heartbeat"

🛡️ Sk3 High-Fidelity Logging

Use the

giipApiSk3

endpoint for large payloads or when data integrity is critical.

Endpoint:

https://giipfaw.azurewebsites.net/api/giipApiSk3

Advantages:
- Prevents data loss when transmitting large
```
jsondata
```
  payloads
- On failure, stores the agent's detailed error log (StackTrace) alongside the record for easier debugging
Tip: When using KVSPut, include
```
kType
```
,
```
kKey
```
,
```
kFactor
```
, and
```
kValue
```
inside
```
jsondata
```
. The Sk3 engine maps these fields automatically for reliable database writes.

# KVSPut via Sk3 endpoint
curl -X POST "https://giipfaw.azurewebsites.net/api/giipApiSk3" \
  -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":[...]}'

🔧 Troubleshooting

KVSPut returns 401

Verify the SK value in the
```
token
```
field is correct.
SK must be sent in the Body
token
field, not in a header.

KVSPut returns 400

Check that the
```
text
```
field is exactly
```
KVSPut kType kKey kFactor
```
(this literal string).
Verify that
```
jsondata
```
is valid JSON.
Confirm
```
kKey
```
is a numeric string (e.g.,
```
"123456"
```
). Hostnames and UUIDs are not valid.

Verify that data was stored

Query with KVSFactorLast immediately after KVSPut using the same kType/kKey/kFactor combination:

# Step 1: Write data
curl -X POST "https://YOUR_API_URL/api/giipApiSk2" \
  -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":"heartbeat","kValue":{"status":"alive","timestamp":"2026-06-19T10:00:00Z"}}'

# Step 2: Confirm the write
curl -X POST "https://YOUR_API_URL/api/giipApi" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "x-giip-ak: YOUR_AK" \
  -H "x-giip-sk: YOUR_SK" \
  --data-urlencode "text=KVSFactorLast lssn, 123456, heartbeat"

KVSFactorLast / KVSFactorList returns empty results

No data has been stored for that kType/kKey/kFactor combination yet.
Write data with KVSPut first, then query.
Double-check that the LSSN number is correct.

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

giipv3/public/help/api-kvs.en.md

Related Documents:

Network Topology API Guide — How to obtain SK and LSSN
API Result Codes Guide (RstVal)

KVS (Key-Value Store) API Guide (v2.0)

📋 Overview

🔑 Prerequisites

1. SK (Secret Key)

2. LSSN (Server Sequence Number)

✍️ KVSPut — Write Data

Concept

Request Structure

jsondata Field Reference

kType / kKey Rules

Common kFactor Values

Code Examples

curl

PowerShell

Bash

Python

Response Interpretation

🔍 KVSFactorLast — Query Latest Data

Authentication

Request Format

Examples

SK-Based Query (giipApiSk2)

📜 KVSFactorList — Query History

Request Format

Examples

🛡️ Sk3 High-Fidelity Logging

🔧 Troubleshooting

KVSPut returns 401

KVSPut returns 400

Verify that data was stored

KVSFactorLast / KVSFactorList returns empty results

SK-Based Query (
`giipApiSk2`
)