API Reference Overview (v1.2)

Guide to common API specifications and authentication methods for controlling and monitoring GIIP platform microservices and database resources.

📋 Overview

The GIIP API follows RESTful architecture principles, processing requests and returning responses in JSON format. All APIs are accessible only via the HTTPS protocol for security, and valid Access and Secret Keys are required for successful function calls.

🔐 Authentication

The following authentication information must be included in all API request headers.

Header Key	Description
x-giip-ak	Access Key issued by the GIIP administrator
x-giip-sk	Secret Key issued by the GIIP administrator

[!IMPORTANT] The Secret Key must not be leaked to the outside and should be securely managed on the server side to avoid direct exposure in client-side JavaScript (JS) code.

Shared AK/SK vocabulary

Across GIIP, credentials break down into three concrete kinds (as of 2026-08-20, based on code review + live testing documented in Issue & Task API):

Type	Backing store	Issued per	Scope
Project SK	tSecretKey.SKey	One per project (csn)	That csn only — a shared key, the caller isn't individually identifiable
User-level static key	tCorpUser.uSecretKey	One per user (usn)	That user's own csn memberships (every csn if the user is an admin)
Login-session AK	tUserLogin.AccToken	Freshly issued per login, expires after 24 hours	Same permissions as the logged-in user

⚠️ The concrete header name and delivery method differ per endpoint. The x-giip-ak/x-giip-sk headers above are a general convention used by several API groups, but the Issue Management API (/api/giipIssues, /api/giipIssueComments) and the CatQuest API pass either an AK or an SK through a single x-api-key header (or Authorization: Bearer) — they do not use separate x-giip-ak/x-giip-sk header names (verified live, 2026-08-20). Before calling any specific API, always check its own doc (Issue & Task API, CatQuest Data API, etc.) for the exact header name and delivery method. The table on this page shows the kinds of credentials GIIP uses overall — it does not mean every API shares one header convention.

📡 Common Response Format

All GIIP APIs provide a consistent response format to facilitate client-side processing.

{
  "RstVal": 0,
  "RstMsg": "Success",
  "Data": { ... }
}

• RstVal: Success status (0: Success, otherwise: Error)
• RstMsg: Success message (Includes detailed reason on error)
• Data: Data body returned upon success

🚀 Request Format

All API requests are POSTed as application/x-www-form-urlencoded following the Azure Function call specification.

Key Form Data

Field	Description
text	Command string to execute
user_id	Calling user ID
token	Session token
usertoken	Session token used for actual integration

---

🚀 Guides by API Group

Refer to the individual guides below for detailed API specifications by field.

1. Server Management API: Infrastructure asset query and command execution
2. Database API: DB performance and query statistics
3. Issue Management API: Failure alarms and status updates
4. Cost Analysis API: Cloud usage and cost prediction
5. Project/User API: Permissions and organization management
6. Monitoring Data Query API: Real-time CPU/MEM/Disk metrics, performance history, and process list
7. Network Security Policy API: Firewall rule query, IP allow/block, and policy batch deployment
8. Network Topology (Net3D) API: Infrastructure connection data collection and transmission specifications (netinv, netstat, db_connections)
9. System Management API: Remote command execution, agent control, and server tag management
10. KVS (Key-Value Store) API: Factor data query (KVSFactorLast, KVSFactorList)
11. Vercel Management API: Vercel configuration management and deployment history query
12. GitHub Actions Management API: GitHub repository integration and workflow history query
13. Email Server Management API: SMTP server configuration and test sending (Admin only)
14. Sk3 (High-fidelity Logging) API: High-fidelity logging bridge for agent transmission error detection and integrity verification
15. Common Response & Result Codes (RstVal): Standard result codes guide based on the tDefRst table

---

🛠️ Common Error Codes

• 401 Unauthorized: Authentication information is invalid or expired
• 403 Forbidden: No permission to call the specified API (Includes IP-based access control)
• 429 Too Many Requests: Rate limit exceeded
• 500 Internal Server Error: Internal server error or temporary failure occurred

📖 Developer Notes

• Endpoint Caller: src/lib/lsvrUtils.ts
• Session Management: Reference sessionStorage's user_id, token, csn, cname, etc.
• All integrations default to HTTPS.

🔧 Troubleshooting

Symptom	Cause	Resolution
A 401 Unauthorized is returned	The Access Key/Secret Key is expired or invalid	Re-check the x-giip-ak/x-giip-sk header values and, if needed, ask the administrator to re-issue the keys
A 403 Forbidden is returned	No permission to call the API, or blocked by IP-based access control	Verify the account permissions and whether the source IP is allowed
The RstVal is not 0 but the cause is unclear	The meaning of the standard result code was not checked	Check RstMsg and look up the code in the API Result Codes Guide
The request is not processed or the text command is ignored	The request is not application/x-www-form-urlencoded, or the text/user_id/token fields are missing	Send the form data in the correct format with the required fields per the specification

---

Related Documents:

• Issue & Task API (a working example supporting both AK and SK, with detailed 401 root causes)
• CatQuest Data API (a working read-only example)

---

Version: 1.3 Last Updated: 2026-08-20 Markdown Source: giipv3/public/help/api-reference.en.md

v1.3 changelog (2026-08-20, giip #1280): Added the "Shared AK/SK vocabulary" section, organizing project SK / user-level static key / login-session AK by their backing table. Clarified that the Issue Management API and CatQuest API use a single x-api-key header rather than the x-giip-ak/x-giip-sk convention on this page, and pointed readers to each API's own doc for the exact header name (resolves the inconsistency across the three documents).