API Overview - TraceCtrl

Base URL

All endpoints are prefixed with /api/v1.

http://localhost:8000/api/v1

Authentication

The Engine API currently does not require authentication. In production deployments, secure the API behind a reverse proxy or API gateway.

Endpoints

System

Method	Endpoint	Description
`GET`	`/health`	Health check
`GET`	`/projects`	List all service names (for project selector)

Topology

Method	Endpoint	Description
`GET`	`/topology/graph`	Full topology graph (supports `?service=`)
`GET`	`/topology/agents/{agent_id}`	Single agent detail

Agents

Method	Endpoint	Description
`GET`	`/agents`	Agent inventory (supports `?service=`)
`GET`	`/agents/{agent_id}/tools`	Tools used by an agent
`GET`	`/agents/{agent_id}/guardrails`	Guardrails for an agent

Sessions

Method	Endpoint	Description
`GET`	`/sessions`	Session list (supports `?service=`)
`GET`	`/sessions/latest-spans`	Spans from the most recent trace
`GET`	`/sessions/{trace_id}/spans`	Spans for a trace (supports `?extra=`)

Guardrails

Method	Endpoint	Description
`GET`	`/guardrails`	Guardrail registry (supports `?agent_id=`)
`GET`	`/guardrails/invocations`	Recent evaluation spans
`GET`	`/guardrails/protector-config`	Protector Plus config (redacted)
`PUT`	`/guardrails/protector-config`	Upsert Protector Plus config
`POST`	`/guardrails/protector-test`	Health-check the Protector Plus endpoint
`GET`	`/guardrails/protector-config/sdk`	Full config for the SDK

Violations

Method	Endpoint	Description
`GET`	`/violations`	List violations (`limit`, `agent_id`, `severity`)
`GET`	`/violations/recent`	Recent violations (`limit`)
`GET`	`/violations/stream`	SSE stream of new violations

Scans

Method	Endpoint	Description
`POST`	`/scans`	Upload scan results from a CLI
`GET`	`/scans`	List all stored scans
`GET`	`/scans/latest`	Latest scan with drift detection
`GET`	`/scans/{scan_id}`	Results for a specific scan
`POST`	`/scan/validate-path`	Validate an OpenClaw workspace path
`POST`	`/scan/trigger`	Trigger an engine-side scan
`GET`	`/scan/status/{scan_id}`	Poll a triggered scan
`POST`	`/scan/fix`	Apply automated remediations

Risk

Method	Endpoint	Description
`GET`	`/risk/agents`	All agents with inventory data
`GET`	`/risk/summary`	System-wide risk summary
`GET`	`/risk/attack-paths`	Ranked attack paths from TAGAAI rules
`GET`	`/risk/agent-scores`	Per-agent risk scores

Attack Graph

Method	Endpoint	Description
`GET`	`/attack-graph/paths`	Detailed paths for the findings panel
`GET`	`/attack-graph/overlay`	Compromised nodes and edges for the overlay

Response Format

All endpoints return JSON. Errors return:

{
  "detail": "Error description"
}

with the appropriate HTTP status code (400, 404, 409, 500, or 503 where applicable).

​Base URL

​Authentication

​Endpoints

​System

​Topology

​Agents

​Sessions

​Guardrails

​Violations

​Scans

​Risk

​Attack Graph

​Response Format