> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tracectrl.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> TraceCtrl Engine REST API reference

## 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`](https://docs.tracectrl.ai/api-reference/health) | Health check |
| `GET` | [`/projects`](https://docs.tracectrl.ai/api-reference/projects) | List all service names (for project selector) |

### Topology

| Method | Endpoint | Description |
| - | - | - |
| `GET` | [`/topology/graph`](https://docs.tracectrl.ai/api-reference/topology-graph) | Full topology graph (supports `?service=`) |
| `GET` | [`/topology/agents/{agent_id}`](https://docs.tracectrl.ai/api-reference/topology-agent) | Single agent detail |

### Agents

| Method | Endpoint | Description |
| - | - | - |
| `GET` | [`/agents`](https://docs.tracectrl.ai/api-reference/agents) | Agent inventory (supports `?service=`) |
| `GET` | [`/agents/{agent_id}/tools`](https://docs.tracectrl.ai/api-reference/agent-tools) | Tools used by an agent |
| `GET` | [`/agents/{agent_id}/guardrails`](https://docs.tracectrl.ai/api-reference/agent-guardrails) | Guardrails for an agent |

### Sessions

| Method | Endpoint | Description |
| - | - | - |
| `GET` | [`/sessions`](https://docs.tracectrl.ai/api-reference/sessions) | Session list (supports `?service=`) |
| `GET` | [`/sessions/latest-spans`](https://docs.tracectrl.ai/api-reference/sessions-latest-spans) | Spans from the most recent trace |
| `GET` | [`/sessions/{trace_id}/spans`](https://docs.tracectrl.ai/api-reference/sessions-spans) | Spans for a trace (supports `?extra=`) |

### Guardrails

| Method | Endpoint | Description |
| - | - | - |
| `GET` | [`/guardrails`](https://docs.tracectrl.ai/api-reference/guardrails-list) | Guardrail registry (supports `?agent_id=`) |
| `GET` | [`/guardrails/invocations`](https://docs.tracectrl.ai/api-reference/guardrail-invocations) | Recent evaluation spans |
| `GET` | [`/guardrails/protector-config`](https://docs.tracectrl.ai/api-reference/protector-config) | Protector Plus config (redacted) |
| `PUT` | [`/guardrails/protector-config`](https://docs.tracectrl.ai/api-reference/protector-config) | Upsert Protector Plus config |
| `POST` | [`/guardrails/protector-test`](https://docs.tracectrl.ai/api-reference/protector-config) | Health-check the Protector Plus endpoint |
| `GET` | [`/guardrails/protector-config/sdk`](https://docs.tracectrl.ai/api-reference/protector-config) | Full config for the SDK |

### Violations

| Method | Endpoint | Description |
| - | - | - |
| `GET` | [`/violations`](https://docs.tracectrl.ai/api-reference/violations) | List violations (`limit`, `agent_id`, `severity`) |
| `GET` | [`/violations/recent`](https://docs.tracectrl.ai/api-reference/violations-recent) | Recent violations (`limit`) |
| `GET` | [`/violations/stream`](https://docs.tracectrl.ai/api-reference/violations-stream) | SSE stream of new violations |

### Scans

| Method | Endpoint | Description |
| - | - | - |
| `POST` | [`/scans`](https://docs.tracectrl.ai/api-reference/scans-upload) | Upload scan results from a CLI |
| `GET` | [`/scans`](https://docs.tracectrl.ai/api-reference/scans-list) | List all stored scans |
| `GET` | [`/scans/latest`](https://docs.tracectrl.ai/api-reference/scans-latest) | Latest scan with drift detection |
| `GET` | [`/scans/{scan_id}`](https://docs.tracectrl.ai/api-reference/scans-detail) | Results for a specific scan |
| `POST` | [`/scan/validate-path`](https://docs.tracectrl.ai/api-reference/scan-validate-path) | Validate an OpenClaw workspace path |
| `POST` | [`/scan/trigger`](https://docs.tracectrl.ai/api-reference/scan-trigger) | Trigger an engine-side scan |
| `GET` | [`/scan/status/{scan_id}`](https://docs.tracectrl.ai/api-reference/scan-status) | Poll a triggered scan |
| `POST` | [`/scan/fix`](https://docs.tracectrl.ai/api-reference/scan-fix) | Apply automated remediations |

### Risk

| Method | Endpoint | Description |
| - | - | - |
| `GET` | [`/risk/agents`](https://docs.tracectrl.ai/api-reference/risk-agents) | All agents with inventory data |
| `GET` | [`/risk/summary`](https://docs.tracectrl.ai/api-reference/risk-summary) | System-wide risk summary |
| `GET` | [`/risk/attack-paths`](https://docs.tracectrl.ai/api-reference/attack-paths) | Ranked attack paths from TAGAAI rules |
| `GET` | [`/risk/agent-scores`](https://docs.tracectrl.ai/api-reference/agent-scores) | Per-agent risk scores |

### Attack Graph

| Method | Endpoint | Description |
| - | - | - |
| `GET` | [`/attack-graph/paths`](https://docs.tracectrl.ai/api-reference/attack-graph-paths) | Detailed paths for the findings panel |
| `GET` | [`/attack-graph/overlay`](https://docs.tracectrl.ai/api-reference/attack-graph-overlay) | Compromised nodes and edges for the overlay |

## Response Format

All endpoints return JSON. Errors return:

```json theme={"dark"}
{
  "detail": "Error description"
}
```

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.