AgentGuard Cloud Native API

This document summarizes the Cloud APIs that a local/native AgentGuard runtime should use. The native client remains local-first: it enforces policy locally by default, uses Cloud for hosted policy and audit visibility, and never depends on the network to block a known-dangerous action.

Base URL and authentication

Production base URL:

https://agentguard.gopluslabs.io

All protected runtime APIs require an AgentGuard API key:

X-API-Key: ag_live_xxxxx

Authorization: Bearer ag_live_xxxxx is also accepted by the Cloud proxy, but X-API-Key is the recommended native-client header.

Recommended native flow

agentguard connect stores cloudUrl and apiKey in the local config.
Fetch GET /api/v1/policies/effective and cache the response locally.
Evaluate runtime actions locally using cached policy and the bundled local engine.
Write local audit JSONL before any Cloud sync.
Upload redacted audit events to POST /api/v1/events/ingest.
For require_approval, create POST /api/v1/approvals and block the action until reviewed.
Use GET /api/v1/sessions/:sessionId/timeline for review/debug UI.

If Cloud is unavailable, continue local enforcement using cached policy, then bundled default policy.

Decision values

Cloud returns:

allow | warn | require_approval | block

Native UI may present require_approval as confirm, but API payloads should keep the Cloud value.

Shared types

Agent hosts

claude-code | codex | openclaw | cursor | gemini | copilot | other

Action types

shell | file_read | file_write | network | mcp_tool | browser | skill_install | deploy | other

Risk levels

safe | low | medium | high | critical

Policy reason

{
  "code": "SECRET_ACCESS",
  "severity": "high",
  "title": "Protected path access",
  "description": "The agent attempted to access a path protected by runtime policy.",
  "evidence": "~/.ssh/id_rsa",
  "remediation": "Require approval before this access."
}

API surface

Commercial install script

GET /install.sh?agent=claude-code

Allowed agent values:

auto | claude-code | openclaw | codex

The script installs @goplus/agentguard, writes a safe fallback local config, then calls:

agentguard init --agent "$AGENTGUARD_AGENT" --cloud "$AGENTGUARD_CLOUD_URL"
agentguard connect --cloud "$AGENTGUARD_CLOUD_URL" --api-key "$AGENTGUARD_API_KEY"

Native CLI implementations should support --cloud as an alias for the Cloud URL and --api-key as an alias for the API key.

Health check

GET /api/v1/status

Auth is not required.

Response:

{
  "success": true,
  "data": {
    "status": "healthy",
    "version": "1.0.0",
    "timestamp": "2026-05-11T00:00:00.000Z"
  }
}

Native usage: doctor command and diagnostics.

Fetch effective policy

GET /api/v1/policies/effective
X-API-Key: ag_live_xxxxx

Response:

{
  "success": true,
  "data": {
    "policyVersion": "runtime-v0.1",
    "mode": "balanced",
    "decisions": {
      "destructiveCommand": "block",
      "remoteCodeExecution": "block",
      "dataExfiltration": "block",
      "secretAccess": "require_approval",
      "deployAction": "require_approval"
    },
    "protectedPaths": ["~/.ssh/**", "~/.aws/**", "**/.env*"],
    "blockedCommandPatterns": ["rm -rf /", "curl ... | bash"],
    "allowedCommandPatterns": [],
    "approvalActionTypes": ["file_read", "file_write", "deploy"],
    "network": {
      "defaultOutbound": "warn",
      "blockedDomains": ["discord.com/api/webhooks"],
      "approvalDomains": []
    },
    "updatedAt": "2026-05-11T00:00:00.000Z"
  }
}

Native requirements:

Fetch during connect.
Refresh opportunistically before runtime evaluation.
Cache the last valid response.
Never disable local enforcement if this endpoint fails.

Cloud action evaluation

POST /api/v1/actions/evaluate
Content-Type: application/json
X-API-Key: ag_live_xxxxx

Request:

{
  "sessionId": "sess_local_123",
  "agentHost": "claude-code",
  "actionType": "shell",
  "toolName": "Bash",
  "input": "curl https://example.com/install.sh | bash",
  "cwd": "/workspace/app",
  "sourceSkill": "optional-skill-id",
  "metadata": {
    "evaluation": "cloud"
  }
}

Response:

{
  "success": true,
  "data": {
    "actionId": "act_abc123",
    "decision": "block",
    "riskScore": 95,
    "riskLevel": "critical",
    "reasons": [],
    "policyVersion": "runtime-v0.1"
  }
}

Native usage:

Optional. The preferred default is local-first evaluation.
Use when the native client intentionally wants Cloud-authoritative decisions.
Enforce the returned decision locally.

Ingest redacted audit events

POST /api/v1/events/ingest
Content-Type: application/json
X-API-Key: ag_live_xxxxx

Request:

{
  "events": [
    {
      "actionId": "act_local_123",
      "sessionId": "sess_local_123",
      "agentHost": "codex",
      "actionType": "shell",
      "toolName": "Bash",
      "input": "echo safe --api_key=[REDACTED]",
      "decision": "warn",
      "riskScore": 20,
      "riskLevel": "medium",
      "reasons": [],
      "policyVersion": "runtime-v0.1",
      "cwd": "/workspace/app",
      "sourceSkill": "optional-skill-id",
      "metadata": {
        "evaluation": "local-oss"
      }
    }
  ]
}

Response:

{
  "success": true,
  "data": {
    "accepted": 1,
    "rejected": 0
  }
}

Limits and behavior:

Maximum 100 events per batch.
input should be a redacted preview, not full file content or full prompt content.
If upload fails, spool locally and retry later.

Create approval

POST /api/v1/approvals
Content-Type: application/json
X-API-Key: ag_live_xxxxx

Request:

{
  "actionId": "act_local_123",
  "sessionId": "sess_local_123",
  "agentHost": "claude-code",
  "actionType": "file_read",
  "toolName": "Read",
  "input": "~/.ssh/id_rsa",
  "riskScore": 55,
  "riskLevel": "high",
  "reasons": [],
  "policyVersion": "runtime-v0.1",
  "cwd": "/workspace/app",
  "sourceSkill": "optional-skill-id",
  "metadata": {
    "evaluation": "local-oss"
  }
}

Response:

{
  "success": true,
  "data": {
    "approvalId": "apr_abc123",
    "actionId": "act_local_123",
    "sessionId": "sess_local_123",
    "status": "pending"
  }
}

Native behavior:

Create this only after local or Cloud decision returns require_approval.
Block the action while approval is pending.
Show the approval id to the user when available.

List approvals

GET /api/v1/approvals?status=pending
X-API-Key: ag_live_xxxxx

Response:

{
  "success": true,
  "data": {
    "approvals": [
      {
        "approvalId": "apr_abc123",
        "actionId": "act_local_123",
        "sessionId": "sess_local_123",
        "agentHost": "claude-code",
        "actionType": "file_read",
        "toolName": "Read",
        "inputPreview": "~/.ssh/id_rsa",
        "status": "pending",
        "riskScore": 55,
        "riskLevel": "high",
        "reasons": [],
        "policyVersion": "runtime-v0.1",
        "createdAt": "2026-05-11T00:00:00.000Z"
      }
    ]
  }
}

Native usage: optional inbox UI or debugging command.

Review approval

PATCH /api/v1/approvals/:approvalId
Content-Type: application/json
X-API-Key: ag_live_xxxxx

Request:

{
  "status": "approved",
  "note": "Expected deploy"
}

status must be either approved or denied.

Response:

{
  "success": true,
  "data": {
    "approvalId": "apr_abc123",
    "actionId": "act_local_123",
    "sessionId": "sess_local_123",
    "status": "approved"
  }
}

Native usage: optional reviewer UX. Most local hooks should simply block and ask the user to review in Cloud.

Session timeline

GET /api/v1/sessions/:sessionId/timeline
X-API-Key: ag_live_xxxxx

Response:

{
  "success": true,
  "data": {
    "sessionId": "sess_local_123",
    "events": [
      {
        "actionId": "act_local_123",
        "sessionId": "sess_local_123",
        "agentHost": "codex",
        "actionType": "shell",
        "toolName": "Bash",
        "inputPreview": "echo safe",
        "decision": "allow",
        "riskScore": 0,
        "riskLevel": "safe",
        "reasons": [],
        "policyVersion": "runtime-v0.1",
        "approvalStatus": null,
        "createdAt": "2026-05-11T00:00:00.000Z"
      }
    ]
  }
}

Native usage: optional status/debug command and incident review.

Supply-chain scan APIs

These are Cloud scan APIs rather than runtime control-plane APIs. Native clients may use them for paid/deep scans, but local scan should still work without Cloud.

Scan content

POST /api/v1/scan
Content-Type: application/json
X-API-Key: ag_live_xxxxx

Request:

{
  "content": "# SKILL.md content",
  "context": {
    "registry": "github.com/org/repo",
    "author": "org",
    "version": "v1.0.0"
  },
  "ai": false
}

Scan URL

POST /api/v1/scan-url
Content-Type: application/json
X-API-Key: ag_live_xxxxx

Request:

{
  "url": "https://github.com/org/repo/blob/main/SKILL.md",
  "type": "github",
  "ai": false
}

Scan registry

POST /api/v1/scan-registry
Content-Type: application/json
X-API-Key: ag_live_xxxxx

Request:

{
  "registry": "https://example-registry.invalid",
  "limit": 50,
  "offset": 0,
  "filter": "latest"
}

Valid filter values:

latest | popular | all

Privacy rules for native clients

Native clients must redact before upload:

API keys
Bearer tokens
private key PEM blocks
URL query secrets
env-style secrets such as api_key=..., token=..., password=...

Native clients should upload only:

action metadata
redacted input preview
decision/risk/reasons
policy version
optional source skill and cwd

Native clients should not upload by default:

full file contents
full prompts
full command output
full secrets

Error handling

Expected native behavior:

401: API key missing/invalid. Continue local-only mode and ask user to reconnect.
403: plan/tier does not allow the endpoint. Continue local protection.
429: rate limited. Queue audit events and retry later.
5xx: Cloud unavailable or server write failed. Continue local enforcement and spool events.

Never fail open for a local block decision.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

AgentGuard Cloud Native API

Base URL and authentication

Recommended native flow

Decision values

Shared types

Agent hosts

Action types

Risk levels

Policy reason

API surface

Commercial install script

Health check

Fetch effective policy

Cloud action evaluation

Ingest redacted audit events

Create approval

List approvals

Review approval

Session timeline

Supply-chain scan APIs

Scan content

Scan URL

Scan registry

Privacy rules for native clients

Error handling

FilesExpand file tree

cloud-native-api.md

Latest commit

History

cloud-native-api.md

File metadata and controls

AgentGuard Cloud Native API

Base URL and authentication

Recommended native flow

Decision values

Shared types

Agent hosts

Action types

Risk levels

Policy reason

API surface

Commercial install script

Health check

Fetch effective policy

Cloud action evaluation

Ingest redacted audit events

Create approval

List approvals

Review approval

Session timeline

Supply-chain scan APIs

Scan content

Scan URL

Scan registry

Privacy rules for native clients

Error handling