Prometheus — API Surface#

API types#

REST/HTTP, Protobuf-over-HTTP (remote read/write), OTLP (OpenTelemetry), CLI (two binaries), Library

Prometheus exposes multiple API surfaces: a versioned REST API for queries and metadata, a binary protobuf-over-HTTP protocol for remote read/write, an OTLP receiver for OpenTelemetry metrics ingestion, and two CLI tools. It is also consumed as a library by the wider ecosystem (Thanos, Cortex, Mimir) via its public Go packages.

REST/HTTP API#

Router#

• Router: Custom github.com/prometheus/common/route.Router (wraps julienschmidt/httprouter)
• Route registration: Explicit programmatic registration in two places:
  • web/web.go (New function, lines 458–609): top-level routes
  • web/api/v1/api.go (API.Register, lines 392–483): /api/v1/* routes
• Mount path: /api/v1/ (or <route-prefix>/api/v1/)

Middleware chain#

Applied in this order (outermost first):

1. OpenTelemetry tracing — otelhttp.NewHandler wraps the entire mux
2. Stack tracer — withStackTracer logs panics with goroutine stacks
3. Prometheus instrumentation — promhttp.InstrumentHandlerCounter / Duration / ResponseSize per handler
4. Readiness gate — testReady wrapper blocks requests when TSDB is not yet ready
5. Compression — httputil.CompressionHandler (gzip) on query endpoints and federation
6. OpenAPI wrapper — OpenAPIBuilder.WrapHandler records API coverage on every handler

Authentication#

Authentication is delegated to prometheus-community/toolkit/web (the FlagConfig{WebConfigFile} path). The web config file (--web.config.file) supports TLS with client certificate verification (mTLS), HTTP Basic Auth, and per-user bcrypt hashing. No auth is applied at the Go route level; the http.Server is wrapped by the toolkit’s ServeMultiple which handles TLS setup.

CORS is supported via a configurable origin regex (--web.cors.origin), applied at handler construction.

Key endpoints#

Top-level routes (registered directly on the router mux):

API v1 routes (all under /api/v1/):

Write receiver routes (gated by separate feature flags):

Protobuf-over-HTTP (Remote Read/Write)#

Prometheus does not use gRPC. The remote read/write protocol uses HTTP POST with protobuf-encoded bodies, snappy-compressed.

Proto files#

• prompb/types.proto — Core types: TimeSeries, Label, Sample, Exemplar, Histogram, LabelMatcher, ReadHints, ChunkedSeries
• prompb/remote.proto — Wire protocol messages: WriteRequest, ReadRequest, ReadResponse, ChunkedReadResponse
• prompb/io/prometheus/write/v2/types.proto — Remote Write 2.0 format (newer protocol revision)
• prompb/io/prometheus/client/metrics.proto — Prometheus exposition format (OpenMetrics-compatible)

There are no gRPC service definitions in these proto files. All transport is plain HTTP.

Remote Write protocol#

• Endpoint (outbound): Configured in prometheus.yml under remote_write:. Prometheus POSTs to external receivers.
• Endpoint (inbound): POST /api/v1/write — accepts WriteRequest (v1) or writev2.Request (v2). Content-Type negotiated via X-Prometheus-Remote-Write-Version header.
• Handler: storage/remote.NewWriteHandler — accepts either protobuf message type, snappy-decompresses, and appends via storage.Appendable.

Remote Read protocol#

• Endpoint: POST /api/v1/read
• Response types: SAMPLES (single protobuf response) or STREAMED_XOR_CHUNKS (chunked streaming). Negotiated via accepted_response_types in the request.
• Handler: storage/remote.NewReadHandler — backed by storage.SampleAndChunkQueryable.

OTLP Write (OpenTelemetry)#

• Endpoint: POST /api/v1/otlp/v1/metrics
• Handler: storage/remote.NewOTLPWriteHandler — accepts pmetricotlp.ExportRequest, converts to Prometheus format (delta-to-cumulative conversion optional via feature flag), appends via storage.AppendableV2.

CLI#

prometheus binary (cmd/prometheus)#

• Framework: github.com/alecthomas/kingpin/v2
• Mode control: Single --agent boolean flag switches between Server mode and Agent mode
• Flag categories and counts (~78 total):

Server-only and agent-only flags produce a clear error if used in the wrong mode (enforced via PreAction).

promtool binary (cmd/promtool)#

• Framework: github.com/alecthomas/kingpin/v2
• Top-level commands:

Plugin / Extension System#

Prometheus does not have a general-purpose plugin system in the traditional sense (no hashicorp/go-plugin, no WASM, no shared libraries). Extension is achieved through three interface-based mechanisms:

Service Discovery plugins#

• Mechanism: discovery.Config interface + discovery.RegisterConfig(Config) global registry
• Extension point: Each SD provider implements Config (with NewDiscoverer(DiscovererOptions) and NewDiscovererMetrics(...)) and self-registers via init() in discovery/install/install.go
• Examples: discovery/kubernetes, discovery/aws, discovery/consul, discovery/azure — 30+ built-in providers, all using the same pattern
• Third-party: External binaries can implement the HTTP SD endpoint (discovery/http) to feed target groups without modifying Prometheus itself

Storage backends#

• Mechanism: storage.Storage, storage.Queryable, storage.Appendable interfaces
• Extension point: The fanout storage accepts any storage.Storage implementation. Remote write/read adapters allow any HTTP-compatible backend.
• Examples: Thanos, Cortex, Mimir all implement storage.Queryable and run the Prometheus PromQL engine against their own storage backends

Remote write receivers (third-party)#

• Mechanism: Any HTTP server that accepts protobuf WriteRequest at the remote write endpoint URL
• Protocol: Documented in prompb/remote.proto; no Go interface required
• Examples: InfluxDB, Elasticsearch, Cortex, VictoriaMetrics all implement this receiver

Library API#

The wider ecosystem uses Prometheus as a Go library, not just as a binary. Key public packages:

API style: Constructor functions + option structs. No fluent builder or functional options pattern at the top level; configuration is explicit through typed structs. Example:

eng := promql.NewEngine(promql.EngineOpts{
    MaxSamples:    50_000_000,
    Timeout:       2 * time.Minute,
    LookbackDelta: 5 * time.Minute,
})
q, _ := eng.NewInstantQuery(ctx, queryable, nil, expr, time.Now())
res := q.Exec(ctx)

Backward compatibility: Prometheus follows semver-like conventions but the module path is github.com/prometheus/prometheus (no /v2). Breaking changes are rare and announced through the CHANGELOG. The ecosystem projects (Thanos, Cortex) pin specific commits or minor versions rather than relying on formal guarantees.

Notable API design observations#

1. Self-describing via OpenAPI. The /api/v1/openapi.yaml endpoint returns a live OpenAPI 3.x spec generated by OpenAPIBuilder, which wraps every registered handler. This means the spec is always synchronized with the actual routes — no code generation drift.

2. Dual content-type on write endpoints. /api/v1/write accepts both Remote Write 1.0 (application/x-protobuf) and 2.0 (application/x-protobuf; proto=io.prometheus.write.v2.Request), negotiated via the X-Prometheus-Remote-Write-Version header. This backward compatibility design is a deliberate protocol versioning strategy without path versioning.

3. Admin API gating. Destructive admin operations (delete_series, clean_tombstones, snapshot) are registered as normal routes but require --web.enable-admin-api. Without the flag, the routes are still registered but return 403. This means they appear in the OpenAPI spec unconditionally while being runtime-gated.

4. Agent mode API is a strict subset. The wrapAgent wrapper (vs wrap) signals which endpoints are available in agent mode. In agent mode, query endpoints return 503 since there is no query engine. The route table itself does not change between modes.

5. No versioning of the HTTP API beyond v1. There is no /api/v2/ path. New endpoints are added to the /api/v1/ namespace; breaking changes are avoided by additive design (new optional parameters, new response fields).