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 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.

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.

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}/dagRuns
• GET /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. With a state filter the two modes can report different total_entries for a DAG with more than 10000 runs: offset paging filters and counts the newest 10000 runs, cursor paging every run of the DAG. Browsers on an allowed CORS origin can read the Dexaflow-Next-Cursor and Link headers.