API

The Dungbeetle cloud server exposes a small HTTP API under /api/v1 for ingesting runs, managing hosted baselines, and reading analytics. In normal use you don't call it directly — dungbeetle push / push-baselines do — but it's documented here for integrations and tooling. For the concepts behind it, see Cloud server; to run your own, see Self-hosting. Coding agents can drive run triage and baseline approval over the MCP server, which is a thin client over this API.

Base URL: your server origin, e.g. https://dungbeetle.example.com. All examples use http://localhost:4317 (the default).

Authentication

Every /api/v1 route uses HTTP Basic auth: the repository's client_id is the username and client_secret is the password. The credential pair resolves to a single repository, and everything a request can read or write is scoped to that repository. Mint a pair by creating a repository in the web UI (see Cloud server).

curl -u "$DUNGBEETLE_CLIENT_ID:$DUNGBEETLE_CLIENT_SECRET" \
  http://localhost:4317/api/v1/baselines

• Missing/malformed Authorization header → 401 with WWW-Authenticate: Basic.
• Invalid credentials → 401.
• Repeated failures from the same client/IP are throttled → 429 with a Retry-After header. Successful requests never count toward the limit.

The /api/v1 routes all require client credentials; /health and /healthz are the unauthenticated probes. (The web UI under / and /ui has its own session-cookie auth — see Cloud server.)

Conventions

• Requests and responses are JSON (Content-Type: application/json).
• Ingest endpoints (POST) are bounded by DUNGBEETLE_MAX_BODY_BYTES (default 25 MiB); larger bodies get 413.
• Errors return { "error": "<message>" } with the relevant 4xx status.

Endpoints

Method	Path	Auth	Purpose	Page
GET	/health	none	Liveness check	Health
GET	/healthz	none	Readiness + version/uptime	Health
POST	/api/v1/runs	client creds	Ingest a run report	Runs
GET	/api/v1/runs/:id	client creds	Fetch a stored run + report	Runs
GET	/api/v1/runs/:id/screenshots/:artifactId	client creds	Fetch an offloaded screenshot (PNG) by id	Screenshots
POST	/api/v1/screenshots/probe	client creds	Which screenshot digests the repo still needs	Screenshots
PUT	/api/v1/screenshots/:digest	client creds	Upload a screenshot artifact (content-addressed)	Screenshots
POST	/api/v1/runs/:id/review	client creds	Approve/reject a run (optionally promote)	Runs
GET	/api/v1/repository	client creds	Identify the authenticated repository	Repository
GET	/api/v1/analytics	client creds	Trend + per-target flakiness	Repository
GET	/api/v1/usage	client creds	Current-period usage vs plan limits	Repository
POST	/api/v1/baselines	client creds	Upload a baseline version	Baselines
GET	/api/v1/baselines	client creds	List targets + latest version	Baselines
GET	/api/v1/baselines/:target	client creds	Version history for a target	Baselines
GET	/api/v1/baselines/:target/latest	client creds	Latest version + snapshot	Baselines
GET	/api/v1/baselines/:target/versions/:version	client creds	A specific version	Baselines

The status codes and plan limits apply across all endpoints.

Health probes

GET /health

Unauthenticated liveness probe.

200 OK
{ "status": "ok", "apiVersion": 1 }

GET /healthz

Unauthenticated readiness probe with build/runtime info for post-deploy verification. version reflects DUNGBEETLE_VERSION (or the package version); uptime is in seconds.

200 OK
{ "status": "ok", "version": "1.2.3", "uptime": 42 }