v1.0

Docs / API Reference

Integration Reference

Authentication, runtime protection, audit events, approvals, sessions, and supply-chain scanning endpoints.

Authentication

Send an API key in the X-API-Key header with every authenticated request.

curl

curl -H "X-API-Key: ag_live_your_key_here" \
  https://agentguard.gopluslabs.io/api/v1/scan

Bearer authentication is also documented: Authorization: Bearer ag_live_your_key_here.

Base URL

production

https://agentguard.gopluslabs.io

For local development, use http://localhost:3000. Endpoint paths remain unchanged.

Runtime Protection

The connected local guard evaluates high-risk actions before execution, caches policy for documented offline behavior, and syncs redacted audit events through the connected path.

Evaluate an actionPOST /api/v1/actions/evaluate

Get effective policyGET /api/v1/policies/effective

Sync redacted audit eventsPOST /api/v1/events/ingest

Review approvals and sessionsGET /api/v1/approvals

install

curl -fsSL https://agentguard.gopluslabs.io/install.sh | bash

Scan Agent Supply Chain

POST/api/v1/scanAuthentication required

Scan skill, tool, plugin, MCP server, or agent source before it enters the runtime.

Request body

Name	Type	Required	Description
`content`	`string`	Yes	Raw source code or manifest content
`ai`	`boolean`	No	Enable AI deep analysis; documented processing may add 5–30 seconds
`files`	object[]	No	Additional files in { name, content } format
`context`	`object`	No	Optional platform, version, and author context

Request example

curl

curl -X POST https://agentguard.gopluslabs.io/api/v1/scan \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ag_live_your_key_here" \
  -d '{
    "content": "import os; api_key = os.environ[SECRET]",
    "context": { "platform": "langchain", "version": "1.0.0" }
  }'

Response · 200 OK

json

{ "scanId": "scan_a1b2c3d4e5f6", "riskScore": 9.2, "riskLevel": "CRITICAL", "verdict": "REJECT", "processingMs": 142 }

Scan by URL

POST/api/v1/scan-urlAuthentication required

Fetch and scan a GitHub repository, registry package, or public raw file URL.

Name	Type	Required	Description
`url`	`string`	Yes	URL for agent source or manifest content
`type`	`string`	Yes	github, clawhub, or raw
`ai`	`boolean`	No	Enable AI deep analysis

curl

curl -X POST https://agentguard.gopluslabs.io/api/v1/scan-url \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ag_live_your_key_here" \
  -d '{ "url": "https://github.com/user/repo", "type": "github", "ai": true }'

The response follows the POST /api/v1/scan format.

Scan a Registry

POST/api/v1/scan-registryAuthentication required

Start an asynchronous batch scan for packages in a supported registry.

The current public reference marks this endpoint as requiring Pro access or above. Commercial availability must be confirmed before launch.

Name	Type	Required	Description
`registry`	`string`	Yes	npm, pypi, clawhub, or huggingface
`limit`	`number`	No	Maximum packages; documented range 10–100
`offset`	`number`	No	Registry pagination offset
`filter`	`object`	No	Keyword, author, downloads, or category filter

curl

curl -X POST https://agentguard.gopluslabs.io/api/v1/scan-registry \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ag_live_your_key_here" \
  -d '{ "registry": "npm", "limit": 20, "offset": 0 }'

202 Accepted

{ "batchId": "batch_x9y8z7w6v5", "status": "processing", "totalPackages": 20, "statusUrl": "/api/v1/report/batch_x9y8z7w6v5" }

Get a Scan Report

GET/api/v1/report/:scanIdAuthentication required

Retrieve the complete report for a finished supply-chain scan.

Name	Type	Required	Location	Description
`scanId`	`string`	Yes	path	Unique ID returned by a scan endpoint

curl

curl -H "X-API-Key: ag_live_your_key_here" \
  https://agentguard.gopluslabs.io/api/v1/report/scan_a1b2c3d4e5f6

Service Status

GET/api/v1/statusNo authentication

Return current API status, version, active detectors, and uptime.

curl

curl https://agentguard.gopluslabs.io/api/v1/status

200 OK

{ "status": "operational", "version": "1.0.0", "uptimeSeconds": 864000 }

Rate Limits

The public API reference documents a sliding-window limit applied per API key.

Tier	Protected actions / month	Requests / minute	API keys
`Free`	`100`	5	1
`Pro`	5,000	50	5
`Enterprise`	`Unlimited`	200	20

Treat these values as current documentation evidence. Reconfirm plan names, quotas, and commercial terms before publication.

response headers

X-RateLimit-Limit: 50
X-RateLimit-Remaining: 47
X-RateLimit-Reset: 1740600000

Error Codes

All error responses use standard HTTP status codes and a consistent machine-readable format.

HTTP	Code	Description
`400`	`VALIDATION_ERROR`	Invalid request parameters
`401`	`AUTHENTICATION_ERROR`	Invalid or missing API key
`402`	`QUOTA_EXCEEDED`	Monthly protection quota exceeded
`403`	`FEATURE_NOT_AVAILABLE`	Feature requires a different access tier
`404`	`NOT_FOUND`	Resource not found
`429`	`RATE_LIMIT_EXCEEDED`	Rate limit exceeded
`500`	`INTERNAL_ERROR`	Server error

error response

{ "error": { "code": "VALIDATION_ERROR", "message": "Request body must include a content field.", "details": { "field": "content", "reason": "required" } }