giipAgentCheckTarget API Reference
API for managing an agent's check targets — the things an agent periodically checks (a Slack channel, a mailbox, a web URL, a GitHub repo, ...). Credential values are never stored or returned; only non-secret metadata (auth method and status) is handled.
📋 Overview
giipAgentCheckTarget is a REST endpoint on the GIIP API. It exposes four operations on the check-target registry: list/due (GET), create or update (POST), record a run result (PUT), and delete (DELETE).
- Endpoint:
https://wapi.giipapps.net/api/giipAgentCheckTarget - Auth: header
x-api-key: <GIIP SK>— a project-scoped SK. The SK scopes you to a single CSN; you can only read and write that CSN's targets. - Content-Type (POST/PUT):
application/json - Isolation: every operation is scoped by
csn. You cannot reach another CSN's targets.
⚠️ No credentials are stored. This API intentionally holds no secret values. Target credential fields sent on POST are ignored and never persisted. Only non-secret metadata is kept:
auth_method(how the target is reached),auth_status(whether it is reachable), andauth_note(a method memo with no secret values).
🔍 Operations
1. List / due — GET
Lists a CSN's check targets, or the scheduler's due list.
| Query | Type | Req | Description |
|---|---|---|---|
csn | int | List mode: all targets of this CSN | |
due | bool | Due mode: targets due for a check now (scheduler) | |
limit | int | Due-mode cap (default 200) |
Response: { "ok": true, "targets": [ ... ], "count": <n> }
2. Create or update — POST
Creates a target (omit target_id) or updates one (pass target_id).
| Field | Type | Req | Description |
|---|---|---|---|
target_id | int | Omit to create; pass to update | |
csn | int | ✅ | Project number; must match key scope |
target_type | string | One of slack_workspace, slack_channel, email_mailbox, web_url, github_repo, custom | |
target_ref | string | Non-secret identifier only (channel id, URL, repo, ...) | |
display_name | string | Human-readable name | |
check_instruction | string | What the agent should check | |
interval_min | int | Check interval in minutes | |
report_route | string | Where to report findings | |
auth_method | string | One of connector, browser_session, human_only, delegated_agent, none_public | |
auth_status | string | One of unknown, connected, needs_user_auth, failed | |
auth_note | string | Method memo only — no secret values | |
enabled | bool | Whether the target is active |
Response: { "ok": true, "target_id": <id> }
Credential fields are ignored and never stored. Send only the non-secret metadata above.
3. Record a check result — PUT
Records the result of one check run (used by the scheduler). The server sets last_run_at.
| Field | Type | Req | Description |
|---|---|---|---|
csn | int | ✅ | Project number |
target_id | int | ✅ | Target that was checked |
last_result | string | Result of the run | |
watermark | string | Progress marker for the next run | |
auth_status | string | Updated reachability status | |
auth_note | string | Method memo only — no secret values |
Response: { "ok": true }
4. Delete — DELETE
Deletes a single check target.
| Query | Type | Req | Description |
|---|---|---|---|
csn | int | ✅ | Project number |
target_id | int | ✅ | Target to delete |
Response: { "ok": true }
🛠️ Examples (cURL)
# 1) List CSN 47's check targets
curl "https://wapi.giipapps.net/api/giipAgentCheckTarget?csn=47" \
-H "x-api-key: <YOUR_SK>"
# 2) Create a check target
curl -X POST "https://wapi.giipapps.net/api/giipAgentCheckTarget" \
-H "x-api-key: <YOUR_SK>" -H "Content-Type: application/json" \
-d '{"csn":47,"target_type":"web_url","target_ref":"https://example.com/status","display_name":"Status page","check_instruction":"Alert if not 200","interval_min":10,"auth_method":"none_public","enabled":true}'
# 3) Record a check run result
curl -X PUT "https://wapi.giipapps.net/api/giipAgentCheckTarget" \
-H "x-api-key: <YOUR_SK>" -H "Content-Type: application/json" \
-d '{"csn":47,"target_id":12,"last_result":"ok","watermark":"2026-11-15T02:00:00Z","auth_status":"connected"}'
# 4) Delete a check target
curl -X DELETE "https://wapi.giipapps.net/api/giipAgentCheckTarget?csn=47&target_id=12" \
-H "x-api-key: <YOUR_SK>"
The
x-api-keyis a project-scoped SK. Never print or log it. A key can only read/write targets within its owncsn.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| 401 / 403 | Missing or wrong x-api-key, or a key for a different CSN | Use the SK of the target's CSN |
| POST does not save my credential | By design — credential values are never stored | Store only non-secret metadata (auth_method/auth_status/auth_note) |
target_id not updated | Omitted target_id on POST creates a new target | Pass target_id to update an existing target |
| Empty due list | No target is due yet, or enabled is false | Check interval_min and enabled |
Metadata
- Source file:
giipv3/public/help/api-agent-check-target.en.md - raw source path:
/help/api-agent-check-target.en.md - OpenAPI source of truth:
giipv3/src/lib/openapiSpec.ts→/giipAgentCheckTarget - Related API:
giipfaw/giipAgentCheckTarget