Skip to content

A Pinboard node serves three surfaces on one port. Every node in a fleet serves all of them; put any number behind one load balancer URL.

https://pinboard.example.com

Surfaces

SurfacePathsCallerAuth
Routing/{namespace}/{id}/...Browsers, apps, other instancesData-plane rules, optional
Worker APIPOST /registry/register, heartbeat, release, tag, deregisterpinned workerspinboard:worker scope
Operator API/registry/health, workers, overview, stats, wind_down, drain, undrain, /metricsDashboards, scriptspinboard:operator scope
Probes/healthz, /readyzLoad balancers, KubernetesNone

Pinboard also calls each worker. Those endpoints are listed in Worker callbacks.

Endpoints

MethodPathPage
ANY/{namespace}/{id}{rest}Proxy a request
POST/registry/registerRegister a worker
POST/registry/heartbeatHeartbeat
POST/registry/releaseRelease placements
POST/registry/tagTag a placement
POST/registry/deregisterDeregister
GET/registry/healthNode health
GET/registry/workersList workers
GET/registry/overviewFleet overview
GET/registry/statsWorker stats
POST/registry/wind_downWind down placements
POST/registry/drainDrain a client
POST/registry/undrainUndrain a client
GET/metricsPrometheus metrics
GET/healthzLiveness
GET/readyzReadiness

Conventions

  • Request and response bodies are JSON (content-type: application/json) unless a page says otherwise.
  • Request bodies are capped at 1 MiB, 8 MiB for /registry/register.
  • /registry/* routes match path and method exactly. A wrong method answers 404 {"error":"not found"}. /healthz and /readyz answer any method.
  • Times on the wire: expiresInMs and uptimeMs are milliseconds; deadline and drainDeadline are relative seconds (fractional); expiry and degradedSince are Unix epoch milliseconds.
  • Placement epochs are decimal strings, compared numerically.
  • Failures return {"error": "..."}. See Errors.

Base path

With the createPinboard({ basePath }) option set (for example /v2; there is no env variable for it), every route except /metrics lives under it: /v2/registry/register, /v2/{namespace}/{id}. A request outside the base path answers 404 {"error":"not found"}.

Modes

Two server options change request shapes. Pages mark the differences.

ModeOptionEffect
Single-hostnamedefaultOne placement world. Registrations carry no hostname.
Hostname-awarePINBOARD_HOSTNAME_AWARE=1Workers register a hostname and per-namespace env. Requests route by the Host header.