API Reference

API Reference

Trove exposes a small HTTP API.

The API is used by the dashboard and agents. It is also useful for scripts.

Authentication

Agent report ingest always requires a per-agent bearer token:

Authorization: Bearer <agent-token>

When OIDC is enabled, the dashboard/read APIs also require either a valid browser session or the optional TROVE_API_TOKEN bearer token. See Authentication.

/healthz, /oauth2/login, /oauth2/callback, and /oauth2/logout remain unauthenticated by design.

GET /healthz

Health check endpoint.

Example:

curl http://SERVER:8080/healthz

Use this for container health checks, reverse proxy checks, and uptime monitoring.

POST /api/v1/report

Agent report ingest endpoint.

Requires bearer token.

Request body is a model.Report JSON object.

Simplified example:

{
  "agent": {
    "name": "docker-nuc01",
    "platform": "docker",
    "version": "0.7.0",
    "interval_seconds": 30
  },
  "host": {
    "hostname": "nuc01",
    "meta": {
      "docker_version": "26.1.0"
    }
  },
  "services": [
    {
      "external_id": "abc123",
      "name": "gitea",
      "kind": "container",
      "image": "gitea/gitea:latest",
      "image_digest": "sha256:...",
      "state": "running",
      "health": "healthy",
      "ports": [
        { "host": 3000, "container": 3000, "proto": "tcp" }
      ],
      "labels": {
        "com.docker.compose.project": "gitea"
      }
    }
  ]
}

Response:

{
  "ok": true,
  "services": 1
}

Validation rules include:

• agent.name required
• agent.platform required
• host.hostname required
• each service needs external_id
• service external_id must be unique within the report
• service kind must be recognized
• service health must be agent-reportable

Agents cannot report health="stale". Stale is server-derived.

GET /api/v1/services

Returns catalog services for the dashboard/API.

Auth: OIDC session or TROVE_API_TOKEN when OIDC is enabled.

Example:

curl http://SERVER:8080/api/v1/services

The response includes service details joined with host/agent context and derived freshness where available.

GET /api/v1/agents

Returns known agents and heartbeat information.

Auth: OIDC session or TROVE_API_TOKEN when OIDC is enabled.

Example:

curl http://SERVER:8080/api/v1/agents

Useful for checking whether agents are reporting and what platform/version they run.

GET /api/v1/events

Returns recent activity events.

Auth: OIDC session or TROVE_API_TOKEN when OIDC is enabled.

Example:

curl http://SERVER:8080/api/v1/events

Events include state, health, and agent transitions.

GET /api/v1/me

Returns the current dashboard/API authentication state.

Auth: OIDC session or TROVE_API_TOKEN when OIDC is enabled.

Example:

curl -H "Authorization: Bearer $TROVE_API_TOKEN" http://SERVER:8080/api/v1/me

Typical OIDC session response:

{
  "authenticated": true,
  "via": "oidc",
  "email": "user@example.com",
  "subject": "..."
}

Typical API token response:

{
  "authenticated": true,
  "via": "api-token"
}

POST /oauth2/logout

Clears the local trove_session cookie and redirects to the provider's OIDC end_session_endpoint when available.

This endpoint is intended for browsers. The dashboard uses a real POST form so the browser follows the IdP logout redirect.

Service kinds

Known service kinds:

• container
• pod
• vm
• lxc
• process
• deployment
• statefulset
• daemonset

Health values

Agent-reportable health values:

• healthy
• unhealthy
• unknown

Server-derived health value:

• stale

Synthetic removed state

Agents do not send removed.

The server sets:

state = "removed"

when a previously known service is absent from a full-state report.