API Reference

The Govrix Management API runs on port 4001. It exposes 17 endpoints covering health, agents, events, sessions, costs, and configuration.

Authentication

All endpoints except /health, /ready, and /metrics require a bearer token.


curl -H "Authorization: Bearer $GOVRIX_API_KEY" \
  http://localhost:4001/api/v1/agents

GOVRIX_API_KEY must be set in your environment or .env file before starting the proxy. Requests without a valid token receive 401 Unauthorized.

The key is configured at startup via the GOVRIX_API_KEY environment variable. There is no key rotation endpoint in Scout OSS — rotate by restarting with a new value.

Endpoint Overview

Method	Path	Auth	Description
`GET`	`/health`	No	Liveness probe
`GET`	`/ready`	No	Readiness probe (DB connected)
`GET`	`/metrics`	No	Prometheus metrics
`GET`	`/api/v1/agents`	Yes	List all agents
`GET`	`/api/v1/agents/{id}`	Yes	Get agent by ID
`PUT`	`/api/v1/agents/{id}`	Yes	Update agent status / metadata
`POST`	`/api/v1/agents/{id}/retire`	Yes	Retire an agent
`GET`	`/api/v1/agents/{id}/events`	Yes	Events for one agent
`GET`	`/api/v1/events`	Yes	List all events
`GET`	`/api/v1/events/{id}`	Yes	Get event by ID
`GET`	`/api/v1/events/sessions/{session_id}`	Yes	Events for a session
`GET`	`/api/v1/events/stream`	Yes	SSE stream of live events
`GET`	`/api/v1/sessions`	Yes	List sessions (Enterprise)
`GET`	`/api/v1/sessions/{id}`	Yes	Session detail + events (Enterprise)
`GET`	`/api/v1/costs/summary`	Yes	Total cost and tokens, date range
`GET`	`/api/v1/costs/breakdown`	Yes	Cost breakdown by agent
`GET`	`/api/v1/config`	Yes	Current proxy configuration

Base URL


http://localhost:4001

In production, place the Management API behind an internal load balancer or service mesh — it should not be exposed to the public internet.