Issue Management API Reference

This document provides the technical specification for programmatically managing issues and error logs on the GIIP platform.

🔌 Go to Issue Management Feature →

📋 Overview

The Issue Management API is used by automation scripts or AI agents to retrieve and process server failures, error logs, and task statuses. It provides two primary methods of invocation.

---

🔐 Authentication

Every request must include a valid Secret Key (SK).

• Header: x-api-key: [Your_SK]
• Body: { "token": "[Your_SK]" } (for JSON requests)
• Query: ?token=[Your_SK]

---

Both paths below are fully functional. Use the dedicated REST endpoints (the path the giipv3 admin UI actually uses) for CRUD such as creating issues and comments; use the giipApiSk2 wrapper for direct SP calls.

🚀 Method 1: Dedicated Endpoint (REST API)

The most intuitive way to interact with issues. Auth via the x-api-key header, Content-Type application/json.

1. Create Issue (New)

• URL: POST /api/giipIssues — omit isn (or send 0) to INSERT a new issue; the new isn is returned.
• Body (JSON):

{ "title": "Title (required)", "content": "Body", "status": "PENDING",
  "csn": 47, "target_lssn": null, "agent_workflow": null }

• Success: { "isn": 577, "message": "Issue created", "success": true }

2. List Issues

• URL: GET /api/giipIssues
• Query Parameters:
  • status: (Optional) Issue status (READY, PENDING, DONE, etc.)
  • isn: (Optional) Specific issue serial number
• Response: { "issues": [...] }

3. Update Issue Status

• URL: PUT /api/giipIssues (POST also accepted)
• Body (JSON): { "isn": 7890, "status": "DONE" } → { "success": true }

4. Add Comment

• URL: POST /api/giipIssueComments
• Body (JSON): { "isn": 7890, "content": "Closed.", "author": "api-tester", "issuetype": "comment" } → { "success": true }

---

🚀 Method 2: Universal API Wrapper (giipApiSk2)

A powerful SK-based method that directly calls GIIP Stored Procedures. Highly recommended for AI agents. Listing, fetching, and status updates all work through this path.

• URL: POST /api/giipApiSk2
• Content-Type: application/x-www-form-urlencoded
• Fields:
  • token: [Your_SK] — pass the SK only in this field (never in text/jsondata)
  • text: [Command] [Params...]
  • jsondata: (Optional) JSON for value mapping, e.g. {} or {"isn":7890,"status":"DONE"}

⚠️ text rule (strict): List in text only the exact parameters the SP accepts, in order. The engine (run.ps1) handles auth (@sk) and jsondata automatically, so never list them. Over-listing exceeds the SP's argument count and triggers has too many arguments specified.

Common Command Examples (safe)

Feature	SP params (list in text)	text Example	Success
List Issues	status	GiipIssueList READY	data (issue array)
Get Details	isn	GiipIssueGet 7890	data[0] (one issue)
Dispatch (remote run)	isn	GiipIssueDispatch 7890	data[0].RstVal = 200

🚫 Do NOT use GiipIssuePut via Sk2 to change status (data-destruction risk). Sk2 GiipIssuePut maps to pApiGiipIssuePutbySK(@sk, @isn, @title, @content, @status, @csn) — a full overwrite (no coalesce). Calling GiipIssuePut 7890 DONE puts the 2nd value DONE into @title and the 3rd (jsondata) into @content, destroying the title and body. The response still shows RstVal:200 (a false success) even though the record is corrupted (verified 2026-07-09, task 20260708183049). To change only the status safely, use the dedicated REST PUT /api/giipIssues {isn, status}. Its pApiGiipIssuePutbyAK uses ISNULL(@title, title) to preserve the existing title/body — this is the path the giipv3 front end actually uses.

---

🔍 Response Standard

giipApiSk2 (SP wrapper) response — reads return records in data; SP actions (e.g. Dispatch) return RstVal = 200 on success:

{ "data": [ { "RstVal": 200, "Proc_MSG": "Dispatched", "isn": 7890 } ] }

List/Get commands return the issue records in the data array.

Dedicated REST endpoint response — success is success: true (no RstVal in the body):

{ "isn": 7890, "message": "Issue updated", "success": true }

ℹ️ Success check: The SP success code is RstVal = 200, not 0; failures return 400/401/403/404 (K-Layer CLAIM-006). Dedicated endpoints return a success boolean instead of RstVal.

---

⚠️ Important Notes

• 500 Internal Server Error: If you encounter "The term 'if' is not recognized", it is a PowerShell compatibility issue on the server. Ensure the latest patch (v1.0.1+) is applied.
• CSN Restriction: To access issues belonging to specific project groups, the API key must have the appropriate permissions for those projects.

Troubleshooting

Symptom	Cause	Solution
Authentication failure / 401	Missing or invalid Secret Key	Include a valid SK via the x-api-key header or token parameter
Command ignored or empty result	Malformed text parameter (command and params not separated)	Follow the [Command] [Params] format, e.g. GiipIssueList READY
... has too many arguments specified	Too many params listed in text	List only the SP's exact params. @sk and jsondata are handled by the engine — never list them
Title/body destroyed (became DONE/{}) after a status change	Used Sk2 GiipIssuePut (a full-overwrite SP) to change status	Change status via the dedicated REST PUT /api/giipIssues {isn,status} (Method 1). Never use Sk2 GiipIssuePut for writes
Response data[0].RstVal is not 200	SP execution error or invalid isn	Check Proc_MSG, then see the API Result Codes guide. Success is 200, not 0
Issues not returned for a project group	The API key lacks permission for that CSN/project	Grant the key the appropriate project permissions

---

Version: 1.3 Last Updated: 2026-07-09 Source File: giipv3/public/help/giip-issue-api.en.md

v1.3 changelog (2026-07-09, task 20260708183049): Reconciled against the live production API (giipv3 front · giipApiSk2 · SP sources). ① Added a Sk2 write-path danger warning: Sk2 GiipIssuePut maps to the full-overwrite SP pApiGiipIssuePutbySK(@sk,@isn,@title,@content,@status,@csn), so GiipIssuePut 7890 DONE destroys the title/body (returning a false RstVal:200). Verified live (issues 577/578 corrupted, then restored). Writes (create/status/comment) now steer to the dedicated REST endpoints; Sk2 is documented for reads and actions only. (The old report's "too many arguments / incompatible" note was a partial observation; the real hazard is that the SP is a full overwrite.) ② Success code is RstVal = 200 (not 0) — corrected response example and troubleshooting table. ③ Added the issue-creation procedure (POST /api/giipIssues, omit isn) and safe status change (PUT /api/giipIssues {isn,status}, ISNULL-preserving).