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

The Edge gateway's auth middleware reads exactly one header:

X-AgentTrust-Token: at_team_your_key

Authorization: Bearer <jwt> alone will not authenticate you. The gateway never inspects the Authorization header — a direct HTTP caller that sends only a bearer token gets 401 whenever AUTH_ENABLED=true. Put your JWT in X-AgentTrust-Token. (The Python SDK sends both headers, which is why SDK users never hit this.)

The embedded gateway is the opposite: it reads only Authorization: Bearer.

Token validation: GET /v1/auth/check

Base conventions

All runtime APIs under /v1/
JSON request/response bodies
Interactive OpenAPI docs at GET /docs, raw schema at GET /openapi.json — both disabled when AGENTRUST_ENV=production
Prometheus metrics at GET /metrics
Health check at GET /health

Primary endpoints

Method	Path	Purpose
POST	`/v1/runtime/pre-check`	Gate — "can we call this?", before execution
POST	`/v1/runtime/post-check`	Gate — "is this output safe to release?", after execution
POST	`/v1/runtime/validate`	Single-shot full pipeline, after execution
GET/POST	`/v1/runtime/kill-switch`	Read or set the global kill switch
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

Rate limiting is a sliding window keyed on agent_id, active only when RATE_LIMIT_ENABLED=true (the default outside development / dev / test).

Scope	Keyed on	Default limit
`POST /v1/runtime/validate`	`X-Agent-ID` header	70 req/min (60 rate + 10 burst)
`POST /v1/invoicepay/payments`	`X-Agent-ID` header	70 req/min (60 rate + 10 burst)
`/v1/auth/*`	client IP	20 req/min
Everything else	—	Unthrottled

The limiter keys on a header, not the body

The bucket comes from the X-Agent-ID request header, not the agent_id field in the JSON body. A direct HTTP caller that sets only the body field lands in a single shared "unknown" bucket alongside every other such caller. Send X-Agent-ID to get per-agent limits.

The effective threshold is requests_per_minute + burst, so the shipped default cuts off at 70, not 60. Per-agent overrides live in gateway/config/rate_limits.yaml (default, window_seconds, and glob-matched agent_overrides — e.g. payment-* is 30+5). Exceeding the limit returns 429 with Retry-After and X-RateLimit-Agent headers.

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