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

Environments

Method	Path	Description
POST	/api/v1/clients/:id/environments	Create environment for client
PUT	/api/v1/environments/:envId	Update environment
DELETE	/api/v1/environments/:envId	Delete environment
GET	/api/v1/environments/:id/hosts	List hosts in environment

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)
GET	/api/v1/clusters/:clusterID	Get single cluster with full details
GET	/api/v1/clusters/:clusterID/nodes	List nodes in a cluster (with host linkage)
GET	/api/v1/clusters/:clusterID/namespaces	List namespaces in a cluster
GET	/api/v1/clusters/:clusterID/workloads	List workloads in a cluster (filterable by namespace/kind)
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/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 and are scoped to the caller's allowed clients. See Kubernetes Inventory for full documentation.

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)

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

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

Aggregation Semantics

• 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 metric annotation
GET	/api/v1/annotations	List annotations for host/environment
DELETE	/api/v1/annotations/:id	Delete annotation (creator only)

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

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
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)

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

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

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)
GET	/api/v1/hosts/:id/alerts	alerts:read	Alert groups for a host
GET	/api/v1/environments/:id/alerts	alerts:read	Alert groups for an environment
GET	/api/v1/clients/:id/alerts	alerts:read	Alert groups for a client
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

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

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

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

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

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	Soft-delete service account

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)

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

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

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

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

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).

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