API Endpoints

Complete reference for the Proxima Console REST API.

Infrastructure (no auth)

Method	Path	Description
GET	/healthz	Liveness check
GET	/readyz	Readiness check (DB + NATS)
GET	/metrics	Prometheus metrics

Setup Status

Method	Path	Description
GET	/api/v1/setup/status	Check initial setup completion status (public, no auth)

Clients

Method	Path	Description
GET	/api/v1/clients	List clients
POST	/api/v1/clients	Create client
GET	/api/v1/clients/:id	Get client
PUT	/api/v1/clients/:id	Update client
DELETE	/api/v1/clients/:id	Delete client
GET	/api/v1/clients/:id/environments	List environments for client
GET	/api/v1/clients/:id/hosts	List hosts for a client
GET	/api/v1/clients/:id/integrations	List integrations detected on the client's hosts
GET	/api/v1/clients/:id/install-tokens	List install tokens
POST	/api/v1/clients/:id/install-tokens	Create install token. Single-use by default — omitting max_uses stores 1, so one leaked token enrolls at most one agent. Pass max_uses: n (n≥1) to bound it, or max_uses: 0 to opt into unlimited. Negative is 400.
DELETE	/api/v1/clients/:id/install-tokens/:tokenID	Delete install token
GET	/api/v1/clients/:id/notification-settings	Get client notification settings
PUT	/api/v1/clients/:id/notification-settings	Update client notification settings
GET	/api/v1/clients/:id/retention-settings	Get client change-retention overrides (admin)
PUT	/api/v1/clients/:id/retention-settings	Update client change-retention overrides (admin)
PUT	/api/v1/clients/:id/covering-team	Assign the client's escalation covering team
DELETE	/api/v1/clients/:id/covering-team	Clear the client's escalation covering team
GET	/api/v1/clients/:id/llm-usage	Get the client's LLM usage and spend
GET	/api/v1/clients/:id/healthcheck/score	Get the client's healthcheck score

Environments

Method	Path	Description
POST	/api/v1/clients/:id/environments	Create environment for client
GET	/api/v1/environments/:envId	Get environment
PUT	/api/v1/environments/:envId	Update environment
DELETE	/api/v1/environments/:envId	Delete environment
GET	/api/v1/environments/:id/hosts	List hosts in environment
GET	/api/v1/environments/:envID/healthcheck/score	Get the environment's healthcheck score
GET	/api/v1/environments/:envID/inventory/export	Export the environment's inventory
GET	/api/v1/environments/:envID/log-source-status	List log-source status for the environment's hosts

Assets (CMDB)

Method	Path	Description
GET	/api/v1/assets	List all assets (paginated, filterable by type/status/search)
GET	/api/v1/assets/summary	Asset counts grouped by type and status
GET	/api/v1/assets/:id	Get single asset
GET	/api/v1/clients/:id/assets	List assets for a client
GET	/api/v1/environments/:id/assets	List assets for an environment

All asset endpoints require assets:read permission and are scoped to the caller's allowed clients. See Assets & CMDB for full documentation.

Clusters (K8s Inventory)

Method	Path	Description
GET	/api/v1/clusters	List all clusters (paginated, filterable by client/environment/status/search; ?include=capacity adds capacity, pods_not_running, warning_events_1h)
GET	/api/v1/clusters/:clusterID	Get single cluster with full details
GET	/api/v1/clusters/:clusterID/summary	Cluster health digest from the inventory: node/pod counts, waiting reasons, pending pods, restarters, workloads not ready, capacity (assets:read)
GET	/api/v1/clusters/:clusterID/metrics/:query	One of ten allow-listed cluster metric queries (cpu_by_node, memory_by_namespace, restarts, pods_by_phase, cpu_by_workload, cpu_by_namespace, cpu_by_pod, memory_by_pod, restarts_by_workload, replicas); start, end, namespace, workload, workload_kind, instant (metrics:read)
GET	/api/v1/cloud-resources/:resourceID/metrics/:name	One allow-listed metric of a Hetzner Cloud load balancer (hcloud_lb_*) or of a Hetzner Cloud server with no Console agent (hcloud_server_*), in the host metrics shape; resourceID is the topology node's cloud.resource_id; start, end (metrics:read on the resource's pull source: its environment when pinned, the whole project when not)
GET	/api/v1/clusters/:clusterID/nodes	List nodes in a cluster (with host linkage)
GET	/api/v1/clusters/:clusterID/nodes/capacity	Every node (up to 1,000) with allocatable, requested, limits and used CPU/memory, pods, status; truncated and total (assets:read)
GET	/api/v1/clusters/:clusterID/nodes/:nodeID	One node of the cluster; another cluster's node is 404 (assets:read)
GET	/api/v1/clusters/:clusterID/namespaces	List namespaces in a cluster
GET	/api/v1/clusters/:clusterID/namespaces/usage	Every namespace with requested/limits CPU and memory, pods, restarts, workload count (assets:read)
GET	/api/v1/clusters/:clusterID/workloads	List workloads in a cluster (filterable by namespace/kind)
GET	/api/v1/clusters/:clusterID/workloads/:workloadID	One workload of the cluster; another cluster's workload is 404 (assets:read)
GET	/api/v1/clusters/:clusterID/pods	List pods in a cluster (filterable by namespace, phase)
GET	/api/v1/clusters/:clusterID/nodes/:nodeID/pods	List pods on a specific node
GET	/api/v1/clusters/:clusterID/workloads/:workloadID/pods	List pods for a specific workload
GET	/api/v1/clusters/:clusterID/services	List services in a cluster (filterable by namespace)
GET	/api/v1/clusters/:clusterID/ingresses	List ingresses in a cluster (filterable by namespace)
GET	/api/v1/clusters/:clusterID/pvcs	List PVCs in a cluster (filterable by namespace, phase)
GET	/api/v1/clusters/:clusterID/events	List K8s events in a cluster (filterable by type: Normal/Warning)
GET	/api/v1/clusters/:clusterID/jobs	List jobs/cronjobs in a cluster (filterable by namespace, kind)
GET	/api/v1/clusters/:clusterID/hpas	List HPAs in a cluster (filterable by namespace)
GET	/api/v1/clusters/:clusterID/network-policies	List network policies in a cluster (filterable by namespace)
GET	/api/v1/clusters/:clusterID/resource-quotas	List resource quotas in a cluster (filterable by namespace)
GET	/api/v1/clusters/:clusterID/endpoint-slices	List endpoint slices in a cluster (filterable by namespace)
GET	/api/v1/clusters/:clusterID/live/manifest	One object (kind, namespace, name) read live through the cluster agent, redacted in the agent; ConfigMaps and Secrets refused. Cluster agent v0.8.0+ (409 agent_too_old), 60 reads a minute per user shared with revisions
GET	/api/v1/clusters/:clusterID/live/revisions	A workload's newest 20 revisions with redacted pod templates, read live. Cluster agent v0.8.0+
GET	/api/v1/clusters/:clusterID/live/logs	One container's recent output read live from the pod, secret-sanitized, never stored (namespace, pod, container, tail ≤ 300, previous, since_time). Needs logs:read, not assets:read; 30 reads a minute per user
GET	/api/v1/clusters/:clusterID/events/timeline	Kubernetes events from the 14-day VictoriaLogs copy, newest first; validated exact-match filters (namespace, involved_kind, involved_name, workload + workload_kind, type, reason), window ≤ 14 days, limit ≤ 1000; 60 reads a minute per user
GET	/api/v1/clusters/:clusterID/changes	"What changed?" timeline for the cluster, a namespace or a workload: recorded changes, ArgoCD deploys, Kubernetes events and alerts in one list, newest first; namespace, workload, kind, from, to (window ≤ 30 days). Each source needs its own permission (changes:read, alerts:read, assets:read); a missing one empties that source, holding none is 403
GET	/api/v1/clusters/:clusterID/argocd/applications	ArgoCD Applications reported by this cluster's agent or mapped to it (same client only), each with its destination mapping, sync/health and revisions; report.state and notes explain unknown data (agent_too_old, crd_absent, forbidden, …). assets:read on the cluster's environment; rows naming another cluster the caller cannot read are hidden
GET	/api/v1/clusters/:clusterID/workloads/:workloadID/drift	ArgoCD drift of one workload: the Applications mapped to this cluster that manage it (group/kind/namespace/name), with the workload's own sync and health. assets:read; the workload must belong to the cluster
GET	/api/v1/clients/:id/clusters	List clusters for a client
GET	/api/v1/environments/:envID/clusters	List clusters for an environment

All cluster endpoints require assets:read permission unless noted, and are scoped to the caller's allowed clients. See Kubernetes Inventory for full documentation.

Cluster Onboarding

Method	Path	Description
POST	/api/v1/clients/:id/cluster-onboarding	Record the intent to onboard a cluster and mint the install token the collector enrolls with (24h, max_uses unlimited so every StatefulSet replica can enroll, pinned to one environment). Idempotent per (environment_id, cluster_slug): a second call resumes the attempt and returns it without a new token. hosts:write on the client and the environment
GET	/api/v1/clients/:id/cluster-onboarding	List the client's attempts that are neither abandoned nor finished. hosts:read; an environment-scoped caller sees only attempts in environments it may read
GET	/api/v1/cluster-onboarding/:onboardingID/status	Recompute both tracks and return every gate with its verdict and its sentence. Always recomputed; the stored last_status is a list-view cache, never the authority. hosts:read on the attempt's client
POST	/api/v1/cluster-onboarding/:onboardingID/probe	Send one GET /version through the cluster's agent, impersonating the caller with the groups their roles' kube_specs resolve for this cluster, and record the outcome. Fixed path, 5s timeout, one probe per 15s per attempt (429), single-flighted (409), 404 until the cluster has appeared in Console. kubernetes:read on the cluster's client and environment
DELETE	/api/v1/cluster-onboarding/:onboardingID	Mark the attempt abandoned so it leaves the open-attempts list. Never deletes or unlinks the cluster, its inventory or its agent. hosts:write on the attempt's client and environment

There is no clusters:* permission; onboarding borrows hosts:* for its own records and kubernetes:read for the one call that reaches into a cluster. See Cluster Onboarding for the tracks, the gate states and what the round-trip proves.

Databases (CMDB)

Method	Path	Description
GET	/api/v1/database-clusters	List database clusters (filterable by client/environment/engine/status/search)
GET	/api/v1/database-clusters/:databaseClusterID	Get single database cluster
GET	/api/v1/databases	List databases (filterable by client/environment/cluster/host/engine/role/status/search)
GET	/api/v1/databases/:databaseID	Get single database instance

All database endpoints require assets:read permission and are scoped to the caller's allowed clients. See Database Inventory for full documentation.

Hosts

Method	Path	Description
GET	/api/v1/hosts	List all hosts (paginated, client-scoped)
GET	/api/v1/hosts/:id	Get host details
DELETE	/api/v1/hosts/:id	Delete host
GET	/api/v1/hosts/:id/services	List services
GET	/api/v1/hosts/:id/packages	List packages
GET	/api/v1/hosts/:id/ports	List open ports
GET	/api/v1/hosts/:id/interfaces	List network interfaces
GET	/api/v1/hosts/:id/users	List users
GET	/api/v1/hosts/:id/hardware	Get hardware details (CPUs, disks, filesystems, firewall rules, kernel modules, certificates)
GET	/api/v1/hosts/:id/security	Get security posture (firewall, SELinux, AppArmor, etc.)
GET	/api/v1/hosts/:id/cron-jobs	List cron jobs
GET	/api/v1/hosts/:id/gpu-devices	List GPU devices
GET	/api/v1/hosts/:id/containers	List Docker containers
GET	/api/v1/hosts/:id/containers/metrics/latest	Latest metrics for all containers on a host
GET	/api/v1/hosts/:id/containers/:containerID/metrics	Per-container metric history (CPU, memory, network, block I/O)
GET	/api/v1/hosts/:id/processes	List running processes (CPU-descending)
GET	/api/v1/hosts/:id/processes/:pid/metrics	Per-process metric history (CPU, memory, RSS, threads)
GET	/api/v1/hosts/export	Export the host inventory (all hosts in scope)
POST	/api/v1/hosts/export	Export a selected subset of hosts

Host Lifecycle

Method	Path	Description
POST	/api/v1/hosts/:id/deactivate	Deactivate host (marks offline, revokes NATS credentials)
POST	/api/v1/hosts/:id/activate	Re-activate a deactivated host
POST	/api/v1/hosts/:id/revoke	Revoke host NATS credentials (force disconnect)

Entity Tags

User-defined key=value tags on entities. Currently supports hosts; extensible to other entity types.

Method	Path	Description
GET	/api/v1/hosts/:id/tags	List tags for a host
PUT	/api/v1/hosts/:id/tags	Bulk set (upsert) tags
DELETE	/api/v1/hosts/:id/tags/:key	Delete a single tag
GET	/api/v1/tags/keys	Autocomplete tag keys
GET	/api/v1/tags/values	Autocomplete tag values for a key

Query Parameters for /tags/keys

Parameter	Required	Description
prefix	No	Filter keys starting with this prefix

Query Parameters for /tags/values

Parameter	Required	Description
key	Yes	Tag key to search values for
prefix	No	Filter values starting with this prefix

Tag Key Validation

Tag keys must match ^[a-z0-9][a-z0-9._-]{0,99}$ — lowercase alphanumeric with dots, hyphens, and underscores, 1-100 characters. Tag values are limited to 500 characters.

Entity Extensibility

The entity_tags table uses a polymorphic entity_type column. Adding tags to new entity types (services, containers) requires adding one map entry in AllowedEntityTypes and registering new routes.

Search (PQL)

Search across infrastructure using the Proxima Query Language (PQL). Results are scoped to the authenticated user's accessible clients (super admins see all).

Method	Path	Description
GET	/api/v1/search	Search hosts using PQL query
GET	/api/v1/search/count	Count matching hosts
GET	/api/v1/search/fields	List searchable fields and operators
POST	/api/v1/search/validate	Validate PQL syntax
GET	/api/v1/search/aggregate	Aggregate results by a field
GET	/api/v1/search/values	Autocomplete field values
POST	/api/v1/search/translate	Translate a natural-language question into PQL

Query Parameters for /search

Parameter	Default	Description
q	— (required)	PQL query string
page	1	Page number
per_page	20	Items per page (max 100)
format	json	Response format: json or csv

Query Parameters for /search/count

Parameter	Required	Description
q	Yes	PQL query string

Query Parameters for /search/aggregate

Parameter	Required	Description
q	Yes	PQL query string
group_by	Yes	Field to group by (e.g. host.os, host.arch)

Query Parameters for /search/values

Parameter	Required	Description
field	Yes	PQL field name (e.g. host.os, tag.env, label.role)
prefix	No	Filter values starting with this prefix
limit	No	Max results (default 20, max 100)

Validate Request Body

{ "query": "host.os = \"Ubuntu\"" }

PQL Syntax

host.os = "Ubuntu"
host.arch IN ("amd64", "arm64")
host.hostname ~ "web-*"
service.name = "nginx" AND host.agent_status = "online"
label.role = "web" AND tag.tier = "production"
host.cpu_cores > 4 AND host.memory_total_bytes > 8000000000
NOT tag.owner EXISTS

Field prefixes: host.*, label.* (agent labels), tag.* (user-defined tags), service.*, container.*, package.*

Operators: =, !=, ~ (glob wildcard), >, <, >=, <=, IN, NOT IN, EXISTS

Combinators: AND, OR, NOT, parenthesized grouping

Saved Searches

Save PQL queries for quick access. Users see their own saved searches plus shared searches from other users.

Method	Path	Description
GET	/api/v1/saved-searches	List saved searches (own + shared)
POST	/api/v1/saved-searches	Save a PQL query
GET	/api/v1/saved-searches/:id	Get saved search
PUT	/api/v1/saved-searches/:id	Update saved search (owner or super admin)
DELETE	/api/v1/saved-searches/:id	Delete saved search (owner or super admin)

Create/Update Request Body

{
  "name": "Ubuntu production servers",
  "query": "host.os ~ \"Ubuntu*\" AND tag.tier = \"production\"",
  "description": "All Ubuntu hosts tagged as production tier",
  "is_shared": true
}

Metrics (per-host)

Method	Path	Description
GET	/api/v1/hosts/:id/metrics	List distinct metric names
GET	/api/v1/hosts/:id/metrics/:name	Query time-series data points
GET	/api/v1/hosts/:id/metrics/:name/series	List distinct label keys

Query Parameters for /metrics/:name

Parameter	Default	Description
start	1 hour ago	Start time (RFC3339)
end	now	End time (RFC3339)
labels_key	""	Filter by labels key (e.g. device=sda1,mount=/)
derivative	false	Compute rate of change for counter metrics (true/false)

For time ranges ≤6 hours, returns 1-minute bucketed data from the raw table. For longer ranges, returns hourly aggregates.

Batch Endpoints

Method	Path	Description
GET	/api/v1/hosts/metrics/latest	Batch query latest metric values for multiple hosts
GET	/api/v1/hosts/tags/batch	Batch query tags for multiple hosts

Query Parameters for /hosts/metrics/latest

Parameter	Required	Description
host_ids	Yes	Comma-separated host IDs (UUIDs)
metrics	Yes	Comma-separated metric names

Returns the most recent value per (host, metric) pair within the last hour. Designed to replace per-host metric fetching on the hosts list page (1 request instead of 3 per host). Limited to 100 host IDs and 50 metric names per request.

Aggregate Metrics (environment / client)

Aggregate endpoints return metrics averaged (AVG) across all hosts in an environment or client. Same query parameters and response format as per-host metrics.

Environment-level

Method	Path	Description
GET	/api/v1/environments/:id/metrics	List metric names across all hosts
GET	/api/v1/environments/:id/metrics/:name	Query aggregated data points
GET	/api/v1/environments/:id/metrics/:name/series	List series across all hosts

Client-level

Method	Path	Description
GET	/api/v1/clients/:id/metrics	List metric names across all hosts
GET	/api/v1/clients/:id/metrics/:name	Query aggregated data points
GET	/api/v1/clients/:id/metrics/:name/series	List series across all hosts
GET	/api/v1/clients/:id/metrics/:name/hosts	Per-host series — one per host and labels_key, never averaged (below)

The environment and project Metrics dashboards no longer use the averaged endpoints; they read /clients/:id/metrics/:name/hosts.

Per-host series (client)

GET /api/v1/clients/:id/metrics/:name/hosts returns {series: [{host_id, labels_key, data}], truncated, hosts_total} in one VictoriaMetrics query. With neither host_ids nor top, the server keeps at most 100 hosts — the highest CPU usage peaks over the window — and sets truncated and hosts_total; host_ids above 100 is a 400. Parameters: start, end, derivative, plus environment_id (one environment of the client — 404 if it belongs to another client, 403 if the caller cannot read it), host_ids (comma-separated UUIDs, at most 100) and top (1–100, keep the N series with the highest peak — it ranks series, not hosts, so it is meant for cpu_usage_ratio, where the two coincide). Requires metrics:read on the client; an environment-scoped caller is confined to its environments, and the query always names the environments it reads, so host_ids cannot reach another client's hosts.

Aggregation Semantics (the averaged endpoints)

• AVG is used as the default aggregation across hosts — appropriate for percentage metrics (CPU, memory, disk utilization).
• MIN/MAX are computed as the overall min/max across all hosts.
• sample_count is summed across all hosts.
• Derivative support (?derivative=true) computes per-host rates first, then averages across hosts.

Events Timeline

Method	Path	Description
GET	/api/v1/events/timeline	Get aggregated events for chart markers

Query Parameters for /events/timeline

Parameter	Required	Description
start	Yes	Start time (RFC3339)
end	Yes	End time (RFC3339)
host_id	No	Filter by host (UUID)
environment_id	No	Filter by environment (UUID)
event_type	No	Filter by type: deploy, file_change, agent_status
limit	No	Max results (default 100)

MetricsQL Query

Method	Path	Description
POST	/api/v1/metrics/query	Execute MetricsQL expression with tenant filtering

Backend injects extra_filters[] for tenant isolation. Response streams Prometheus-format JSON.

Annotations

Method	Path	Description
POST	/api/v1/annotations	Create a chart note (host / environment / client scope; annotations:write at that scope; signed-in user only)
GET	/api/v1/annotations	Notes a host / environment / client chart inherits in [start, end] (metrics:read)
PUT	/api/v1/annotations/:id	Edit a note (author only)
DELETE	/api/v1/annotations/:id	Delete a note (author, annotations:write moderator at its scope, or super-admin)
GET	/api/v1/chart-markers	Alert windows + completed deploys for a host / environment / client chart (metrics:read; alerts need alerts:read, deploys changes:read)

See Chart Notes & Markers for scopes, permissions and marker rules.

Change Detection

File integrity monitoring — tracks file changes, watched files, and file version history.

Method	Path	Description
GET	/api/v1/changes	List all change events (filtered, paginated)
GET	/api/v1/changes/:id	Get a single change event
GET	/api/v1/hosts/:id/changes	List change events for a host
GET	/api/v1/hosts/:id/files	List watched files for a host
GET	/api/v1/hosts/:id/files/:fileID/versions	List file version history
GET	/api/v1/clients/:id/changes	List change events for a client
GET	/api/v1/environments/:id/changes	List change events for an environment
GET	/api/v1/changes/catalog	Get the change catalog (known change sources and kinds)
GET	/api/v1/changes/:id/citations	List incidents that cited this change as a candidate cause

Query Parameters for change event endpoints

Parameter	Default	Description
page	1	Page number
per_page	20	Items per page (max 100)
source	—	Filter by source (agent, gitlab, github, deployment)
event_type	—	Filter by type (file_created, file_modified, file_deleted, file_metadata_changed, push, merge_request, tag, release, pipeline_completed, pipeline_failed, workflow_completed, workflow_failed, sync, sync_failed, health_degraded)
severity	—	Filter by severity (info, warning, critical)
start	—	Start time (RFC3339)
end	—	End time (RFC3339)

Global /changes also supports host_id, client_id, and environment_id query parameters.

Query Parameters for /hosts/:id/files

Parameter	Default	Description
page	1	Page number
per_page	20	Items per page (max 100)
include_deleted	false	Include soft-deleted files

Compliance

Frameworks

Method	Path	Description
GET	/api/v1/frameworks	List compliance frameworks
GET	/api/v1/frameworks/:id	Get framework details
POST	/api/v1/frameworks	Create compliance framework
PUT	/api/v1/frameworks/:id	Update framework
DELETE	/api/v1/frameworks/:id	Delete framework
POST	/api/v1/frameworks/:id/reset	Reset framework evaluations
GET	/api/v1/frameworks/:id/controls	List a framework's controls (compliance:read)
POST	/api/v1/frameworks/:id/controls	Create control under framework

Controls

Method	Path	Description
GET	/api/v1/controls/:id	Get control details
PUT	/api/v1/controls/:id	Update control
DELETE	/api/v1/controls/:id	Delete control
GET	/api/v1/controls/:id/mappings	List mappings for a control
POST	/api/v1/controls/:id/mappings	Create mapping for a control

Mappings

Method	Path	Description
GET	/api/v1/mappings/:id	Get mapping by ID
PUT	/api/v1/mappings/:id	Update mapping
DELETE	/api/v1/mappings/:id	Delete mapping

Compliance Posture (Host / Environment / Client)

Method	Path	Description
GET	/api/v1/hosts/:id/compliance	Get host compliance posture
GET	/api/v1/hosts/:id/compliance/evaluations	List host compliance evaluations
POST	/api/v1/hosts/:id/compliance/evaluate	Trigger compliance evaluation for host
GET	/api/v1/environments/:envID/compliance	Get environment compliance posture
GET	/api/v1/environments/:envID/compliance/top-failures	Top compliance failures in environment
GET	/api/v1/clients/:id/compliance	Get client compliance posture
GET	/api/v1/clients/:id/compliance/top-failures	Top compliance failures for client
GET	/api/v1/clients/:id/compliance/expiring-exceptions	Expiring exceptions for client

Attestations

Method	Path	Description
GET	/api/v1/attestations	List attestations (filterable, client-scoped)
POST	/api/v1/attestations	Create manual attestation
PUT	/api/v1/attestations/:id	Update attestation
DELETE	/api/v1/attestations/:id	Delete attestation

Exceptions

Method	Path	Description
GET	/api/v1/exceptions	List compliance exceptions (filterable, client-scoped)
POST	/api/v1/exceptions	Create compliance exception
PUT	/api/v1/exceptions/:id	Update exception
DELETE	/api/v1/exceptions/:id	Delete exception

Agent Config (Environment-Level)

Manage environment-wide agent operational config. Changes are pushed to all online hosts. See Config Sync.

Method	Path	Description
GET	/api/v1/environments/:envID/agent-configs	List all configs for an environment
GET	/api/v1/environments/:envID/agent-configs/:configType	Get a specific config
PUT	/api/v1/environments/:envID/agent-configs/:configType	Create or update config (pushes to all online hosts)
DELETE	/api/v1/environments/:envID/agent-configs/:configType	Delete a config

Agent Config (Host-Level)

Per-host config overrides and effective config resolution. See Config Sync.

Method	Path	Description
GET	/api/v1/hosts/:hostID/agent-configs/effective	Get all resolved configs with secrets redacted
GET	/api/v1/hosts/:hostID/agent-configs/:configType	Get effective (resolved) config for a host
PUT	/api/v1/hosts/:hostID/agent-configs/:configType	Create or update host override (pushes to agent)
DELETE	/api/v1/hosts/:hostID/agent-configs/:configType	Delete host override (reverts to environment config)

Allowed Config Types

agent_settings, change_detection, collectors, healthcheck, intervals, labels, log_collection, watch_files. Other values return 400 Bad Request.

Credentials

Manage encrypted credentials for collector plugins. Credentials are encrypted at rest using Vault Transit. See Credentials for full documentation.

Method	Path	Description
POST	/api/v1/clients/:clientID/credentials	Create a credential
GET	/api/v1/clients/:clientID/credentials	List credentials for a client
GET	/api/v1/clients/:clientID/credentials/:credentialID	Get credential metadata
PUT	/api/v1/clients/:clientID/credentials/:credentialID	Update credential (rotate if data changes)
DELETE	/api/v1/clients/:clientID/credentials/:credentialID	Delete credential (409 if referenced)
POST	/api/v1/clients/:clientID/credentials/:credentialID/test	Test credential (decrypt + validate)
GET	/api/v1/credentials	List all credentials across the caller's clients
GET	/api/v1/credentials/types	List supported credential types

Alert Sources

Method	Path	Permission	Description
POST	/api/v1/clients/:id/alert-sources	alertsources:write	Create alert source (returns token once)
GET	/api/v1/clients/:id/alert-sources	alertsources:read	List alert sources for a client
GET	/api/v1/clients/:id/alert-sources/:id	alertsources:read	Get alert source
PUT	/api/v1/clients/:id/alert-sources/:id	alertsources:write	Update alert source
DELETE	/api/v1/clients/:id/alert-sources/:id	alertsources:delete	Delete alert source
POST	/api/v1/alert-sources	alertsources:write	Create alert source (top-level form; client_id in body)
GET	/api/v1/alert-sources	alertsources:read	List alert sources. client_id is optional: present, it lists that one client (re-checked per client in the handler); absent, it lists across every client on which the caller holds alertsources:read — a super-admin sees all, a caller who holds it on no client gets []
GET	/api/v1/alert-sources/:sourceID	alertsources:read	Get alert source
PUT	/api/v1/alert-sources/:sourceID	alertsources:write	Update alert source
DELETE	/api/v1/alert-sources/:sourceID	alertsources:delete	Delete alert source
GET	/api/v1/alert-sources/:sourceID/token	alertsources:read	Reveal the source's ingest token

Alert Label Mappings

Method	Path	Permission	Description
GET	/api/v1/clients/:id/alert-label-mappings	alertsources:read	List label mappings for a client
POST	/api/v1/clients/:id/alert-label-mappings	alertsources:write	Create label mapping
PUT	/api/v1/clients/:id/alert-label-mappings/:id	alertsources:write	Update label mapping
DELETE	/api/v1/clients/:id/alert-label-mappings/:id	alertsources:delete	Delete label mapping
GET	/api/v1/alert-label-mappings	alertsources:read	List label mappings across the caller's clients
POST	/api/v1/alert-label-mappings	alertsources:write	Create label mapping (top-level form)
PUT	/api/v1/alert-label-mappings/:mappingID	alertsources:write	Update label mapping
DELETE	/api/v1/alert-label-mappings/:mappingID	alertsources:delete	Delete label mapping

Alerts

Method	Path	Permission	Description
GET	/api/v1/alerts	alerts:read	List alert groups (filterable by client_id, environment_id, host_id, status, severity, from, to)
GET	/api/v1/alerts/:id	alerts:read	Get alert group detail with correlation, alerts, and log
GET	/api/v1/alerts/counts	alerts:read	Alert counts by status (scoped to user's clients)
POST	/api/v1/alerts/:id/acknowledge	alerts:write	Acknowledge alert group
POST	/api/v1/alerts/:id/resolve	alerts:write	Manually resolve alert group
POST	/api/v1/alerts/:id/silence	alerts:write	Silence alert group until timestamp
POST	/api/v1/alerts/:id/unsilence	alerts:write	Remove silence from alert group
POST	/api/v1/alerts/bulk/acknowledge	alerts:write	Bulk acknowledge alert groups
POST	/api/v1/alerts/bulk/resolve	alerts:write	Bulk resolve alert groups
POST	/api/v1/alerts/bulk/silence	alerts:write	Bulk silence alert groups
POST	/api/v1/alerts/:alertGroupID/notes	alerts:write	Add a note to an alert group
POST	/api/v1/alerts/:alertGroupID/confirm	alerts:write	Confirm you are still handling an acknowledged group (answers the ack confirm loop)
GET	/api/v1/alerts/:alertGroupID/context	alerts:read	Get the alert's deterministic context pack (the triage input)
POST	/api/v1/alerts/:alertGroupID/triage	alerts:write	Trigger an on-demand L1 investigation
POST	/api/v1/alerts/:alertGroupID/fix-worked	alerts:write	Record whether the known fix worked (feeds the learning loop). Returns 501 when the memory store is not wired.
POST	/api/v1/alerts/:alertGroupID/resolution/approve	alerts:write	Approve a resolution into L1 memory
POST	/api/v1/alerts/webhook/grafana/:token	none (token in URL)	Receive a Grafana legacy webhook

Query Parameters for /alerts

Parameter	Default	Description
page	1	Page number
per_page	20	Items per page (max 100)
client_id	—	Filter by client (UUID)
environment_id	—	Filter by environment (UUID)
host_id	—	Filter by host (UUID)
status	—	Filter by status: firing, acknowledged, resolved, silenced
severity	—	Filter by severity: critical, warning, info
from	—	Start time (RFC3339)
to	—	End time (RFC3339)

Silence Request Body

{
  "until": "2026-03-16T08:00:00Z"
}

Alertmanager Webhook Receiver (public, token-authenticated)

Method	Path	Description
POST	/api/v1/alerts/webhook/alertmanager/:token	Receive Alertmanager webhook (returns 202 Accepted)

No JWT or API key required. Authentication is via the token embedded in the URL. The request is published to NATS for async processing.

Watch Config (Legacy)

Per-host file watch configuration management. Config changes are persisted and pushed to agents via NATS.

Method	Path	Description
GET	/api/v1/hosts/:id/watch-config	Get current watch config for a host (404 if not set)
PUT	/api/v1/hosts/:id/watch-config	Create or update watch config (pushes to agent via NATS)

Logs

Log querying and exploration via VictoriaLogs proxy.

Method	Path	Description
POST	/api/v1/logs/query	Query logs via LogsQL with tenant-scoped filtering
GET/POST	/api/v1/logs/select/*	Reverse proxy to VictoriaLogs VMUI and API
GET	/api/v1/logs/select/:path	Proxy to the VictoriaLogs select API (tenant filters injected server-side)
GET	/api/v1/logs/select/vmui/:path	Proxy VMUI static assets

Query parameters:

Parameter	Description
client_id	Client ID (required for multi-client users and super admins)

Request body (POST /api/v1/logs/query):

{
  "query": "level:error",
  "start": "2024-01-01T00:00:00Z",
  "end": "2024-01-02T00:00:00Z",
  "limit": 1000
}

Response: NDJSON stream (one JSON object per line).

Admin: Users

Method	Path	Permission	Description
GET	/api/v1/users	users:read	List users (paginated)
POST	/api/v1/users	users:write	Create user (status=invited, sends invite email)
GET	/api/v1/users/:id	users:read	Get user with team memberships + client assignments
PUT	/api/v1/users/:id	users:write	Update user
DELETE	/api/v1/users/:id	users:delete	Disable user + revoke sessions
POST	/api/v1/users/:id/resend-invite	users:write	Resend invitation email
POST	/api/v1/users/:id/reset-password	users:write	Send password reset email
GET	/api/v1/users/:id/clients	users:read	List direct client assignments
POST	/api/v1/users/:id/clients	users:write	Assign user to client with role
PUT	/api/v1/users/:id/clients/:cid	users:write	Change assignment role
DELETE	/api/v1/users/:id/clients/:cid	users:write	Remove assignment
POST	/api/v1/users/:id/invite-console	users:write	Invite a Telegram-only user to the Console
DELETE	/api/v1/users/:id/clients/:cid/environments/:eid	users:write	Remove an environment-scoped grant (create/update fold into the client-assignment routes via environment_id)

Admin: Teams

Method	Path	Permission	Description
GET	/api/v1/teams	teams:read	List teams
POST	/api/v1/teams	teams:write	Create team
GET	/api/v1/teams/:id	teams:read	Get team with members + clients
PUT	/api/v1/teams/:id	teams:write	Update team
DELETE	/api/v1/teams/:id	teams:delete	Delete team (cascades)
POST	/api/v1/teams/:id/members	teams:write	Add member
PUT	/api/v1/teams/:id/members/:uid	teams:write	Change member role
DELETE	/api/v1/teams/:id/members/:uid	teams:write	Remove member
POST	/api/v1/teams/:id/clients	teams:write	Add client
DELETE	/api/v1/teams/:id/clients/:cid	teams:write	Remove client
DELETE	/api/v1/teams/:id/clients/:cid/environments/:eid	teams:write	Remove environment-scoped client coverage from a team

Admin: Roles & Permissions

Method	Path	Permission	Description
GET	/api/v1/roles	roles:read	List roles (system first)
POST	/api/v1/roles	roles:write	Create custom role
GET	/api/v1/roles/:id	roles:read	Get role
PUT	/api/v1/roles/:id	roles:write	Update role (not system roles)
DELETE	/api/v1/roles/:id	roles:delete	Delete role (not system roles)
GET	/api/v1/permissions	roles:read	List all available permissions
GET	/api/v1/roles/:id/usage	roles:read	Get role usage (who and what is bound to this role)

Admin: Service Accounts

Method	Path	Permission	Description
GET	/api/v1/service-accounts	users:read	List service accounts
POST	/api/v1/service-accounts	users:write	Create service account (returns API key once)
GET	/api/v1/service-accounts/:id	users:read	Get service account
PUT	/api/v1/service-accounts/:id	users:write	Update service account
DELETE	/api/v1/service-accounts/:id	users:delete	Delete service account (permanent — to disable reversibly, PUT with is_active=false)
POST	/api/v1/service-accounts/:id/rotate	users:write	Rotate the API key (returns the new key once)

Admin: Audit Log

Method	Path	Permission	Description
GET	/api/v1/audit-log	audit:read	Query audit log (filterable by actor, action, resource, date range)

Webhook Sources (Management)

Method	Path	Permission	Description
GET	/api/v1/webhook-sources	webhooks:read	List webhook sources (paginated)
POST	/api/v1/webhook-sources	webhooks:write	Create webhook source (returns token once)
GET	/api/v1/webhook-sources/:id	webhooks:read	Get webhook source
PUT	/api/v1/webhook-sources/:id	webhooks:write	Update webhook source
DELETE	/api/v1/webhook-sources/:id	webhooks:delete	Delete webhook source
POST	/api/v1/webhook-sources/:id/rotate	webhooks:write	Rotate token (invalidates old URL)
GET	/api/v1/webhook-sources/:id/deliveries	webhooks:read	List recent deliveries for a source

Webhook Receivers (Public, token-authenticated)

These endpoints receive webhook payloads from external tools. No JWT or API key required — authentication is via the token embedded in the URL. Request body limit: 1 MB.

Method	Path	Description
POST	/api/v1/webhooks/gitlab/:token	Receive GitLab webhook (validates X-Gitlab-Token if secret configured)
POST	/api/v1/webhooks/github/:token	Receive GitHub webhook (validates X-Hub-Signature-256 HMAC if secret configured)
POST	/api/v1/webhooks/argocd/:token	Receive ArgoCD webhook (validates X-Argocd-Token if secret configured)

Runbooks

Method	Path	Description
GET	/api/v1/runbooks	List runbooks (client-scoped)
POST	/api/v1/runbooks	Create runbook
GET	/api/v1/runbooks/actions	List available runbook actions
GET	/api/v1/runbooks/:id	Get runbook
PUT	/api/v1/runbooks/:id	Update runbook
DELETE	/api/v1/runbooks/:id	Delete runbook
GET	/api/v1/runbooks/:id/versions	List runbook versions
GET	/api/v1/runbooks/:id/versions/:version	Get specific runbook version
GET	/api/v1/runbooks/:id/access	Get client access for runbook
PUT	/api/v1/runbooks/:id/access	Set client access for runbook
POST	/api/v1/runbooks/:id/execute	Execute runbook on a host
POST	/api/v1/runbooks/:id/preview	Preview runbook execution (dry run)

Runbook Executions

Method	Path	Description
GET	/api/v1/runbook-executions	List runbook executions (filterable by runbook, host, status)
GET	/api/v1/runbook-executions/:id	Get execution details
POST	/api/v1/runbook-executions/:id/cancel	Cancel a running execution

Fleet Management

Agent fleet visibility and self-update rollouts (canary → batched). All routes require agents:read; the rollout mutation routes additionally require agents:write. The agent list is tenant-scoped to the caller's allowed clients.

Method	Path	Permission	Description
GET	/api/v1/fleet/versions	agents:read	Version compatibility info (current backend, minimum supported, recommended agent version)
GET	/api/v1/fleet/agents	agents:read	List agents with computed version-skew status (client-scoped)
GET	/api/v1/fleet/updates	agents:read	List update rollouts
GET	/api/v1/fleet/updates/:id	agents:read	Get a rollout with its per-agent update rows
POST	/api/v1/fleet/updates	agents:write	Create an update rollout (canary + batch, rate-limited)
POST	/api/v1/fleet/updates/:id/pause	agents:write	Pause an in-progress rollout
POST	/api/v1/fleet/updates/:id/resume	agents:write	Resume a paused rollout
POST	/api/v1/fleet/updates/:id/abort	agents:write	Abort a rollout
POST	/api/v1/fleet/agents/:agentID/rotate-credentials	agents:write	Rotate one agent's NATS credentials

Terminal

Method	Path	Description
GET	/api/v1/terminal/ws	WebSocket connect for interactive terminal (browser)
GET	/api/v1/terminal/ws/join	WebSocket join an active session as observer/participant
GET	/api/v1/terminal/sessions	List terminal sessions (?active=true/false)
GET	/api/v1/terminal/sessions/:sessionID	Get terminal session details
DELETE	/api/v1/terminal/sessions/:sessionID	Kill a terminal session
GET	/api/v1/terminal/sessions/:sessionID/recording	Get presigned download URL for session recording
GET	/api/v1/hosts/:id/terminal/access	Check terminal access for a host (allowed logins)
POST	/api/v1/hosts/:id/files/upload	Upload file to host (multipart, max 768 KB)
GET	/api/v1/hosts/:id/files/download	Download file from host (?path=/remote/path)

gRPC endpoints (proxied through nginx on port 443):

RPC	Service	Description
Session	TerminalService	Bidirectional streaming for pc ssh terminal sessions
JoinSession	TerminalService	Bidirectional streaming for pc sessions join
PortForward	TerminalService	Bidirectional streaming for pc ssh -L port forwarding

AI Chat

Method	Path	Description
POST	/api/v1/chat	Send chat message (SSE streaming response)
POST	/api/v1/chat/:conversationID/confirm	Confirm pending tool call in a conversation

Conversations

Method	Path	Description
GET	/api/v1/conversations	List conversations for current user
GET	/api/v1/conversations/:id	Get conversation with decrypted messages
DELETE	/api/v1/conversations/:id	Delete conversation
PATCH	/api/v1/conversations/:id	Update conversation (rename)

Service Desk

Tickets & Kanban

Method	Path	Description
GET	/api/v1/service-desk/tickets	List tickets (ClickHouse, filterable)
GET	/api/v1/service-desk/tickets/:issueKey	Get ticket details
POST	/api/v1/service-desk/tickets	Create ticket (JSM write)
GET	/api/v1/service-desk/kanban	Get kanban board view
GET	/api/v1/service-desk/projects	List fixed-price projects
GET	/api/v1/service-desk/activity	Get recent activity
GET	/api/v1/service-desk/tickets/counts	Get ticket status counts
GET	/api/v1/service-desk/on-call	Get the selected project's current on-call engineer
GET	/api/v1/service-desk/support-hours	Get the client's support-hours usage for the current billing period
GET	/api/v1/service-desk/notification-settings	Get the caller's reporter-notification toggle
PUT	/api/v1/service-desk/notification-settings	Update the caller's reporter-notification toggle
POST	/api/v1/service-desk/reports/export/send	Send a tasks report to the caller's Telegram chat
GET	/api/v1/service-desk/views	List saved views
POST	/api/v1/service-desk/views	Create saved view
GET	/api/v1/service-desk/views/:id	Get saved view
PUT	/api/v1/service-desk/views/:id	Update saved view
DELETE	/api/v1/service-desk/views/:id	Delete saved view
GET	/api/v1/service-desk/tickets/:issueKey/feedback	Get the ticket's CSAT rating
POST	/api/v1/service-desk/tickets/:issueKey/feedback	Submit a CSAT rating
GET	/api/v1/service-desk/tickets/:issueKey/attachments/:attachmentId/download	Download an attachment
GET	/api/v1/service-desk/tickets/:issueKey/attachments/:attachmentId/download-url	Get a signed attachment download URL
GET	/api/v1/service-desk/tickets/:issueKey/attachments/:attachmentId/download-signed	Download an attachment via signed URL
POST	/api/v1/internal/service-desk/ticket-status	Upsert a ticket status overlay (service-account only)
POST	/api/v1/internal/service-desk/ticket-projection	Upsert a ticket projection (service-account only)
POST	/api/v1/internal/notify/ticket-reporter	Send a reporter push DM (service-account only)

Metrics & Reports

Method	Path	Description
GET	/api/v1/service-desk/metrics/sla	SLA metrics
GET	/api/v1/service-desk/metrics/delivery	Delivery metrics
GET	/api/v1/service-desk/metrics/summary	Metrics summary
GET	/api/v1/service-desk/reports/export	Export tickets as CSV

Ticket Sub-resources (JSM proxy)

Method	Path	Description
GET	/api/v1/service-desk/tickets/:issueKey/comments	List comments
POST	/api/v1/service-desk/tickets/:issueKey/comments	Add comment
GET	/api/v1/service-desk/tickets/:issueKey/approvals	List approvals
POST	/api/v1/service-desk/tickets/:issueKey/approvals/:approvalId	Submit approval decision
GET	/api/v1/service-desk/tickets/:issueKey/transitions	List available transitions
POST	/api/v1/service-desk/tickets/:issueKey/transition	Execute status transition
GET	/api/v1/service-desk/tickets/:issueKey/attachments	List attachments
POST	/api/v1/service-desk/tickets/:issueKey/attachments	Add attachment
GET	/api/v1/service-desk/tickets/:issueKey/actions	List audit trail actions for ticket
GET	/api/v1/service-desk/request-types/:requestTypeId/fields	Get fields for a request type

Organization Mappings

Method	Path	Description
GET	/api/v1/service-desk/organizations	List client-scoped organizations
GET	/api/v1/service-desk/admin/organizations	List all organizations (admin)
POST	/api/v1/service-desk/admin/organizations	Create organization mapping
PUT	/api/v1/service-desk/admin/organizations/:id	Update organization mapping
DELETE	/api/v1/service-desk/admin/organizations/:id	Delete organization mapping

Access Audit

Method	Path	Description
GET	/api/v1/admin/access-audit/by-user/:userId	Audit effective access for a user
GET	/api/v1/admin/access-audit/by-client/:clientId	Audit who has access to a client

Auth — Public (5/min rate limit, configurable via PROXIMA_AUTH_RATE_LIMIT)

Method	Path	Description
POST	/api/v1/auth/login	Login with email + password
POST	/api/v1/auth/refresh	Refresh access token
POST	/api/v1/auth/mfa/verify	Verify MFA code during login
POST	/api/v1/auth/forgot-password	Request password reset email
POST	/api/v1/auth/reset-password	Reset password with token
POST	/api/v1/auth/accept-invite	Accept invitation, set password
GET	/api/v1/auth/config	Auth configuration (Google SSO enabled)

Auth — Google OIDC SSO (no auth required)

These endpoints are only registered when PROXIMA_GOOGLE_CLIENT_ID is configured. When disabled, they return 404.

Method	Path	Description
GET	/api/v1/auth/google	Redirect (307) to Google authorization endpoint
GET	/api/v1/auth/google/callback	OAuth 2.0 callback from Google (validates state, exchanges code, issues tokens)
POST	/api/v1/auth/google/exchange	Exchange one-time auth code for JWT tokens
POST	/api/v1/auth/google/cli-mfa	Verify MFA for a CLI Google login

The flow is: frontend redirects to /auth/google -> Google authenticates -> callback creates a one-time code -> frontend exchanges code for tokens via /auth/google/exchange. See Authentication — Google OIDC SSO for the full flow diagram.

Auth — Protected (JWT required)

Method	Path	Description
POST	/api/v1/auth/logout	Logout (revoke session)
GET	/api/v1/auth/me	Current user profile + permissions
PUT	/api/v1/auth/profile	Update current user profile (display name)
POST	/api/v1/auth/mfa/setup	Start MFA setup
POST	/api/v1/auth/mfa/confirm	Confirm MFA with TOTP code
DELETE	/api/v1/auth/mfa	Disable MFA
PUT	/api/v1/auth/password	Change password
GET	/api/v1/auth/sessions	List active sessions
DELETE	/api/v1/auth/sessions/:id	Revoke session
DELETE	/api/v1/auth/sessions	Revoke all sessions
POST	/api/v1/auth/onboarding-tour	Record onboarding-tour state
PUT	/api/v1/auth/ui-preferences	Update the caller's UI preferences
POST	/api/v1/auth/telegram/admin/link-code	Generate a Telegram link code for a user (admin)

Auth — Passkeys (WebAuthn)

Passkey endpoints are only registered when PROXIMA_WEBAUTHN_RP_ID is configured. When disabled, they return 404.

Public (rate-limited with auth routes)

Method	Path	Description
POST	/api/v1/auth/passkey/login/begin	Begin passkey login ceremony
POST	/api/v1/auth/passkey/login/finish	Complete passkey login ceremony
POST	/api/v1/auth/passkey/mfa/begin	Begin passkey MFA verification
POST	/api/v1/auth/passkey/mfa/finish	Complete passkey MFA verification
POST	/api/v1/auth/passkey/accept-invite/begin	Begin passkey registration during invite acceptance
POST	/api/v1/auth/passkey/accept-invite/finish	Complete passkey registration during invite acceptance

Protected (JWT required)

Method	Path	Description
POST	/api/v1/auth/passkey/register/begin	Begin passkey registration for current user
POST	/api/v1/auth/passkey/register/finish	Complete passkey registration
GET	/api/v1/auth/passkey/credentials	List registered passkey credentials
PUT	/api/v1/auth/passkey/credentials/:id	Rename a passkey credential
DELETE	/api/v1/auth/passkey/credentials/:id	Delete a passkey credential

Feedback

Method	Path	Description
POST	/api/v1/feedback	Submit user feedback (creates Jira issue if configured, otherwise logs to structured logs)

Request body:

Field	Type	Required	Description
category	string	Yes	One of: bug, feature_request, ux_issue, suggestion
title	string	Yes	Brief summary (max 200 characters)
description	string	Yes	Detailed description (max 2000 characters)
page_url	string	No	Current page URL (auto-populated by frontend)
screenshot	string	No	Base64-encoded PNG screenshot (max 5MB decoded)

Response (201):

{
  "data": {
    "jira_key": "PDD-42",
    "jira_url": "https://yourorg.atlassian.net/browse/PDD-42"
  }
}

When Jira is not configured, jira_key and jira_url are empty strings. The overall request body limit is 8MB (to accommodate base64-encoded screenshots).

Agent Enrollment & Credentials

Public, token-authenticated agent lifecycle endpoints. Rate-limited by PROXIMA_CREDENTIAL_RATE_LIMIT.

Method	Path	Description
POST	/api/v1/agents/enroll	Enroll an agent with an install token. Returns 409 on an enroll conflict (identity-takeover protection).
POST	/api/v1/agents/credentials/renew/nonce	Issue a server-side renewal challenge nonce
POST	/api/v1/agents/credentials/renew	Renew agent NATS credentials. The nonce becomes mandatory when PROXIMA_REQUIRE_RENEWAL_NONCE=true.

Briefing

Method	Path	Description
GET	/api/v1/briefing	Get the Home page: per-section objects (projects, alerts, on-call, monitors, fleet, vulnerabilities, Service Desk) plus degraded_sections. Optional client_id (403 if not accessible) and period (7d/30d/90d, default 30d)

Healthcheck

Scanner runs, findings, rules, and scores. See Healthcheck.

Method	Path	Description
GET	/api/v1/healthcheck/categories	List healthcheck categories
GET	/api/v1/healthcheck/rules	List healthcheck rules
GET	/api/v1/healthcheck/rules/:ruleID	Get a healthcheck rule
PUT	/api/v1/healthcheck/rules/:ruleID	Update a healthcheck rule
GET	/api/v1/hosts/:hostID/healthcheck/score	Get a host's healthcheck score
GET	/api/v1/hosts/:hostID/healthcheck/runs	List healthcheck runs for a host
GET	/api/v1/hosts/:hostID/healthcheck/runs/latest	Get the latest healthcheck run for a host
GET	/api/v1/hosts/:hostID/healthcheck/runs/:runID	Get healthcheck run detail
GET	/api/v1/hosts/:hostID/healthcheck/runs/:runID/findings	List scanner findings for a run
GET	/api/v1/hosts/:hostID/findings	List scanner findings for a host
POST	/api/v1/hosts/:hostID/healthcheck/trigger	Trigger an on-demand healthcheck run

Integrations

Collector integrations detected on hosts (PostgreSQL, nginx, Docker, …).

Method	Path	Description
GET	/api/v1/integrations	List integrations across the caller's clients
GET	/api/v1/integrations/:integrationID	Get an integration
GET	/api/v1/integrations/:integrationID/hosts	List hosts running an integration
GET	/api/v1/hosts/:hostID/integrations	List integrations on a host

On-Call Schedules

Native on-call: schedules, rotations, overrides, and the resolved "who is on call" view. See Schedules and On-Call Management.

Method	Path	Description
GET	/api/v1/oncall/now	Who is on call now (and next) per schedule
GET	/api/v1/oncall/schedules	List on-call schedules
POST	/api/v1/oncall/schedules	Create an on-call schedule
GET	/api/v1/oncall/schedules/:id	Get an on-call schedule tree
PATCH	/api/v1/oncall/schedules/:id	Update an on-call schedule
DELETE	/api/v1/oncall/schedules/:id	Delete an on-call schedule
GET	/api/v1/oncall/schedules/:id/shifts	Materialize shifts over a range
GET	/api/v1/oncall/schedules/:id/calendar	Layered on-call calendar over a range
POST	/api/v1/oncall/schedules/:id/rotations	Create a rotation
PATCH	/api/v1/oncall/rotations/:id	Update a rotation
DELETE	/api/v1/oncall/rotations/:id	Delete a rotation
PUT	/api/v1/oncall/rotations/:id/users	Replace a rotation's ordered users
POST	/api/v1/oncall/schedules/:id/overrides	Create an override
PATCH	/api/v1/oncall/overrides/:id	Move, resize, or reassign an override
DELETE	/api/v1/oncall/overrides/:id	Delete an override
GET	/api/v1/users/:userID/oncall-profile	Get a user's on-call profile
PUT	/api/v1/users/:userID/oncall-profile	Set a user's on-call phone
POST	/api/v1/users/:userID/oncall-profile/verify-phone	Verify a user's on-call phone

On-Call Readiness

See Readiness Drill and Resolution Safety.

Method	Path	Description
GET	/api/v1/oncall/readiness	List on-call readiness drills fired in a window. Optional from/to (RFC3339) bound fired_at as half-open [from, to); omitted, they default to the last 30 days. from after to is a 400; a window wider than 90 days is clamped to its most recent 90 rather than refused. A readinessMaxRows = 5000 safety cap on the response logs a WARN when hit
GET	/api/v1/oncall/readiness/coverage	List per-client paging coverage
POST	/api/v1/oncall/readiness/:userID/clear-degraded	Manually clear an on-call's readiness-degraded state ("engineer is back")

Escalation Policies & Routes

An alert pages a human if and only if an enabled route matches it. See Escalation and Paging Control.

Method	Path	Description
GET	/api/v1/escalation/policies	List escalation policies
POST	/api/v1/escalation/policies	Create an escalation policy
GET	/api/v1/escalation/policies/:id	Get an escalation policy
PATCH	/api/v1/escalation/policies/:id	Update an escalation policy
DELETE	/api/v1/escalation/policies/:id	Delete an escalation policy
GET	/api/v1/escalation/policies/:id/routes	List the routes linked to a policy
GET	/api/v1/escalation/routes	List escalation routes
POST	/api/v1/escalation/routes	Create an escalation route
PATCH	/api/v1/escalation/routes/:id	Update an escalation route
DELETE	/api/v1/escalation/routes/:id	Delete an escalation route
PUT	/api/v1/escalation/routes/order	Reorder escalation routes (match order is significant)
GET	/api/v1/users/:id/notification-policy	Get a user's notification chains
PUT	/api/v1/users/:id/notification-policy	Replace a user's notification chains

On-Call Cutover (admin)

Gate for migrating a team from shadow paging to Console paging.

Method	Path	Description
GET	/api/v1/admin/oncall-cutover	List cutover gate status per team
POST	/api/v1/admin/oncall-cutover/:teamID	Flip a team to Console paging (live)
DELETE	/api/v1/admin/oncall-cutover/:teamID	Revert a team to shadow paging
GET	/api/v1/admin/settings/oncall	List the on-call configuration in force

Incidents

Incident grouping, the L1 investigation session, and the remediation approval loop.

Method	Path	Description
GET	/api/v1/incidents/:incidentID	Get incident detail
GET	/api/v1/incidents/:incidentID/dependencies	Get the incident's host dependency graph
GET	/api/v1/incidents/:incidentID/session	Get the investigation session
GET	/api/v1/incidents/:incidentID/session/stream	Stream the investigation session (SSE)
POST	/api/v1/incidents/:incidentID/feedback	Submit RCA feedback
GET	/api/v1/incidents/:incidentID/remediation	Get the remediation proposal
POST	/api/v1/incidents/:incidentID/remediation/approve	Approve and execute the remediation proposal
POST	/api/v1/incidents/:incidentID/remediation/reject	Reject the remediation proposal
POST	/api/v1/incidents/:incidentID/remediation/fix-worked	Record the did-the-fix-work verdict on an executed remediation

L1 Triage (admin)

Method	Path	Description
GET	/api/v1/l1/models	List the allowlisted L1 triage models
PUT	/api/v1/l1/settings/triage-model	Set the global L1 triage model

Version Currency

Tracks installed software versions against a product catalog and surfaces CVE exposure.

Method	Path	Description
GET	/api/v1/versions	Version-currency dashboard
GET	/api/v1/versions/products/:slug	Version-currency drill-down for a product
GET	/api/v1/versions/products/by-name/:name	Version-currency drill-down by product name
POST	/api/v1/versions/triage	Triage a product's CVEs for a client
POST	/api/v1/versions/sync	Sync the endoflife.date catalog now
GET	/api/v1/versions/aliases	List catalog aliases
POST	/api/v1/versions/aliases	Upsert a catalog alias by local name
PUT	/api/v1/versions/aliases/:id	Map or ignore a catalog alias
GET	/api/v1/versions/unmatched	List unmatched inventory names (triage queue)
POST	/api/v1/versions/unmatched/dismiss	Dismiss an unmatched inventory name
GET	/api/v1/versions/export	Export the version-currency report
POST	/api/v1/versions/export	Export a selected version-currency report

Pull Sources (admin)

Cloud-provider change feeds pulled on a schedule (rather than pushed by webhook).

Method	Path	Description
GET	/api/v1/pull-sources	List pull sources
POST	/api/v1/pull-sources	Create a pull source
GET	/api/v1/pull-sources/:id	Get a pull source
PUT	/api/v1/pull-sources/:id	Update a pull source
DELETE	/api/v1/pull-sources/:id	Delete a pull source

Telegram Groups (admin)

Method	Path	Description
GET	/api/v1/admin/telegram/groups	List discovered Telegram groups
POST	/api/v1/admin/telegram/groups/:chat_id/bind	Bind a group to a client or team
PATCH	/api/v1/admin/telegram/groups/:chat_id	Update group config
DELETE	/api/v1/admin/telegram/groups/:chat_id	Unbind a group
GET	/api/v1/admin/telegram/groups/:chat_id/topics	List the chat's discovery-staged forum topics and its current per-kind routing
PUT	/api/v1/admin/telegram/groups/:chat_id/topics/:kind	Point one kind (alerts|tasks) at one staged topic
DELETE	/api/v1/admin/telegram/groups/:chat_id/topics/:kind	Clear a kind's route (it falls back to the binding's thread)

Telegram Ops Bot (service-account only)

Called by the ops bot with its service-account API key, not by browsers. See Ops Bot.

Method	Path	Description
POST	/api/v1/telegram/ops/discover	Register a discovered Telegram group
POST	/api/v1/telegram/ops/bind	Bind a Telegram group to a client
POST	/api/v1/telegram/ops/bind-team	Bind a Telegram group to a team
POST	/api/v1/telegram/ops/callback	Alert action callback (ack / resolve / silence from a bot button)
POST	/api/v1/telegram/ops/topic	Point one routing kind at the forum topic /topic was run in
POST	/api/v1/telegram/ops/engage	Reactive listening-bot engage
POST	/api/v1/internal/telegram/notify-targets	Resolve Telegram notification targets
GET	/api/v1/internal/notification-config	Read a notification pipeline config value

Global Notification Settings (admin)

Method	Path	Description
GET	/api/v1/admin/notification-settings	List global notification settings
PUT	/api/v1/admin/notification-settings/:key	Set a global notification setting

Voice Callbacks (public, provider-signed)

Twilio callbacks. Authenticated by the X-Twilio-Signature HMAC, not by JWT. See Voice Paging.

Method	Path	Description
POST	/api/v1/twilio/voice/twiml/:callID	Serve the call-flow TwiML
POST	/api/v1/twilio/voice/gather	DTMF gather — the on-call presses 1 to acknowledge (2 no longer resolves; it re-gathers)
POST	/api/v1/twilio/voice/status	Call status callback

Kubernetes Access

See Kubernetes Access.

Method	Path	Description
POST	/api/v1/kube/token	Issue a short-lived kube proxy token for pc kube
GET	/api/v1/kube/role-metadata	Role-authoring metadata (namespaces, resources, verbs) for the kube_spec editor

SSH Certificates

Backs pc ssh certificate-based access. See OpenSSH Architecture.

Method	Path	Description
POST	/api/v1/ssh/certs	Issue an SSH user certificate
GET	/api/v1/ssh/host-ca	Get the SSH Host CA public key

System Status

Method	Path	Description
GET	/api/v1/system/status	System status (dependency health as seen by the backend)

Authentication

All /api/v1/ endpoints (outside /auth) support two authentication methods:

• JWT Bearer: Authorization: Bearer <jwt> (user sessions)
• API Key: X-API-Key: <key> (service accounts)

Pagination

List endpoints support pagination with the following query parameters:

Parameter	Default	Max	Description
page	1	—	Page number
per_page	20	100	Items per page