API and SDK¶

This page lists BenchDB's HTTP endpoints and the generated Go and TypeScript clients. It is for people writing integrations or read automation. To publish results, use benchdb results submit instead; see Submitting results.

The server builds its OpenAPI document from the same Huma route definitions that serve requests, so the document always matches the running server. The generated clients are checked in and reviewed like code.

Discover the API¶

A running server serves these pages. Add the path prefix first if the server uses one.

benchdb openapi prints the same 3.1 document without a server, and benchdb openapi --downgrade prints the 3.0 version.

Any language can call the HTTP API from these documents. Submission still goes through the CLI so that every project gets the same validation, token handling, glob expansion, and concurrency limits.

Endpoints¶

Reads need no credential. Writes need one. Token and alert-rule endpoints need a credential that belongs to a user. Authentication and tokens lists the exact checks and failure codes.

Results¶

Benchmarks, series, and history¶

Each item from GET /api/benchmarks has a status (regressed, improved, stable, or insufficient) and two fields that explain it:

• change_machine is the machine whose history sets the status.
• change_percent is how far that machine's latest point moved from its history window's mean, as a percent of the mean. A positive value means the number went up. It is null when the machine histories share no unit or the mean is zero.

The page also has status_counts for every benchmark that matches the other filters, statuses_pending while a status recompute is queued, and next_page_cursor. Regression analysis explains how statuses are set.

CI reports¶

CI reporting explains selectors, baselines, and status.

Sign-in, tokens, and alerts¶

Generated clients¶

The repository generates two clients from the OpenAPI 3.1 document:

• a Go client in sdk/go/benchdb, generated with oapi-codegen-dd/v3
• a TypeScript client and models in web/src/lib/api, generated with Orval

This Go program lists regressed benchmarks with the machine and size of each change:

package main

import (
    "context"
    "fmt"
    "log"
    "net/http"

    "go.kenn.io/benchdb/sdk/go/benchdb"
)

func main() {
    client, err := benchdb.NewHTTPClient("https://benchdb.example", http.DefaultClient)
    if err != nil {
        log.Fatal(err)
    }
    status := benchdb.ListBenchmarksQueryStatusRegressed
    resp, err := client.ListBenchmarksWithResponse(context.Background(), &benchdb.ListBenchmarksRequestOptions{
        Query: &benchdb.ListBenchmarksQuery{Status: &status},
    })
    if err != nil {
        log.Fatal(err)
    }
    if resp.JSON200 == nil {
        log.Fatalf("list benchmarks: HTTP %d", resp.StatusCode)
    }
    for _, b := range resp.JSON200.Benchmarks {
        if b.ChangePercent != nil && b.ChangeMachine != nil {
            fmt.Printf("%s: %+.1f%% on %s\n", b.Name, *b.ChangePercent, *b.ChangeMachine)
        }
    }
}

After changing an API route or model, regenerate the OpenAPI documents and both clients:

make codegen

make codegen-check regenerates everything and fails if the result differs from what is committed:

make codegen-check

No Python client¶

BenchDB has no maintained Python client. Python benchmark suites should write BenchDB result JSON and run benchdb results submit. Read automation can call the HTTP API directly or use the Go client.