AgentTrust Docs

Overview

The AgentTrust Edge Gateway exposes a REST API for runtime validation, audit, policy management, analytics, and operations. Base URL defaults to http://localhost:8000 (full edge) or http://localhost:8765 (embedded).

Why It Matters

Direct HTTP integration enables non-Python services, n8n workflows, and custom dashboards to use the same governance pipeline as the SDK.

Prerequisites

Running gateway (embedded, Compose, or K8s)
API key or JWT token (when AUTH_ENABLED=true)

Step-by-Step Guide

Authentication

X-AgentTrust-Token: at_team_your_key

Or Bearer JWT:

Authorization: Bearer <jwt>

Token validation: GET /v1/auth/check

Base conventions

All runtime APIs under /v1/
JSON request/response bodies
OpenAPI docs at GET /docs
Prometheus metrics at GET /metrics
Health check at GET /health

Primary endpoints

Method	Path	Purpose
POST	`/v1/runtime/validate`	Primary — full governance pipeline
POST	`/v1/runtime/decision/{envelope_id}`	Re-run decision on stored envelope
GET	`/v1/audit/executions`	List audit records
GET	`/v1/audit/executions/{id}`	Get execution detail
GET	`/v1/audit/chain/verify`	Verify hash chain integrity
DELETE	`/v1/audit/executions/{id}/pii`	GDPR PII erasure
GET	`/v1/review/queue`	Human review queue
POST	`/v1/policy/evaluate`	Policy evaluation
POST	`/v1/certify/agent`	Agent certification
GET	`/v1/analytics/*`	Fleet analytics
GET	`/v1/alerts/*`	Alert engine
GET	`/v1/reports/*`	Compliance reports
GET	`/v1/team/*`	Team management
GET/POST	`/v1/sso/*`	SAML SSO (Enterprise)

Rate limits

Default: 60 requests/minute per agent_id (configurable via RATE_LIMIT_PER_MINUTE).

Examples

Health check:

curl http://localhost:8000/health

Auth check:

curl -H "X-AgentTrust-Token: $AGENTRUST_KEY" http://localhost:8000/v1/auth/check

Best Practices

Use SDK clients when possible (handle retries, failure modes, version negotiation)
Set agent_id consistently for rate limit and analytics grouping
Poll /health for load balancer health checks (not /v1/health)

Common Mistakes

Using /v1/health (does not exist — use /health)
Omitting auth header when AUTH_ENABLED=true
Sending unstructured string as output (must be JSON object)

Troubleshooting

See Errors and Troubleshooting.

API Reference