Run API

CLI, Streamlit, and HTTP share one submit path. A run is the same object whether you start it from drtoller run, the UI, or POST /v1/runs.

This is a control plane for start and status. It does not replace dataset I/O, Prometheus, or Grafana. Cancel, artifact listing, and auth are not in this surface.

Start the server

pip install "drtoller[api]"
drtoller serve api --host 127.0.0.1 --port 8088

Bind host/port also follow DRTOLLER_API_HOST / DRTOLLER_API_PORT. Health: GET /health → {"status":"ok"}.

In the current Compose reference, service run-api listens on 127.0.0.1:8088 (override DRTOLLER_API_PORT). Streamlit calls it through DRTOLLER_RUN_API_BASE_URL. If that env is unset, the UI submits in-process (same library, no HTTP hop).

HTTP

Method	Path	Role
POST	/v1/runs	Start a run (via: airflow or via: local)
GET	/v1/runs/{run_id}?dag_id=…	Airflow DAG-run status
GET	/health	Liveness

POST body (step_id or manifest_path required):

{
  "step_id": "step01",
  "run_id": "my_run",
  "artifacts_root": "/var/lib/drtoller/runs/step01",
  "params": { "runtime.parallelism.workers": 4 },
  "via": "airflow"
}

• via: airflow (default for HTTP/UI) — unpause + trigger the step DAG. Same dag_run.conf as Streamlit (step_id, run_id, artifacts_root, overlay). Response includes dag_id / dag_run_id.
• via: local — run the step in this process and return when dispatch finishes (result in the body). Use for small local jobs, not as a substitute for the worker pool.

GET needs dag_id from the POST response. Optional step_id is echoed. Status is the Airflow DAG-run state.

Library (same models as HTTP):

from drtoller.framework.integration.api import RunSubmitRequest, submit_run

out = submit_run(
    RunSubmitRequest(step_id="step01", run_id="my_run", via="airflow", params={"domain.foo": "bar"})
)

Clients: set DRTOLLER_RUN_API_BASE_URL (for example http://run-api:8088) so UI/helpers use HTTP; otherwise they call submit_run in-process.

Airflow credentials for trigger/status: AIRFLOW_BASE_URL, AIRFLOW_USERNAME, AIRFLOW_PASSWORD — same as Airflow.

CLI

drtoller run path/to/step.drtml --run-id my_run
drtoller run path/to/step.drtml --config run.yaml --param runtime.parallelism.workers=4
drtoller run path/to/step.drtml --via airflow --format json

--config is YAML or JSON (run_id, artifacts_root, params). Repeatable --param KEY=VALUE and --run-id / --artifacts override the file.

--via local (default) runs on this host. --via airflow triggers the DAG and prints dag_id / dag_run_id (JSON with --format json).

All of these go through submit_run. Param merge, hooks, and runtime.run_id stay the same as Airflow’s worker path.

See Install, Streamlit, Airflow, CLI operations.