Workflows API

The Workflows API manages visual workflow definitions and starts debug or manual executions. It backs the admin routes /admin/workflows and /admin/workflows/canvas/{workflowId}.

info

All endpoint paths below include the /workflow-engine mount and omit only the global /api/v1.0 prefix. The router requires authentication and the workflows.enabled feature.

Endpoints

Method	Endpoint	Description
GET	/workflow-engine/definitions	List workflow definitions, newest updates first.
POST	/workflow-engine/definitions	Create a workflow definition.
GET	/workflow-engine/definitions/{definition_id}	Read one workflow definition.
PUT	/workflow-engine/definitions/{definition_id}	Update definition metadata, graph, trigger config, or active state.
DELETE	/workflow-engine/definitions/{definition_id}	Delete a workflow definition.
POST	/workflow-engine/execute	Start a workflow instance with supplied context.
GET	/workflow-engine/target-suggestions?q={query}	Search users, teams, platform roles, and contextual roles for approval-node targets.

Instance inspection, approval decisions, and retry are covered in Workflow Instances API.

Definition Shape

Workflow definitions store the admin canvas graph plus runtime trigger metadata:

Field	Type	Notes
id	UUID	Present on responses.
name	string	Required display name.
description	string or null	Optional admin description.
graph_json	object	React Flow graph with nodes, edges, and optional viewport.
trigger_type	string	Trigger type extracted from the trigger node.
trigger_config	object	Optional trigger-specific configuration.
is_active	boolean	Controls whether the definition can match new automated triggers.
version	integer	Starts at 1 and increments on each update.
created_at	datetime	Response only.
updated_at	datetime	Response only.

Known trigger types used by the UI include access_request, repository_access_request, use_case_request, manual, event, schedule, and form. The current canvas exposes access request, use case request, manual, and schedule trigger configuration.

Graph nodes can use the types trigger, decision, approval, action, input, and end. Approval node target suggestions can resolve users, teams, platform roles, or contextual governance roles.

List Definitions

GET /workflow-engine/definitions

Response:

[
  {
    "id": "definition-uuid",
    "name": "Access request approval",
    "description": null,
    "graph_json": {
      "nodes": [],
      "edges": []
    },
    "trigger_type": "access_request",
    "trigger_config": {},
    "is_active": true,
    "version": 3,
    "created_at": "2026-06-20T10:00:00Z",
    "updated_at": "2026-06-29T09:15:00Z"
  }
]

Create Definition

POST /workflow-engine/definitions

{
  "name": "Repository access approval",
  "description": "Routes repository access requests to maintainers.",
  "graph_json": {
    "nodes": [
      {
        "id": "trigger-1",
        "type": "trigger",
        "position": { "x": 0, "y": 0 },
        "data": {
          "label": "Repository Access Request",
          "triggerType": "repository_access_request"
        }
      }
    ],
    "edges": []
  },
  "trigger_type": "repository_access_request",
  "trigger_config": {},
  "is_active": true
}

The service enforces the workflows.max_active tier limit before creating a definition.

Read Definition

GET /workflow-engine/definitions/{definition_id}

Returns the same definition shape used by list and create responses.

Update Definition

PUT /workflow-engine/definitions/{definition_id}

All fields are optional. The version increments on every successful update.

{
  "name": "Repository access approval v2",
  "is_active": false
}

Use this endpoint for admin actions such as rename, activate/deactivate, and canvas save.

Delete Definition

DELETE /workflow-engine/definitions/{definition_id}

Response:

{
  "message": "Workflow definition deleted"
}

Deleting removes the definition record. Prefer setting is_active to false when the workflow may be needed again or when existing instances are still being investigated.

Execute A Workflow

POST /workflow-engine/execute

{
  "definition_id": "definition-uuid",
  "context": {
    "debug": true,
    "request": {
      "id": "request-uuid",
      "type": "repository_access",
      "status": "pending"
    },
    "repository": {
      "repository_kind": "project",
      "repository_id": "repository-uuid",
      "requested_access_level": "contribute"
    }
  }
}

The endpoint creates an instance, executes until completion, failure, or suspension, and returns the workflow instance shape:

{
  "id": "instance-uuid",
  "definition_id": "definition-uuid",
  "status": "SUSPENDED",
  "current_node_id": "approval-1",
  "context": {},
  "history": [],
  "created_at": "2026-06-29T10:00:00Z",
  "updated_at": "2026-06-29T10:00:01Z"
}

The admin definition list uses this endpoint for debug runs. Trigger-specific debug context templates are client-side defaults; callers may supply any JSON object that the workflow nodes expect.

Target Suggestions

GET /workflow-engine/target-suggestions?q=owner

Response:

[
  {
    "value": "user-uuid",
    "label": "Ada Lovelace",
    "category": "user",
    "description": "ada@example.com"
  },
  {
    "value": "team:data-platform",
    "label": "Data Platform",
    "category": "team",
    "description": "Platform maintainers"
  },
  {
    "value": "contextual:data_owner",
    "label": "Data Owner",
    "category": "role",
    "description": "Resolved at runtime from product governance"
  }
]

Suggestion categories are user, team, and role. Contextual role values include data owner, data steward, custodian, DPO, and repository maintainer.

Error Responses

Status	Meaning
400	Invalid definition payload, invalid execution context, or tier limit violation.
401	Missing or expired authentication.
403	Authenticated user cannot access workflow features.
404	Definition not found.
500	Execution or persistence failure.

Related Docs

• Workflow Instances API
• Access Requests API
• Requests API
• Workflow Builder user guide