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_VALUE

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. /metrics follows the same OIDC/API-token protection as the read APIs.

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.13.0",
    "interval_seconds": 30
  },
  "host": {
    "hostname": "nuc01",
    "meta": {
      "docker.version": "26.1.0",
      "docker.api_version": "1.45"
    }
  },
  "services": [
    {
      "external_id": "abc123",
      "name": "gitea",
      "kind": "container",
      "image": "gitea/gitea:latest",
      "image_digest": "sha256:...",
      "state": "running",
      "health": "healthy",
      "health_detail": "",
      "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 state is required and cannot be removed
• 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.

Optional query parameters:

• limit: positive integer, capped at 500
• offset: non-negative integer; without limit, Trove uses 500
• since: Unix timestamp or RFC3339 time, filtering on updated_at

When pagination or filtering is used, the response includes a pagination object with limit, offset, count, and next_offset when another page may exist.

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.

Events default to the newest 100 rows. Optional query parameters are limit (maximum 500), offset, kind, and since (Unix timestamp or RFC3339).

GET /api/v1/me

Returns the current dashboard/API authentication state.

Auth: OIDC session or TROVE_API_TOKEN when OIDC is enabled.

Example:

TROVE_API_TOKEN=TROVE_API_TOKEN_VALUE \
  curl --oauth2-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.

GET /metrics

Returns Prometheus text format. When OIDC is enabled, use TROVE_API_TOKEN for scrapes.

Current metric families include process uptime/memory/goroutines, accepted reports, SQLite database size, agent status, service health/state/kind, event counts, and image freshness verdicts. See the in-repo API documentation for the exact metric names and a scrape example.

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.