Workflows and Lineage API

Workflow APIs manage the UI-visible definition and its executions. Lineage APIs inspect the artifacts and revisions produced by processing. These are related but answer different questions: execution state explains whether work ran; lineage explains where an artifact came from and what depends on it.

Workflow definitions

The current product contract is rooted at:

/newmoi/workflow/v2/workflow-apps

Method and route

Purpose

GET /newmoi/workflow/v2/workflow-apps

List workflow applications

POST /newmoi/workflow/v2/workflow-deployments

Deploy a UI-visible workflow from its definition

GET /newmoi/workflow/v2/workflow-apps/:workflow_id

Read a workflow

PATCH /newmoi/workflow/v2/workflow-apps/:workflow_id

Update its saved definition

DELETE /newmoi/workflow/v2/workflow-apps/:workflow_id

Delete it

POST .../:workflow_id/pause

Prevent new runs

POST .../:workflow_id/resume

Accept new runs again

The deployment result supplies the workflow identifier used by the workflow-apps routes. The saved DSL is the execution source of truth. Before updating, validate required WorkItem identifiers, input/output types, dependencies, and loop termination. Available WorkItems are workspace-specific; query the deployed WorkItem catalog rather than copying identifiers from a static example.

Workflow templates use /newmoi/workflow-templates for list, create, detail, update, and delete. A template is reusable design material, not proof that a workflow has been deployed or run.

Start and inspect executions

Create an execution with:

POST /newmoi/workflow/v2/workflow-apps/:workflow_id/executions

The execution family provides list/detail, refresh, pause, resume, result, import context, import files, node detail, retry, cancel, and deletion. Keep the returned execution ID; do not select a run only by recency or display name.

Use the execution timeline to distinguish an upstream wait from a compute queue. A successful HTTP start means that the run was accepted, not that all nodes succeeded. Read the terminal execution and its result before consuming outputs.

Node reruns

For a node-scoped rerun:

  1. Read .../nodes/:node_key/rerun-plan.

  2. Review the affected downstream branch, node side effects, and reusable outputs.

  3. Create the rerun through .../nodes/:node_key/reruns.

  4. Follow the returned rerun ID through .../reruns/:rerun_id; cancel that rerun through its /cancel action if required.

Do not use a rerun as an automatic response to invalid input, a deterministic DSL error, or an external side effect that may already have completed.

Lineage and revisions

Route family

What it exposes

GET /newmoi/lineage/catalog-files/:file_id/overview

File-level processing overview

/newmoi/lineage/artifacts/:artifact_id/overview

Artifact-level overview

.../output-blocks

Produced blocks

.../blocks/:block_id/revisions

Available revisions and revision creation

.../effective-revisions

Select effective revisions

.../nodes/:node_id

Node detail and node output blocks

.../nodes/:node_id/rerun

Rerun from an artifact node

.../output-emissions/.../rerun-with-revisions

Rerun with selected revisions

Revision selection changes which artifact content downstream operations treat as effective. Read current revisions immediately before mutation and require explicit confirmation when downstream results can change.

Custom operator and WorkItem API-service routes are part of the workflow domain but have deployment-specific publish and invocation schemas. Use the target deployment’s OpenAPI for input/output schema, compute binding, timeout, concurrency, rate limit, enablement, and invocation payloads.

For worker capacity and metrics, see Compute resources and alerting. For file artifacts, see Data, files, and connectors.