System Management API Reference

Learn about the system-level automation APIs for sending commands to servers or controlling agent status.

📋 Overview

This API module provides endpoints to directly issue commands to individual servers through GIIP agents or to manage server metadata (such as tags).

🔐 Authentication & Headers

All requests must include common authentication headers.

• Header: x-giip-ak: [Your Access Key]
• Header: x-giip-sk: [Your Secret Key]

🚀 Key API Endpoints

1. Run Remote Command

• URL: POST /api/system/command/run
• Description: Executes a specific Shell script or command on the designated server.
• Request Body:

{
  "serverIsn": 456,
  "command": "ls -al /var/log",
  "timeout": 30
}

2. Agent Control

• URL: POST /api/system/agent/control
• Description: Remotely restarts the GIIP agent installed on the server or synchronizes settings.
• Request Body:

{
  "serverIsn": 456,
  "action": "restart"
}

3. Manage Server Tags

• URL: POST /api/system/server/tags
• Description: Updates the list of tags used to categorize servers.
• Request Body:

{
  "serverIsn": 456,
  "tags": ["Production", "Web", "Region-KR"]
}

🔍 Response Data Example (Command Run)

{
  "RstVal": 0,
  "RstMsg": "Success",
  "Data": {
    "jobId": "JOB-10293",
    "output": "total 1024\ndrwxr-xr-x 2 root root ...",
    "exitCode": 0
  }
}

💡 Use Cases

• Automated Patch Management: Issue a bulk update command to all servers for a package where a vulnerability was discovered.
• Dynamic Resource Allocation: Automatically assign the purpose of newly created VMs and apply policies using the tag management API.

🛡️ Using Sk3 (High-fidelity Logging)

For sensitive system management tasks such as remote command execution (Run Remote Command) or agent control, we recommend the giipApiSk3 endpoint to ensure the integrity of your operations and for detailed execution history tracking.

• Endpoint: https://giipfaw.azurewebsites.net/api/giipApiSk3
• Advantages: If a command execution fails, it immediately records the caller's detailed environment information (IP, UA) and StackTrace, helping you quickly and clearly identify unauthorized requests or network failure situations.
• Usage Tip: By utilizing the jsondata substitution feature, you can safely manage complex shell command strings or tag information containing special characters without data loss.

🔧 Troubleshooting

Symptom	Cause	Solution
Request rejected with an authentication error	Missing or invalid x-giip-ak / x-giip-sk header	Include a valid Access Key and Secret Key in both headers and retry
Remote command does not run	Incorrect serverIsn or the target server's agent is offline	Verify the server identifier and restart the agent via the Agent Control API (action: restart)
RstVal in the response is not 0	Command execution failed or timeout was exceeded	Check RstMsg and Data.exitCode, and raise the timeout value if needed
Data loss when sending tags with special characters	The jsondata substitution feature was not used	Send via the jsondata field of the giipApiSk3 endpoint to prevent data loss

---

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

---

Related Documents:

• API Result Codes Guide (RstVal)