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)	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 is "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
`token`	✅	SK value (the `sk` field in `giipAgent.cfg`)
`text`	✅	Literal string: `KVSPut kType kKey kFactor kValue` (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 kValue 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 123456. 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 kValue" \
  --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 kValue"
    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 kValue" \
  --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 kValue",
    "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 123456:

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 123456:

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 kValue" \
  --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 kValue (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 kValue" \
  --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.

Troubleshooting

Symptom	Cause	Solution
KVSPut returns 401	SK was sent as a header, or the `token` value is incorrect	Pass the SK in the Body `token` field and verify the value
KVSPut returns 400	`text` differs from the literal `KVSPut kType kKey kFactor kValue`, or `jsondata` is not valid JSON	Send `text` as the exact literal string and serialize `jsondata` as valid JSON
Write fails or kKey error	`kKey` is not a numeric string (a hostname or UUID was used)	Use a numeric string such as `tLSvr.LSsn` for `kKey`
KVSFactorLast/List returns empty	No data recorded for that `kType`/`kKey`/`kFactor`, or wrong LSSN	Write with KVSPut first, then query, and verify the LSSN value

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)

← PreviousGraphify Data Ingestion API Next →Vercel Management API

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

Troubleshooting

SK-Based Query (`giipApiSk2`)