HTTP API (Scalar)
Dexaflow’s control-plane API is the /api/v2/ surface, pinned Airflow
3.2.x-compatible. It is documented from the OpenAPI spec (openapi.yaml) and
rendered with Scalar.
The full interactive API reference (search, per-endpoint schemas, request/response examples) is served as a standalone page:
The static reference above hides the “Send” button (there is no live server behind
the docs). A running control plane serves its own Scalar at /docs with the test
button enabled, so you can exercise the API against your own instance.
Where the spec lives
The OpenAPI document is generated from the Go handler annotations on every push and
published alongside the site as openapi.yaml. Point any
OpenAPI-aware client (curl-with-schemas, Postman, an SDK generator) at it.
See ADR 0013 for why the API reference is Scalar embedded in the server binary.
When the credential cannot be checked
Every route that takes a bearer token can answer 503 with a Retry-After
header (in seconds) instead of 401. It means the control plane could not
reach a store it needs to check the credential, typically during a database
failover, and says nothing about the credential itself. Wait the Retry-After
and retry the same call; do not sign in again. The spec models it as the shared
AuthUnavailable response on every protected operation, so a generated client
has a typed case for it rather than an unknown status.
Triggering a run at the max_active_runs cap
POST /api/v2/dags/{dag_id}/dagRuns creates the run whatever the number of
active runs of the DAG, as Airflow does: it answers 201 with the run in
queued, and the scheduler starts it when fewer than max_active_runs runs of
the DAG are running, oldest logical date first. Before 0.5.10 a trigger at the
cap answered 409 (dag "x" is at max_active_runs cap of N). The tenant’s own
limits are still refusals: max_runs_per_day answers 403 and a suspended
tenant answers 409.
Setting a run’s state
PATCH /api/v2/dags/{dag_id}/dagRuns/{dag_run_id} with a state sets a run
to queued, success or failed, as Airflow 3.2 does. Only the scheduler
starts a run, under the DAG’s pause and max_active_runs: a PATCH to
running, which Dexaflow 0.5.3 accepted, still answers 200 but stores
queued, and the response shows queued; the audit entry
(dagrun.mark.queued) records requested_state: running. On a run that is
already running, a PATCH to running changes nothing and answers with the
run as it is. Setting queued also clears the run’s start date, so the
scheduler stamps a new one when it starts the run.
Setting failed or success settles the run’s unfinished task instances in
the same transaction, as Airflow 3’s set_dag_run_state_to_failed and
set_dag_run_state_to_success do (since 0.5.10,
#2425):
| Task instance state | failed | success |
|---|---|---|
running, up_for_reschedule | failed | success |
none, scheduled, queued, up_for_retry | skipped | success |
success, failed, skipped, upstream_failed, removed | unchanged | unchanged |
A running attempt is stopped the way a task instance marked failed is: its next
heartbeat, at most 15 seconds later, matches no live row, and the agent kills
its task process group. The slots it held under max_active_tasks and its pool
are free from the verdict on, as in Airflow, so for up to one heartbeat the old
attempt and the next one can run side by side. An agent that cannot reach the
control plane does not learn of the stop and its task runs to its end or its
execution_timeout. Before 0.5.10 only the run changed: its tasks kept running
outside every cap, and the tasks it had not started stayed none.
Clearing on the latest version
POST /api/v2/dags/{dag_id}/clearTaskInstances and
POST /api/v2/dags/{dag_id}/dagRuns/{dag_run_id}/clear take
run_on_latest_version, as Airflow 3.2 does. With true, a finished run
(success or failed, no task instance queued or running) moves to the
DAG’s current version: the clear creates the task instances of the tasks that
version adds and marks removed the ones of the tasks it dropped. A run that
is still running keeps its DAG version, and the cleared tasks re-run on that
version. Both routes, dry run included, then add the Dexaflow field
run_on_latest_version_not_applied, one entry per such run with its
dag_run_id and the reason; the field is left out when every run moved or
the option was not asked:
"run_on_latest_version_not_applied": [
{"dag_run_id": "manual__2026-10-16T09:00:00+00:00",
"reason": "the run is running: only a finished run moves to the current version"}
]
To move such a run, wait for it to finish (or mark it failed or success and
let its running tasks end), then clear again. Clearing a run that is still
running has
the steps and an example. An unknown dag_run_id answers 404 before anything
is cleared.
Paging
List endpoints page with limit and offset, as Airflow 3.2 does, and keep
the Airflow response body. An offset page costs more the deeper it is,
because the database reads and discards every row before it. Two endpoints
also take a cursor, a Dexaflow extension that makes every page cost the same
as the first:
GET /api/v2/dags/{dag_id}/dagRunsGET /api/v2/eventLogs
Every page that has a successor names the next page’s cursor in the
Dexaflow-Next-Cursor response header, offset pages included, so a client can
switch to cursors after its first request. Pass it back as the cursor query
parameter, with the same limit and filters; offset is ignored when a
cursor is set. The cursor is opaque: pass it back as you received it. A
malformed one is answered with 400.
curl -sS -D headers.txt -H "Authorization: Bearer $TOKEN" \
"$DEXAFLOW_URL/api/v2/dags/my_pipeline/dagRuns?limit=100" > page1.json
next=$(awk -F': ' 'tolower($1)=="dexaflow-next-cursor"{print $2}' headers.txt | tr -d '\r')
curl -sS -H "Authorization: Bearer $TOKEN" \
"$DEXAFLOW_URL/api/v2/dags/my_pipeline/dagRuns?limit=100&cursor=$next" > page2.json
Runs that share a logical date are ordered by run id, so both modes return
stable pages, and both count every run that matches the filters. A cursor
page does not count again: it reports the total_entries of the page that
issued its cursor, so the total holds still while you page, and rows added
since show on the next walk from the first page. Browsers on
an allowed CORS origin can read the Dexaflow-Next-Cursor and Link headers.