opamp-core

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.

This site is open source. Improve this page.