Server API Reference (v1.5)

Detailed API specifications for querying server asset information managed on the GIIP platform.

🔌 Go to Server List Feature →

📋 Overview

Using the Server API, you can check the physical and logical status of servers registered in your inventory.

🔐 Authentication (implementation-based, verified 2026-08-20 for giip #1277)

The only endpoint verified to actually work is LsvrDetail, called through the giipApiSk2 generic SP wrapper. This wrapper authenticates only through a POST body field, not an HTTP header.

• Endpoint: POST https://giipfaw.azurewebsites.net/api/giipApiSk2
• Content-Type: application/x-www-form-urlencoded
• Fields:
  • text: [Command name] [parameter name...]
  • token: [Your_SK] — the SK must be passed in this field, never inside text or jsondata
  • jsondata: parameter value(s) (format differs per command — see "2. LsvrDetail" below)
• ⚠️ A direct read of giipfaw/giipApiSk2/run.ps1 (2026-08-20) shows this endpoint parses no HTTP headers at all. Headers such as x-giip-ak are silently ignored, and the Azure Function itself is deployed with authLevel: anonymous, so no Function Key (?code=) is required either. Authentication is entirely driven by the token field above.

⚠️ About the old api.giip.io / x-giip-ak description

The https://api.giip.io/v3 host and x-giip-ak header previously documented here were searched for across the entire codebase (giipfaw Azure Functions, giipv3 source) and confirmed to not exist anywhere in the implementation (zero matches). The same example text was found copy-pasted across several other API guide docs, strongly suggesting it was a template placeholder rather than a real endpoint. Do not use it in production. Use the verified endpoint under "Authentication" above instead.

🔍 Endpoints

Single-Server Detail Lookup (LsvrDetail) — verified working (giip #1277)

• Command: text=LsvrDetail
• Description: Returns detail for a single server identified by LSSN (internal server sequence number). Internally calls pApiLSVRDetailbySk(@sk, @lssn bigint, @jsondata=NULL) → pLSvrDescOptbyAT.
• Request example:

  POST https://giipfaw.azurewebsites.net/api/giipApiSk2
  Content-Type: application/x-www-form-urlencoded
  
  text=LsvrDetail&token={SK}&jsondata=71289
  

  (71289 is the target server's LSSN)
• Response example (lssn=71289):

  { "data": [ { "LSsn": 71289, "LSHostname": "shinsema0104", "CSn": 70418, "CGCode": "smtodr-group", "lsRegdt": "2026-...", "LSLastHeartbeat": null } ] }

• 🚨 jsondata must be a raw number string only — wrapping it in an object fails:
  • ✅ Works: jsondata=71289
  • ❌ Fails: jsondata={"lssn":71289}, {"id":71289}, {"isn":71289}, etc. — every key wrapping produces Error converting data type nvarchar to bigint.
  • Root cause: Since text is the single word LsvrDetail with no trailing parameter name, run.ps1 routes this call through its "single command, no parameter name" path. That path does not extract individual keys from jsondata — instead it escapes the entire jsondata string and appends it verbatim as a string literal for the SP's second positional argument (@lssn bigint), via giipApiSk2's auto jsondata-append logic (labeled ISN 161 in run.ps1). If that literal is a bare number like 71289, SQL Server's implicit nvarchar→bigint conversion succeeds; if it contains braces like {"lssn":71289}, the conversion fails.

🛠️ Usage Example (Shell Script, verified working)

# Fetch detail for server LSSN 71289
curl -X POST "https://giipfaw.azurewebsites.net/api/giipApiSk2" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     --data-urlencode "text=LsvrDetail" \
     --data-urlencode "token=YOUR_SK" \
     --data-urlencode "jsondata=71289"

🛡️ Using Sk3 (High-fidelity Logging)

For core infrastructure asset management tasks, such as registering new servers or verifying detailed information, we recommend the giipApiSk3 endpoint to ensure task integrity and for detailed audit logs.

• Endpoint: https://giipfaw.azurewebsites.net/api/giipApiSk3
• Advantages: If a server registration fails, it immediately records the caller's detailed environment information (IP, UA) and StackTrace, allowing for rapid analysis of agent integration issues or configuration errors.
• Usage Tip: By utilizing the text command and the jsondata parameter substitution feature, you can stably reflect server usage or complex configuration values onto the platform without data loss.

Troubleshooting

Symptom	Cause	Resolution
LsvrDetail query fails with Error converting data type nvarchar to bigint	jsondata was wrapped in an object like {"lssn":71289} — since text=LsvrDetail has no parameter name, the entire jsondata string is assigned as-is to the @lssn bigint argument	Pass only the raw LSSN number in jsondata (e.g., jsondata=71289); never wrap it in an object
LsvrDetail query returns an auth error	Missing/incorrect token field in the POST body, or an SK that has been deactivated (reissued/rotated). Headers such as x-giip-ak are not used by this endpoint at all — setting them has no effect.	Verify the POST body's token field carries a currently valid SK.
LsvrDetail returns an empty result	A non-existent LSSN was used	Retry with a valid LSSN

🚫 Non-Working Commands (giip #1281)

The following commands have no corresponding SP in the giipApiSk2 dispatcher and do not work. Use the UI instead.

Command	Cause	Alternative
LSVRList <CSN>	pApiLSVRListbySk SP does not exist in giipdb	Use the Server List page
LSvrPut '<lsUsage>', <CSN>	SK-based pApiLSvrPutbySk SP does not exist (only AK-based pApiLSvrPutbyAK exists, not callable via giipApiSk2)	Use the Server List page

---

Version: 1.5 Last Updated: 2026-08-20 Source: giipv3/public/help/api-server.en.md

v1.5 Changelog (2026-08-20, giip #1281): Removed non-functional LSVRList and LSvrPut from API Details; added "Non-Working Commands" table with UI alternatives. v1.4 Changelog (2026-08-20, giip #1277): Fixed a documentation/implementation mismatch discovered from a real-world report by an external user (smartorder-works, csn 70418).

---

Related Documents:

• API Result Codes Guide (RstVal)