# GenHealth Workflow Developer API

> Create, version, audit, publish, run, and maintain UMPA workflows directly against the core ETL API. The capability and action-discovery operations are optimized for AI agents.

Source: [https://genhealth.ai/docs/workflows](https://genhealth.ai/docs/workflows)

> **Workflow API access**
>
> Use a GenHealth API key with the workflow scope required by each operation. Copy the request examples to call the API from your server; interactive requests are not enabled in this reference.

## Build workflow automations

Discover supported integrations and actions, validate canonical workflow JSON, manage drafts and immutable versions, inspect graphs, publish viable workflows, and operate organization-scoped workflow runs.

- [Discover capabilities](https://genhealth.ai/docs/workflows/api-reference/v1/workflow-developer-api/get-workflow-capabilities.md): Inspect controls, node types, expressions, integrations, and action schemas.
- [Find workflow functions](https://genhealth.ai/docs/workflows/integrations.md): Search the actions available for use in a workflow definition.
- [Create workflows](https://genhealth.ai/docs/workflows/api-reference/v1/workflow-developer-api/create-developer-workflow.md): Create organization-scoped workflow records and validate their JSON first.
- [Publish and run](https://genhealth.ai/docs/workflows/api-reference/v1/workflow-developer-api/run-developer-workflow.md): Publish immutable versions and start idempotent workflow runs.

## Contract summary

| Property | Value |
| --- | --- |
| OpenAPI | 3.1.0 |
| API version | 1.0.0 |
| Operations | 36 |
| Component schemas | 59 |
| Authentication | HTTP bearer token with operation-specific workflow scopes |

## Organization isolation

Workflow definitions, versions, graphs, webhook endpoints, and runs are resolved within the organization carried by the authenticated credential. An identifier from another organization does not grant access.

## Operations

- [Get Workflow Capabilities](https://genhealth.ai/docs/workflows/api-reference/v1/workflow-developer-api/get-workflow-capabilities.md): `GET /developer/v1/capabilities` — Describe graph JSON, expressions, node controls, lifecycle, and safety status.
- [Search Workflow Actions](https://genhealth.ai/docs/workflows/api-reference/v1/workflow-developer-api/search-workflow-actions.md): `GET /developer/v1/actions` — Search tenant-permitted platform actions; connection setup is reported separately.
- [List Workflow Integrations](https://genhealth.ai/docs/workflows/api-reference/v1/workflow-developer-api/list-workflow-integrations.md): `GET /developer/v1/integrations` — List tenant-permitted public integrations; this does not assert connection setup.
- [List Workflow Integration Connections](https://genhealth.ai/docs/workflows/api-reference/v1/workflow-developer-api/list-workflow-integration-connections.md): `GET /developer/v1/integration-connections` — Report whether each public integration has credentials, without exposing them.
- [Get Workflow Action](https://genhealth.ai/docs/workflows/api-reference/v1/workflow-developer-api/get-workflow-action.md): `GET /developer/v1/actions/{handler}` — Return the complete first-pass schema for one exact public action handler.
- [List Workflow Action Field Options](https://genhealth.ai/docs/workflows/api-reference/v1/workflow-developer-api/list-workflow-action-field-options.md): `GET /developer/v1/actions/{handler}/fields/{field}/options` — Resolve dynamic choices for one action field without exposing credentials.
- [List Developer Workflows](https://genhealth.ai/docs/workflows/api-reference/v1/workflow-developer-api/list-developer-workflows.md): `GET /developer/v1/workflows` — List the same organization-scoped workflows shown in UMPA.
- [Create Developer Workflow](https://genhealth.ai/docs/workflows/api-reference/v1/workflow-developer-api/create-developer-workflow.md): `POST /developer/v1/workflows` — Create a workflow directly in the core ETL store used by UMPA.
- [Validate Workflow Definition](https://genhealth.ai/docs/workflows/api-reference/v1/workflow-developer-api/validate-workflow-definition.md): `POST /developer/v1/workflows/validate` — Preflight canonical workflow JSON against save, audit, and public API rules. This operation does not persist anything. A definition that fails validation still returns HTTP 200 with ``viable=false`` and machine-actionable findings.
- [Import Developer Workflow](https://genhealth.ai/docs/workflows/api-reference/v1/workflow-developer-api/import-developer-workflow.md): `POST /developer/v1/workflows/import` — Import canonical JSON as an inactive UMPA workflow with published version 1.
- [Get Developer Workflow](https://genhealth.ai/docs/workflows/api-reference/v1/workflow-developer-api/get-developer-workflow.md): `GET /developer/v1/workflows/{definition_id}` — Read an active, historical, or draft workflow definition by identifier.
- [Update Developer Workflow](https://genhealth.ai/docs/workflows/api-reference/v1/workflow-developer-api/update-developer-workflow.md): `PATCH /developer/v1/workflows/{definition_id}` — Update workflow metadata or an existing draft; published graphs are immutable.
- [Delete Developer Workflow](https://genhealth.ai/docs/workflows/api-reference/v1/workflow-developer-api/delete-developer-workflow.md): `DELETE /developer/v1/workflows/{definition_id}` — Soft-delete a workflow after publish-scope authorization and explicit confirmation.
- [Export Developer Workflow](https://genhealth.ai/docs/workflows/api-reference/v1/workflow-developer-api/export-developer-workflow.md): `GET /developer/v1/workflows/{definition_id}/export` — Export canonical workflow JSON suitable for validation or exact re-import.
- [Replace Developer Workflow Draft From Json](https://genhealth.ai/docs/workflows/api-reference/v1/workflow-developer-api/replace-developer-workflow-draft-from-json.md): `POST /developer/v1/workflows/{definition_id}/draft/from-json` — Replace the complete draft graph from canonical JSON without publishing it.
- [Create Developer Workflow Draft](https://genhealth.ai/docs/workflows/api-reference/v1/workflow-developer-api/create-developer-workflow-draft.md): `POST /developer/v1/workflows/{definition_id}/draft` — Create an editable draft from the workflow's currently active version.
- [Discard Developer Workflow Draft](https://genhealth.ai/docs/workflows/api-reference/v1/workflow-developer-api/discard-developer-workflow-draft.md): `DELETE /developer/v1/workflows/{definition_id}/draft` — Discard the current unpublished draft while preserving published versions.
- [Publish Developer Workflow](https://genhealth.ai/docs/workflows/api-reference/v1/workflow-developer-api/publish-developer-workflow.md): `POST /developer/v1/workflows/{definition_id}/publish` — Audit and publish the current draft as an immutable active version.
- [List Developer Workflow Versions](https://genhealth.ai/docs/workflows/api-reference/v1/workflow-developer-api/list-developer-workflow-versions.md): `GET /developer/v1/workflows/{definition_id}/versions` — List immutable published versions and draft metadata for one workflow.
- [Get Developer Workflow Version](https://genhealth.ai/docs/workflows/api-reference/v1/workflow-developer-api/get-developer-workflow-version.md): `GET /developer/v1/workflows/{definition_id}/versions/{version_id}` — Read one immutable workflow version without changing the active version.
- [Revert Developer Workflow Version](https://genhealth.ai/docs/workflows/api-reference/v1/workflow-developer-api/revert-developer-workflow-version.md): `POST /developer/v1/workflows/{definition_id}/versions/{version_id}/revert` — Create a new editable draft copied from a historical workflow version.
- [Run Developer Workflow](https://genhealth.ai/docs/workflows/api-reference/v1/workflow-developer-api/run-developer-workflow.md): `POST /developer/v1/workflows/{definition_id}/runs` — Start an active published workflow with idempotent retry semantics.
- [List Workflow Runs Safe](https://genhealth.ai/docs/workflows/api-reference/v1/workflow-developer-api/list-workflow-runs-safe.md): `GET /developer/v1/workflows/{definition_id}/runs` — Return run navigation metadata without trigger or node-result values.
- [Get Developer Workflow Webhook Endpoint](https://genhealth.ai/docs/workflows/api-reference/v1/workflow-developer-api/get-developer-workflow-webhook-endpoint.md): `GET /developer/v1/workflows/{definition_id}/webhook-endpoint` — Return an active, published webhook URL; never exposed as an MCP tool.
- [Cancel Developer Workflow Run](https://genhealth.ai/docs/workflows/api-reference/v1/workflow-developer-api/cancel-developer-workflow-run.md): `POST /developer/v1/runs/{run_id}/cancel` — Request cancellation of one organization-owned public-compatible workflow run.
- [Get Workflow Outline](https://genhealth.ai/docs/workflows/api-reference/v1/workflow-developer-api/read-workflow-outline.md): `GET /developer/v1/workflows/{definition_id}/outline` — Read a compact node-and-edge outline before requesting larger graph details.
- [Get Workflow Graph](https://genhealth.ai/docs/workflows/api-reference/v1/workflow-developer-api/read-workflow-graph.md): `GET /developer/v1/workflows/{definition_id}/graph` — Read the complete public-safe graph for a workflow's current target version.
- [Replace Workflow Graph](https://genhealth.ai/docs/workflows/api-reference/v1/workflow-developer-api/replace-workflow-graph.md): `PUT /developer/v1/workflows/{definition_id}/graph` — Replace the entire editable draft graph after public policy validation.
- [Get Workflow Node Context](https://genhealth.ai/docs/workflows/api-reference/v1/workflow-developer-api/read-workflow-node-context.md): `GET /developer/v1/workflows/{definition_id}/nodes/{node_id}/context` — Read one node with its immediate upstream and downstream graph context.
- [Get Workflow Node Details](https://genhealth.ai/docs/workflows/api-reference/v1/workflow-developer-api/read-workflow-node-details.md): `GET /developer/v1/workflows/{definition_id}/nodes/{node_id}` — Read one node's configuration, connections, and public action metadata.
- [Update Workflow Node](https://genhealth.ai/docs/workflows/api-reference/v1/workflow-developer-api/update-workflow-node.md): `PATCH /developer/v1/workflows/{definition_id}/nodes/{node_id}` — Patch selected fields on one node in the editable draft graph.
- [Delete Workflow Node](https://genhealth.ai/docs/workflows/api-reference/v1/workflow-developer-api/delete-workflow-node.md): `DELETE /developer/v1/workflows/{definition_id}/nodes/{node_id}` — Delete one draft node and optionally reconnect its incoming and outgoing edges.
- [Audit Workflow](https://genhealth.ai/docs/workflows/api-reference/v1/workflow-developer-api/audit-workflow.md): `POST /developer/v1/workflows/{definition_id}/audit` — Audit the unpublished draft and return actionable graph findings without mutation.
- [Insert Workflow Node After](https://genhealth.ai/docs/workflows/api-reference/v1/workflow-developer-api/insert-workflow-node-after.md): `POST /developer/v1/workflows/{definition_id}/nodes/after` — Insert one node after an existing draft node and optionally rewire its targets.
- [Insert Workflow Node Before](https://genhealth.ai/docs/workflows/api-reference/v1/workflow-developer-api/insert-workflow-node-before.md): `POST /developer/v1/workflows/{definition_id}/nodes/before` — Insert one node before an existing draft node and optionally rewire its sources.
- [Read Workflow Run Node Shape](https://genhealth.ai/docs/workflows/api-reference/v1/workflow-developer-api/read-workflow-run-node-shape.md): `GET /developer/v1/workflows/{definition_id}/runs/{run_id}/nodes/{node_id}` — Return status and value-free output shapes for one executed node.