HTTP API

Two surfaces, one boundary

There are two APIs because they have different threat models, not because one is a newer version of the other.

What the console calls

Nothing in the dagron console is privileged: every screen in it is a client of the gateway routes on this page. The quickest way to learn the API is to read a screen you already understand and see which call produced it. This is the run view, mid-flight:

1. Run header — name, short id, status, trigger, elapsed. GET /api/runs/{id}. The same object carries failure, so a red header needs no second call to explain itself.
2. The Live lamp. GET /api/runs/{id}/stream — SSE off one shared Postgres LISTEN. The page never polls; when it falls behind it is told to resync.
3. Graph / Timeline / Logs. GET /api/runs/{id}/graph for the {nodes[], edges[]} the canvas draws, and GET /api/runs/{id}/logs for every task's output merged into one attributed stream.
4. Re-run. POST /api/runs/{id}/rerun (optionally {from}), /resubmit for a clean run off the same spec, and GET /api/runs/{id}/spec behind "re-run with changes".
5. The node you clicked. GET /api/runs/{id}/tasks/{tid}/logs, tailed with ?offset=. The attempt counter beside the status comes from the task row; the passes behind it are …/attempts.
6. Clear + downstream. POST /api/runs/{id}/tasks/{tid}/clear — reset this task and its dependent cone, nothing else.
7. The log filter input and level chips. Not a client-side grep: they are the log-filter query parameters, evaluated on the server. Anything you can click here you can put in a runbook.
8. Cancel, retry, approve, reject — the control routes under Runs, each firing pg_notify in-transaction so the engine reacts immediately rather than on its next tick.

The other console screens map the same way: the workflow list is GET /api/workflows (schedule and run digest already joined in), Runs is GET /api/runs with its filter parameters, and Metrics is /api/metrics plus /api/metrics/timeseries. Each screen is walked through region by region in Get started.

Authentication

Every dagron-api route requires a valid HS256 session JWT, with five exceptions: /healthz, /readyz, POST /api/login, POST /api/logout, and GET /api/badges/{name}. Missing, invalid or expired credentials are a 401.

Two credential types, both presented the same way:

• Session JWT — as the HttpOnly dagron_session cookie (what the browser gets) or as Authorization: Bearer <jwt> (what an API client sends).
• Personal access token — a dgp_-prefixed string in the same Authorization: Bearer header. It resolves to its owner's live permissions, so revoking a group revokes it everywhere at once.

$ TOKEN=$(curl -s http://localhost:8080/api/login \
    -H 'content-type: application/json' \
    -d '{"email":"admin@local","password":"dagron-admin"}' | jq -r .token)

$ curl -s http://localhost:8080/api/me -H "Authorization: Bearer $TOKEN"
{"sub":"…","email":"admin@local","name":"Administrator","groups":["admin"],"exp":…}

Permissions

Three effective roles, derived from the session's groups claim.

What admin gates, and why

Errors, limits, conventions

• Error shape. Handlers answer (status, {"error": "<message>"}). Database failures map to 500 without leaking internals — the deliberate exception is GET /api/health, which answers 200 with db: "error" so that the outage itself stays reportable.
• Request bodies are capped at 1 MiB.
• Pagination is ?limit= + ?offset=. Lists default to 100 and cap at 500 unless a row below says otherwise; the cap is enforced server-side, so asking for more is clamped, not refused.
• CORS is currently permissive — a development posture. Put the gateway behind your own edge before exposing it.
• Timestamps are RFC 3339. Run and task ids are opaque strings; only the search endpoint treats a run id as prefix-matchable.

Session & identity

Runs

Control mutations fire pg_notify('task_events', run_id) inside the transaction, so the engine wakes immediately rather than on its next tick.

Logs

The log filter

Both log endpoints — on the gateway and on the engine ops API — accept the same grammar, applied server-side. A run's captured output can be hundreds of megabytes; shipping all of it so the client can grep is not a filter, it is a download.

The filter is a set of predicates, all of which must hold for a line to survive. Sending none of them returns unfiltered output, byte for byte as before filtering existed.

# Every error line in the run, with a line of context either side.
$ curl -s "$API/api/runs/$RUN/logs?level=error&context=1" \
    -H "authorization: Bearer $DAGRON_TOKEN" | jq -r '.lines[].text'

# Just the extract task, minus healthcheck noise, last 200 lines.
$ curl -s "$API/api/runs/$RUN/logs?task=extract&exclude=healthz&limit=200&tail=1" \
    -H "authorization: Bearer $DAGRON_TOKEN"

These are gateway routes, so they need a session JWT or a personal access token; drop the header when running the same query against the engine's own ops API, which has no auth. Over anything but loopback, use https:// — a bearer token on plain HTTP is readable and replayable in transit.

Four things matter when reading the response:

• Levels are inferred, not recorded. Task output is whatever the command printed, so the level comes from scanning the head of each line. A line that never says "error" cannot be found by asking for errors, and plain — no recognisable level token — is the common case.
• Line numbers are positions in the unfiltered output, so a filtered line can still be located in the raw log.
• Context lines come back with matched: false so a client can dim them. Context you cannot tell apart from a hit overstates what the filter found.
• An invalid filter is a 400 naming the reason — an uncompilable regex, an unknown level, a non-numeric bound. Ignoring it would return an unfiltered wall of text that the caller would read as "nothing was filtered out".

The grammar lives in one parser, so a filter typed into the console, sent by an SDK, or written into a runbook all mean the same thing.

Live events (SSE)

Workflows

Schedules & backfills

GitOps repositories

Environments & secrets

The key must be set identically on dagron-api, which encrypts on write, and on the engine, which decrypts at dispatch.

Datasets & lineage

Read-only views of the dataset registry and its append-only update ledger — the cross-workflow trail behind produces: and on_datasets:. A dataset is updated by a task, never by these routes.

Artifacts

The programmatic artifact channel. Bytes are envelope-encrypted at rest when a KEK provider is configured. All routes need a session, and answer 503 when DAGRON_ARTIFACT_DIR is unset.

Archived runs

History past the hot window. The list reads only the archived_runs index; the detail endpoint fetches the run's dagron.run-archive.v1 document from the archive sink — so dagron-api must see the same GC_ARCHIVE_DIR / GC_ARCHIVE_URL as the engine.

Dead letters

Health, metrics, search

Instance settings

Fleet & linking

These three routes exist in every build on purpose. A dead 404 at the moment someone acquires a second machine teaches nothing, so the open build answers a signpost naming the edition and the single-unit path instead.

The engine ops API

Built with the default ops feature and bound at API_ADDR. No authentication — keep it on localhost or pod-internal. It is self-describing: OpenAPI 3 at /openapi.yaml and /openapi.json, Swagger UI at /docs. Unlike the gateway it works against any datastore the engine was built with, SQLite included, which is what makes dagron dev possible.

$ curl -s -X POST localhost:8787/runs --data-binary @examples/simple_dag.yaml
{"run_id":"…"}
$ curl -s localhost:8787/runs/<run_id> | jq .run.status

# or in one call, synchronously
$ curl -s -X POST "localhost:8787/runs?wait=true&timeout_secs=60" \
    --data-binary @examples/simple_dag.yaml | jq

The built-in API explorer

The ops API documents itself. Point a browser at /docs on API_ADDR — http://127.0.0.1:8787/docs under dagron dev — and you get a Swagger UI over the engine's own OpenAPI 3 document. The assets are vendored into the binary, not fetched from a CDN, so the explorer works on an air-gapped host exactly as it does on a laptop.

1. Title, version and the OAS badge. Read from the live document, so what you are looking at is the spec this binary serves — not a published copy that may be a release behind.
2. The /openapi.yaml link under the title is the machine-readable document itself, also at /openapi.json. Point a client generator at it and the SDK you get matches the running engine.
3. The description states the security posture in the document, not just in these docs: no authentication of its own, bind API_ADDR to localhost or a trusted network, and put dagron-api or a proxy in front before exposing it.
4. Servers. The base URL requests go to. It follows wherever you set API_ADDR.
5. Tag groups — runs, dead-letters, datasets, ops — the same grouping as the table above, so the two are read together.
6. Each operation row carries its method and path. Collapsed, the page is a one-screen index of the whole surface.
7. An expanded operation gives the prose the endpoint table cannot: here, POST /runs explains that the raw body is stored verbatim as the workflow definition, and that admission control sheds with 429 plus Retry-After once MAX_INFLIGHT_RUNS is reached.
8. Try it out issues the request against the engine you are pointed at — a real submit, a real cancel. Convenient on dagron dev; a reason not to leave this surface reachable from anywhere you would not accept an unauthenticated write.

SDKs

Two clients cover the same ground, method for method: a builder over the engine's whole TaskSpec — every task kind, fan-out, sensors, approval gates, templates — and a Client over the whole gateway surface. They emit JSON, which is valid dagron input because JSON is a YAML subset. Their versions track the API version they speak to, so 0.9.x means "covers the 0.9 gateway".

from dagron import Dag, Client, Recipe

# An image built by the workflow that needs it, not by a pipeline elsewhere.
recipe = Recipe("etl", "python:3.12-slim", pip=["duckdb==1.1.3"])

dag = Dag("nightly")
extract = dag.task("extract", image=recipe, command=["python", "/app/extract.py"])
dag.task("report", image=recipe, command=["python", "/app/report.py"],
         depends_on=[extract])

api = Client.from_env()          # DAGRON_API_URL + DAGRON_TOKEN
run_id = api.submit_run(dag)
result = api.wait_run(run_id)    # blocks server-side, not in a poll loop

import { Dag, Client } from "@dagron/sdk";

const dag = new Dag("etl");
const extract = dag.task("extract", { image: "alpine", command: ["echo", "hi"] });
dag.task("load", { image: "alpine", command: ["true"], dependsOn: [extract] });

const api = Client.fromEnv();
const runId = await api.submitRun(dag);
await api.waitRun(runId);
await api.approveTask(runId, "review-gate");   // type: approval gates

Passing a Recipe wherever a task takes an image adds a build task, makes the task depend on it, and fills in the image reference — which is known at author time because it is derived from the recipe. That is also why re-submitting an unchanged recipe finds the image already built rather than building it again.

MCP — the agent surface

dagron-mcp fronts the gateway — never the engine ops API — over the Model Context Protocol on stdio. It is the callee, not the agent: it holds no model and runs no loop. Two variables configure it: DAGRON_API_URL (default http://localhost:8080) and DAGRON_MCP_TOKEN, a session JWT or personal access token sent as Authorization: Bearer. It logs to stderr so stdout carries only protocol messages.

Identity, credential material, admin user management and instance settings are deliberately not tools — an agent drives workflows, it does not mint its own tokens or rewrite instance policy. A read-only mode is available for agents that should look but not touch.

Recipes

Run a saved workflow from CI and fail the job if it fails

$ RUN=$(curl -sf $API/api/workflows/$WF/run \
    -H "authorization: Bearer $DAGRON_TOKEN" \
    -H 'content-type: application/json' \
    -d '{"parameters":{"date":"2026-09-22"}}' | jq -r .run_id)

$ STATUS=$(curl -sf "$API/api/runs/$RUN/wait?timeout_secs=600" \
    -H "authorization: Bearer $DAGRON_TOKEN" | jq -r .status)

$ [ "$STATUS" = succeeded ] || { \
    curl -sf "$API/api/runs/$RUN/logs?level=error&context=2" \
      -H "authorization: Bearer $DAGRON_TOKEN" | jq -r '.lines[].text'; \
    exit 1; }

Use a personal access token here, not a password session: it carries its owner's live permissions, can be revoked on its own, and cannot mint a replacement if the CI runner leaks it. Point $API at an https:// endpoint, or at a loopback address inside an already-encrypted tunnel — every call above puts a bearer token in a request header, and on plain HTTP across a network that token is readable and replayable by anyone on the path. Plain http:// is for localhost only.

Tail one task's output while it runs

$ OFF=0
$ while :; do
    R=$(curl -s "$API/api/runs/$RUN/tasks/$TID/logs?offset=$OFF" \
        -H "authorization: Bearer $TOKEN")
    echo -n "$(jq -r .output <<<"$R")"
    OFF=$(jq -r .next_offset <<<"$R")
    [ "$(jq -r .eof <<<"$R")" = true ] && break
    sleep 1
  done

Submit safely from a retrying client

Give the submit an Idempotency-Key derived from the work, not from the attempt — a logical date, a batch id, a content hash. A network timeout then costs you a retry, not a duplicate run: the second request returns the first run's id with 200.