HTTP API

The server is a FastAPI application; llmclick serve starts it, Swagger lives at /docs. All routes under /api take Authorization: Bearer <API_TOKEN> when that setting is configured. Errors are {"detail": "..."} with 401 (no or wrong token), 403 (a path outside API_PATHS), 404 (missing config, job or report), 409 (cancelling a finished job) or 422 (a request or config that does not fit the schema).

GET /health

Liveness check

Open without a token, for the container healthcheck.

Status	Meaning
200	Successful Response

POST /api/config/load

Check a config file on the server

The experiment key and stage plan of a YAML under API_PATHS. Nothing runs or is written.

Parameter	In	Required	Description
config_path	query	yes	YAML path on the server, relative to its working directory
authorization	header	no	Bearer <API_TOKEN>; needed only when the server sets API_TOKEN

Status	Meaning
200	Successful Response
422	Validation Error

POST /api/config/validate

Check an inline config

The same check as /load for a config sent in the body, in the shape of the YAML.

Parameter	In	Required	Description
authorization	header	no	Bearer <API_TOKEN>; needed only when the server sets API_TOKEN

Request body: Config

Status	Meaning
200	Successful Response
422	Validation Error

POST /api/jobs

Run a config in the background

Submitting the same config again while it runs returns the same job; after it ends, the run continues from the stages already built.

Parameter	In	Required	Description
authorization	header	no	Bearer <API_TOKEN>; needed only when the server sets API_TOKEN

Request body: JobRequest

Status	Meaning
202	Successful Response
422	Validation Error

GET /api/jobs

List jobs

Newest first.

Parameter	In	Required	Description
status	query	no	Only jobs in this status
limit	query	no	Only the most recent jobs
authorization	header	no	Bearer <API_TOKEN>; needed only when the server sets API_TOKEN

Status	Meaning
200	Successful Response
422	Validation Error

GET /api/jobs/{job_id}

Get a job's status and progress

Parameter	In	Required	Description
job_id	path	yes	The job_id a run request returned
authorization	header	no	Bearer <API_TOKEN>; needed only when the server sets API_TOKEN

Status	Meaning
200	Successful Response
422	Validation Error

DELETE /api/jobs/{job_id}

Cancel a pending or running job

The job stops at its next progress report and is then cancelled; poll it to see that. What its stages built so far stays, so submitting the same config again continues from there. 409 for a finished job.

Parameter	In	Required	Description
job_id	path	yes	The job_id a run request returned
authorization	header	no	Bearer <API_TOKEN>; needed only when the server sets API_TOKEN

Status	Meaning
202	Successful Response
422	Validation Error

GET /api/evaluations

List evaluation reports

Every report the evaluation recipes wrote under the output directory, with its headline scores.

Parameter	In	Required	Description
output_dir	query	no	Where the experiments are
recipe	query	no	Only this evaluation recipe
experiment	query	no	Only evaluations of this modeling experiment (directory)
authorization	header	no	Bearer <API_TOKEN>; needed only when the server sets API_TOKEN

Status	Meaning
200	Successful Response
422	Validation Error

GET /api/evaluations/{experiment}

Get one evaluation report in full

Parameter	In	Required	Description
experiment	path	yes	The evaluation experiment's key, as the list shows it
output_dir	query	no	Where the experiments are
authorization	header	no	Bearer <API_TOKEN>; needed only when the server sets API_TOKEN

Status	Meaning
200	Successful Response
422	Validation Error

GET /api/system/recipes

List the recipes

Per recipe: its stages and the keys its registries accept (sources, teachers, ...).

Parameter	In	Required	Description
authorization	header	no	Bearer <API_TOKEN>; needed only when the server sets API_TOKEN

Status	Meaning
200	Successful Response
422	Validation Error

Schemas

ConfigSummary

Field	Type	Default	Description
valid	boolean	True	Always true here: an invalid config is a 422 instead
recipe	string	required	The recipe the config names (pipeline.recipe)
experiment	string	required	Experiment key: the config's name and a hash of what decides its result
directory	string	required	Where the experiment's files go
stages	list[string]	required	Stages a run would execute or reuse, in order
config	object (extra keys allowed)	required	The config with every default filled in

EvaluationSummary

Field	Type	Default	Description
experiment	string	required	The evaluation experiment's key
recipe	string	required	The evaluation recipe that wrote the report
directory	string	required	The evaluation experiment's directory
report	string	required	Path of report.json
model	object (extra keys allowed)	required	The evaluated model (experiment, checkpoint, recipe), or the runs of a comparison
scores	object (extra keys allowed)	required	The headline numbers; the report holds everything
contamination	object (extra keys allowed) | null

JobRequest

Field	Type	Default	Description
config_path	string | null		YAML path on the server, relative to the working directory
config	object (extra keys allowed) | null		Inline config with the same shape as the YAML

JobResponse

Field	Type	Default	Description
job_id	string	required	The experiment key plus a hash of the stages run: the same request gives the same job
status	string	required	pending, running, done, failed, cancelled or interrupted
recipe	string	required	The recipe the config names
experiment	string	required	Experiment key
directory	string	required	Where the experiment's files go
stages	list[string]	required	Stages this job runs or reuses, in order
progress	object (extra keys allowed)	required	The running stage and how far it is
device_slot	integer | null		Which worker, and so which accelerator, ran the job
result	object (extra keys allowed) | null		Every stage's outputs, once the job is done
error	string | null		Why the job failed