OpAMP Provider Endpoints

This document lists the HTTP and WebSocket endpoints exposed by the provider.

Bearer-Token Protection Scope

Bearer protection is controlled by provider config plus environment-backed secrets/JWT settings:

  • provider.ui-use-authorization controls non-OpAMP routes (for example /api, /tool, /ui, /help, /doc-set, /sse, /messages, /mcp when enabled).
  • provider.allow-mcp controls whether /mcp is exposed at all. Default is false.
  • provider.opamp-use-authorization controls OpAMP transport (/v1/opamp HTTP and WebSocket).
  • Environment variables provide token/JWT validation settings:
    • OpAMP transport: OPAMP_AUTH_*
    • Non-OpAMP routes: UI_AUTH_*

UI Endpoints

Method Path Purpose
GET / Redirect to the web UI (/ui).
GET /ui Main web UI page.
GET /help Help page.
GET /doc-set Redirect to the latest docs URL configured in provider.latest_docs_url. The provider, config-service, and catalog-service UI Latest docs links use this route.
GET /create.ico UI favicon.

Tool Endpoints

Method Path Purpose
GET /tool OpenAPI specification for /tool endpoints.
GET /tool/otelAgents List agents that are not disconnected.
GET /tool/commands List all commands (OpAMP-standard and custom).

When provider.ui-use-authorization is set to config-token or idp, /tool endpoints require an Authorization: Bearer <token> header.

GET /tool/otelAgents supports additional query filters (documented in /tool OpenAPI), including service_instance_id, client_version, host_name, host_ip, and invertFilter=true to invert active filter matches.

API Endpoints

Method Path Purpose
GET /api/clients List tracked clients (pending_approval_total included).
GET /api/clients/<client_id> Get one client record.
DELETE /api/clients/<client_id> Remove a client record.
GET /api/approvals/pending List pending-approval agents.
POST /api/approvals/pending Apply approve/block decisions for pending agents.
POST /api/clients/<client_id>/commands Queue command/custom command.
POST /api/clients/<client_id>/actions Set next actions for a client.
PUT /api/clients/<client_id>/heartbeat-frequency Set heartbeat frequency for one client.
POST /api/clients/<client_id>/identify Queue new instance UID for client.
POST /api/clients/<client_id>/config Set requested config for a client.
GET /api/commands/custom List custom command metadata for the UI.
GET /api/settings/comms Get communication threshold settings.
PUT /api/settings/comms Update communication threshold settings.
GET /api/settings/diagnostic Get diagnostic and state-persistence status metadata for UI feature-gating/health display.
GET /api/metrics/graphs Get current gauge values and optional retained gauge-series history for internal dashboard views.
POST /api/settings/state/save Force an immediate provider state snapshot save (when persistence is enabled).
GET /api/settings/client Get global client settings.
PUT /api/settings/client Update global client settings.
GET /api/help/global-settings Get shared help text for Global Settings labels/tooltips.
POST /api/shutdown Shutdown server (requires {"confirm": true}).

GET /api/clients query parameters:

  • service_instance_id (string): case-insensitive substring match against displayed service instance name (falls back to client_id when service.instance.id is absent).
  • client_version (string): case-insensitive substring match.
  • host_name (string): case-insensitive substring match.
  • host_ip (string): case-insensitive substring match.
  • Active filters are combined with OR semantics (records are included when any active filter matches).
  • invertFilter (boolean): when true, invert active filter matches (equivalent to != for the active filter set). Accepted boolean values: true|false|1|0|yes|no|on|off.

OpAMP Transport Endpoints

Method Path Purpose
POST /v1/opamp OpAMP HTTP transport endpoint (AgentToServer/ServerToAgent).
WEBSOCKET /v1/opamp OpAMP WebSocket transport endpoint.

Metrics Endpoint

Method Path Purpose
GET /metrics Expose provider metrics in Prometheus text format.

Metrics notes:

  • provider.metrics.enabled controls both /metrics and /api/metrics/graphs.
  • provider.metrics.graph_history_minutes controls in-memory retention for graphable gauge metrics exposed by /api/metrics/graphs.
  • /metrics is a non-OpAMP route, so it follows provider.ui-use-authorization.
  • When provider.ui-use-authorization=config-token or idp, scrapers must send Authorization: Bearer <token>.

Human-in-loop behavior notes:

  • When provider.human_in_loop_approval=true, unknown agent UIDs are staged into pending approval and rejected until explicitly approved.
  • Blocked agent UIDs are rejected for both HTTP and WebSocket traffic.
  • provider.opamp-use-authorization controls /v1/opamp auth mode:
    • none (default): no OpAMP bearer-token enforcement.
    • config-token: compare bearer token to OPAMP_AUTH_STATIC_TOKEN.
    • idp: validate bearer JWT using OPAMP_AUTH_JWT_* settings.

Bearer protection notes:

  • Both POST /v1/opamp and WEBSOCKET /v1/opamp are protected through provider.opamp-use-authorization.
  • config-token mode validates against OPAMP_AUTH_STATIC_TOKEN.
  • idp mode validates JWT using OPAMP_AUTH_JWT_*.

MCP Transport Endpoints

Method Path Purpose
GET /sse FastMCP SSE stream endpoint exposed through Quart (when mcptool + FastMCP are available).
POST /messages FastMCP SSE message endpoint paired with /sse.
POST/GET /mcp FastMCP Streamable HTTP endpoint (only when provider.allow-mcp=true).

When provider.ui-use-authorization is set to config-token or idp, MCP transport endpoints (/sse, /messages, /mcp) require Authorization: Bearer <token>.

When provider.allow-mcp=false, /mcp requests are rejected even if /sse and /messages remain available.