vantage-docs/docs/reference/rest-api.md

id, title, sidebar_label

id	title	sidebar_label
rest-api	REST API	REST API

The control plane's HTTP API, on port 8080. The web UI is a client of it and has no privileges it does not.

Authentication

Most endpoints take a session: an opaque 32-byte token in the km_session cookie, with the body in Redis for 24 hours.

One endpoint takes a bearer token instead the External Secrets Operator read path.

Unauthenticated

GET  /install            /install.ps1        # dynamic agent install scripts
GET  /update             /update.ps1
GET  /auth/bootstrap-status
POST /auth/bootstrap     /auth/login  /auth/logout
GET  /auth/me            /auth/oidc/start    /auth/oidc/callback
GET  /api/secrets/:group/values               # bearer token (ESO)

/install and /install.ps1 take server_id and token as query parameters and return a shell script with the newest agent version substituted in.

POST /auth/bootstrap works only while the database has no users.

Session-authenticated, under /api

Servers

GET,POST   /servers
GET,POST   /servers/new
GET,DELETE /servers/:id
POST       /servers/:id/generate-key
POST       /servers/:id/update-agent
POST       /servers/:id/apply-updates

Keys

GET,POST   /keys
GET,DELETE /keys/:id
GET        /keys/:id/private-key
POST       /keys/:id/assign
DELETE     /keys/:id/assign/:serverId

Workflows and steps

GET,POST       /steps
PUT,DELETE     /steps/:id
GET            /steps/:id/export
POST           /steps/import · /steps/seed-defaults · /steps/parse
GET            /steps/usage
GET,POST       /workflows
GET,PUT,DELETE /workflows/:id
POST           /workflows/:id/run
GET            /workflows/:id/runs
GET            /runs/:runId
POST           /runs/:runId/cancel
GET            /runs/:runId/servers/:serverId/logs
GET            /runs/:runId/servers/:serverId/logs/stream

PUT and DELETE on a step whose source is default answer 409. See Workflows.

Monitors and channels

GET,POST       /monitors
GET,PUT,DELETE /monitors/:id
GET            /monitors/:id/incidents · /monitors/:id/uptime
GET,POST       /channels
PUT,DELETE     /channels/:id
POST           /channels/:id/test

Secrets

GET,POST       /secrets
GET,PUT,DELETE /secrets/:group
POST           /secrets/:group/reveal
DELETE         /secrets/:group/:key

Console

POST /console/connect
GET  /console/tunnel        # websocket

Other

GET  /audit
GET  /agent/latest-version
GET,PUT /settings                            (owner|admin)
POST /settings/secrets-token                 (owner|admin)
GET  /license
POST /license                                (self-hosted only)
GET,POST   /org/users
PUT        /org/users/:id/role
DELETE     /org/users/:id
GET,PUT    /org/oidc                         (owner|admin)

Notable refusals

Endpoint	Condition	Status
POST /license	deployment is cloud	409 cloud_managed
PUT,DELETE /steps/:id	the step's source is default	409
PUT /org/users/:id/role, DELETE /org/users/:id	the user's auth source is hq	409

POST /license is exempt from the licence check, so pasting a valid licence works while the current one is expired that is the way out of degraded mode.

Multi-tenancy

Every request is scoped to the instance resolved from the session. On a multi-tenant deployment, a request arriving at <slug>.vantage.<tld> also has its host checked against the session's instance, and a mismatch is rejected.

Errors

Errors are JSON with an error field. Customer-facing endpoints in the HQ API answer 404 rather than 403 for another account's resource, because a 403 confirms the resource exists; the control plane's own API is single-tenant per session and does not need that distinction.

Admin API

Vantage HQ is a separate hosted service with its own API and its own session. Its behaviour is described in the Vantage HQ section rather than here; the two services share no session and no authentication.