Server API Reference

Detailed API specifications for querying server asset information and delivering control commands 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 and remotely execute commands or restart services via agents.

🔍 Key Endpoints

1. Retrieve Server List

Fetches information for all servers registered at the project or customer level.

• URL: GET /server/list
• Key Parameters:
  • prj_isn (Integer): Filter by specific Project
  • status (String): Filter by status such as Running, Stop, or Unknown
• Response Data: Hostname, IP address, OS type, CPU/Mem specs, etc.

2. Query Heartbeat & Real-time Status

Checks for survival signals and real-time load information from agents installed on servers.

• URL: GET /server/heartbeat
• Required Parameter: server_isn (Unique Server Number)
• Response Data: Last received time, Current CPU utilization, Available memory, etc.

3. Remote Command Execution (execCommand)

Delivers shell commands to specific servers and asynchronously receives results.

• URL: POST /server/command
• Payload:
  • server_isn: Target server number
  • command: Command to execute (e.g., systemctl restart nginx)
• Response: Returns a Command Receipt ID (cmd_isn) (Execution results are queried at /server/command/result)

🛠️ Usage Example (Shell Script)

# Check current CPU utilization of a specific server
curl -X GET "https://api.giip.io/v3/server/heartbeat?server_isn=123" \
     -H "x-giip-ak: YOUR_AK"

🛡️ 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
Server list/heartbeat query returns an auth error	Missing or invalid x-giip-ak header	Ensure a valid AK is sent in the request header.
GET /server/list returns an empty list	Wrong prj_isn filter or an overly narrow status filter	Verify the prj_isn value and relax the status filter (e.g., remove Running).
GET /server/heartbeat returns no data	Wrong server_isn or the agent has not reported yet	Use a valid server_isn and confirm the agent on the target server is running.
Remote command shows no result immediately	execCommand is asynchronous and only returns a receipt ID	Poll /server/command/result with the returned cmd_isn to fetch the result.

---

Version: 1.1 Last Updated: 2026-04-10 Source: giipv3/public/help/api-server.en.md

---

Related Documents:

• API Result Codes Guide (RstVal)