Skip to main content

WebUI Runbook Endpoints

Private Stack Exposure​

Remote benchmark workers must reach the Metrum Insights control plane over a public URL. When you run a private or local stack, expose PostgREST before launch and use the public HTTPS URL for METRUM_PUBLIC_API_URL, INSIGHTS_API_URL, and INSIGHTS_CONTROL_PLANE_URL:

cloudflared tunnel --url http://localhost:${POSTGREST_PORT:-3000}
export METRUM_PUBLIC_API_URL="https://<cloudflared-host>.trycloudflare.com"
export INSIGHTS_API_URL="$METRUM_PUBLIC_API_URL"
export INSIGHTS_CONTROL_PLANE_URL="$METRUM_PUBLIC_API_URL"
curl -fsS "$METRUM_PUBLIC_API_URL/" >/dev/null

Do not give a remote worker localhost, 127.0.0.1, host.docker.internal, or a private-only DNS name. Keep the tunnel alive through onboarding, polling, result upload, and teardown; expose any private package/WebUI endpoint through a public URL too when the worker downloads artifacts from that stack.

These endpoints sit in front of the control plane for browser, report, and worker-bootstrap workflows. They should be documented with authentication, expected caller, and response examples.

Cloud Onboarding​

  • POST /api/cloud/onboard: managed provider onboarding used for disposable Shadeform and RunPod benchmark workers.
  • GET /api/scripts/worker-startup.sh: startup script fetched by cloud workers during managed onboarding.
  • GET /api/packages/:filename: static worker/runtime artifact download path.

Reports​

  • POST /api/ai-eval: AI-assisted run report text for a benchmark run.
  • GET /api/benchmark-report/:runId: benchmark run HTML report.
  • GET /api/benchmark-report/:runId?ai=1: benchmark run HTML report with AI assistance.
  • GET /api/run-report/:runId: benchmark run spreadsheet export.
  • GET /api/project-report/:projectId: project-level HTML report.
  • GET /api/project-report/:projectId?ai=1: project-level HTML report with AI assistance.
  • GET /api/project-run-report/:projectId: project-level spreadsheet export.
  • GET /api/deterministic-benchmark-report/:runId: deterministic benchmark report.
  • GET /api/deterministic-benchmark-report/:runId/pdf: deterministic benchmark report PDF.
  • GET /api/project-deterministic-benchmark-report/:projectId: deterministic project report.
  • GET /api/project-deterministic-benchmark-report/:projectId/pdf: deterministic project report PDF.

Job Artifacts​

  • GET /api/jobs/:jobId/sut.csv: system-under-test CSV for a job.
  • GET /api/jobs/:jobId/logs.txt: combined framework and tool logs for a job.

Hardware Sizer​

  • GET /api/sizer/status: Sizer configuration and workspace enablement status.
  • GET /api/sizer/health: diagnostic readiness check when an enabled Sizer appears unavailable.
  • GET /api/sizer/gpu-skus: catalog GPU SKUs available for sizing requests.
  • POST /api/sizer/solve: structured solve request for sizing recommendations or scalar targets.
  • POST /api/sizer/agent: natural-language sizer agent request.

Health And Runtime​

  • GET /api/health: WebUI health check.
  • GET /api/version: WebUI build/runtime version.

Do not add WebUI endpoints to this section just because they exist. Add them when a supported runbook calls them.