Module api 

The daemon’s JSON API, version 1: the request and response types every client deserializes, and the principal a transport authenticates. Plain data only: no I/O, no Docker or GitHub types, no secrets.

Routes, all under the authenticated principal:

Route	Body
GET /v1/status	Status
POST /v1/repositories/{owner}/{name}/pause?PauseQuery	Paused; 409 Busy while it runs a job
POST /v1/repositories/{owner}/{name}/resume	none, 204
POST /v1/profiles/{name}/reseed	none, 202; 409 while it reseeds; cache.reseeded when done
POST /v1/caches/{name}/clean	none, 204; 409 Busy while a runner uses it
GET /v1/config	ConfigFile
POST /v1/config/check	TOML in, ConfigCheck
PUT /v1/config	TOML in, ConfigCheck; 422 ConfigCheck when invalid
GET /v1/doctor	Doctor
POST /v1/shutdown	ShutdownRequest in, 202
GET /v1/jobs?JobQuery	JobPage
GET /v1/jobs/{id}	Job
GET /v1/jobs/{id}/samples	SampleSeries
GET /v1/jobs/{id}/logs?LogQuery	text/plain, one line per log line
GET /v1/host/samples?HostSampleQuery	HostSamples
GET /v1/stats?StatsQuery	Stats
GET /v1/caches	Caches
GET /v1/caches/history?CacheHistoryQuery	CacheHistory
GET /v1/events?EventQuery	text/event-stream of EventEnvelope

Errors carry an ErrorResponse.

Structs

Budget

The memory budget runners and the mirror share, in bytes.

Busy

The body of a 409 refused because runners use what the request would change. Has the message of an ErrorResponse, so a client that reads only that still gets it.

CacheHistory

GET /v1/caches/history: every measurement, oldest first.

CacheHistoryQuery

GET /v1/caches/history query parameters.

CacheSize

One volume’s size at one measurement.

CacheVolume

One cache volume and its size.

Caches

GET /v1/caches: every cache volume of the configured profiles, as last measured. Docker measures volumes slowly, so runnerd measures them at start and whenever no runner runs after jobs ended.

Check

One thing the host needs to run runners. Its Display is the line runnerd doctor prints.

ConfigCheck

POST /v1/config/check and PUT /v1/config: what runnerd check-config prints for a config. PUT refuses an invalid one with 422 and this body, which has an ErrorResponse’s message.

ConfigFile

GET /v1/config: the config the daemon runs with. Parse text with config::Config::parse for its fields.

Doctor

GET /v1/doctor: what runnerd doctor checks, for the config the daemon runs with.

ErrorResponse

The body of every error response.

EventEnvelope

One event as GET /v1/events sends it: the SSE data field. The SSE event field is event.kind() and the SSE id field is id.

EventQuery

GET /v1/events query parameters. Resume with the Last-Event-ID header.

HostSample

One sample of the whole slice runners run in.

HostSampleQuery

GET /v1/host/samples query parameters.

HostSamples

GET /v1/host/samples: the slice’s use over time, oldest first.

Job

GET /v1/jobs/{id}: a job with its steps.

JobMetrics

What a job used, over the samples taken while it ran (every few seconds). None until a sample exists.

JobPage

GET /v1/jobs: one page of jobs.

JobQuery

GET /v1/jobs query parameters. Jobs come newest first (by ID, which grows with time).

JobRunner

The runner a job ran on.

JobSummary

A job without its steps: what lists and events carry.

LogQuery

GET /v1/jobs/{id}/logs query parameters. The response is text/plain, one log line per line.

LogSummary

A job’s stored log.

PauseQuery

POST /v1/repositories/{owner}/{name}/pause query parameters.

Paused

POST /v1/repositories/{owner}/{name}/pause: the repository is paused.

ProfileStatus

A runner profile and what runs in its slots.

RepositoryStatus

A configured repository and its queue.

RunnerStatus

A runner registered for one job, in its container.

RunningJob

A runner of this daemon that holds a slot, and the job it runs, if it took one.

Sample

One sample of a container’s use.

SampleSeries

GET /v1/jobs/{id}/samples: what the job’s container used over time, from its start to its removal. Samples older than history.samples are deleted; the job’s metrics stay.

ShutdownRequest

POST /v1/shutdown.

SlotStatus

One slot of a profile: room for one job.

Stats

GET /v1/stats: finished jobs per repository and time bucket, for trends. Sums, so clients can average.

StatsQuery

GET /v1/stats query parameters.

StatsRow

The finished jobs of one repository in one bucket.

Status

GET /v1/status: what the daemon serves and runs right now.

Step

One step of a job, as GitHub reports it.

Timeline

A job’s phases, in the order they happen. A runner’s container starts before GitHub gives it a job.

Enums

Bucket

How GET /v1/stats groups jobs in time.

CacheKind

What a cache volume holds.

CheckStatus

How a Check came out.

Event

Everything that happens, tagged by type.

JobState

Where a job is in its life, as this daemon saw it.

Principal

Who sent a request, as the transport authenticated it. Handlers get it from one place, so a new transport only has to produce one.