giip
SES Proposal
4 min read

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), and auth_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.

QueryTypeReqDescription
csnintList mode: all targets of this CSN
dueboolDue mode: targets due for a check now (scheduler)
limitintDue-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).

FieldTypeReqDescription
target_idintOmit to create; pass to update
csnint✅Project number; must match key scope
target_typestringOne of slack_workspace, slack_channel, email_mailbox, web_url, github_repo, custom
target_refstringNon-secret identifier only (channel id, URL, repo, ...)
display_namestringHuman-readable name
check_instructionstringWhat the agent should check
interval_minintCheck interval in minutes
report_routestringWhere to report findings
auth_methodstringOne of connector, browser_session, human_only, delegated_agent, none_public
auth_statusstringOne of unknown, connected, needs_user_auth, failed
auth_notestringMethod memo only — no secret values
enabledboolWhether 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.

FieldTypeReqDescription
csnint✅Project number
target_idint✅Target that was checked
last_resultstringResult of the run
watermarkstringProgress marker for the next run
auth_statusstringUpdated reachability status
auth_notestringMethod memo only — no secret values

Response: { "ok": true }

4. Delete — DELETE

Deletes a single check target.

QueryTypeReqDescription
csnint✅Project number
target_idint✅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-key is a project-scoped SK. Never print or log it. A key can only read/write targets within its own csn.

Troubleshooting

SymptomCauseFix
401 / 403Missing or wrong x-api-key, or a key for a different CSNUse the SK of the target's CSN
POST does not save my credentialBy design — credential values are never storedStore only non-secret metadata (auth_method/auth_status/auth_note)
target_id not updatedOmitted target_id on POST creates a new targetPass target_id to update an existing target
Empty due listNo target is due yet, or enabled is falseCheck 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