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

Only report ingest requires authentication.

Use:

Authorization: Bearer trove_...

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.

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.

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.

Example:

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

Events include state, health, and agent transitions.

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.