Workflows

Workflow routes manage the catalog and drive executions. All routes here live at the top-level /workflows prefix, with one helper at /namespaces.

POST /workflows

Register one or more workflows from a Python source file.

• Body: multipart/form-data with a single file field containing the .py source.
• Max size: MAX_WORKFLOW_UPLOAD_BYTES (default 1 MiB; 413 if exceeded).
• Permission: caller needs workflow:{namespace}:*:register for every namespace touched by the upload.
• Response: 200 with a list of saved workflow records (namespace, name, version).
• Side effect: any @workflow.with_options(schedule=...) declarations are auto-registered as <name>_auto schedules (unless [flux.scheduling].auto_schedule_enabled = false).

GET /workflows

List workflows visible to the caller.

• Query: ?namespace=<ns> (optional).
• Permission: per-row workflow:{ns}:{name}:read filter; rows the caller cannot read are omitted.
• Response: [{ "namespace", "name", "version" }, ...].

GET /namespaces

List namespaces and a count of workflows the caller can see in each.

• Response: [{ "namespace": "<ns>", "workflow_count": <int> }, ...].

GET /workflows/{namespace}/{workflow_name}

Show the latest version of a workflow.

• Permission: workflow:{namespace}:{workflow_name}:read.
• Response: full workflow record including id, namespace, name, version, metadata, and source (base64-encoded).
• 404: when the workflow does not exist.

GET /workflows/{namespace}/{workflow_name}/versions

List every version of a workflow.

• Permission: workflow:{namespace}:{workflow_name}:read.
• Response: [{ "id", "name", "version" }, ...].

GET /workflows/{namespace}/{workflow_name}/versions/{version}

Show a specific version of a workflow.

• Permission: workflow:{namespace}:{workflow_name}:read.
• Response: same shape as the latest-version GET.

DELETE /workflows/{namespace}/{workflow_name}

Delete a workflow.

• Query: ?version=<n> to delete a single version; omit to delete all versions.
• Permission: workflow:{namespace}:*:register (registration verb gates destructive catalog ops).
• Response: {"status": "success", "message": "..."}.

POST /workflows/{namespace}/{workflow_name}/run/{mode}

Start a new execution.

• Path: mode is one of sync, async, stream. Any other value returns 400.
• Body: any JSON value, passed to the workflow as its input argument. Pydantic models in the workflow signature are validated.
• Query: ?version=<n> to pin to a specific version; ?detailed=true to return the full ExecutionContext DTO instead of a summary.
• Permission: a per-workflow authorize(...) check that combines the workflow’s required permissions (declared via metadata) with the caller’s identity. A 403 here returns {"detail": {"message": "Authorization denied", "missing_permissions": [...]}}.
• Response:
  • async: 200 with the execution summary as soon as the context is created.
  • sync: 200 once the execution reaches a terminal state.
  • stream: SSE (text/event-stream) with task_started, task_completed, and workflow_completed events. The stream closes when the execution finishes or is cancelled.

POST /workflows/{namespace}/{workflow_name}/resume/{execution_id}/{mode}

Resume a paused execution.

• Path: same mode semantics as run.
• Body: any JSON value, delivered to the paused task.
• Query: ?detailed=true for the full DTO.
• Permission: same authorize check as run.
• 404: if execution_id does not exist, or it belongs to a different workflow.
• 400: if the execution has already finished.

GET /workflows/{namespace}/{workflow_name}/cancel/{execution_id}

Cancel an in-flight execution. This is a GET, not POST or DELETE — intentionally, so cancellation can be triggered from a browser address bar or a one-line curl.

• Query: ?mode=sync|async (default async); ?detailed=true for the full DTO.
• Permission: workflow:{namespace}:{workflow_name}:run.
• Response: async returns immediately with state: CANCELLING. sync blocks until the worker reports CANCELLED (or another terminal state).
• 400: if the execution has already finished.

GET /workflows/{namespace}/{workflow_name}/status/{execution_id}

Read the current state of an execution.

• Query: ?detailed=true for the full DTO.
• Permission: workflow:{namespace}:{workflow_name}:read.
• Response: execution summary (or detailed context).

GET /workflows/{namespace}/{workflow_name}/executions

List executions for one workflow.

• Query: ?state=<STATE>, ?limit=50, ?offset=0.
• Permission: workflow:{namespace}:{workflow_name}:read.
• Response: same ExecutionListResponse shape as GET /executions.

Notes

• Workflow source travels base64-encoded from server to worker and is exec-loaded under a synthetic module name. This is internal — operators see only the to_dict() projection.
• The detailed=true flag changes the response shape from a small summary to the full ExecutionContextDTO including the event log. Use it sparingly; event logs can be large.
• For execution-centric reads, see Executions.