Workflow Developer API

Get Workflow Capabilities

Describe graph JSON, expressions, node controls, lifecycle, and safety status.

GET/developer/v1/capabilities

Authorizations

Authorization

stringheaderrequired

Send your GenHealth credential as Bearer <YOUR_API_KEY>. This endpoint requires workflow:read for the authenticated organization.

Headers

Accept

stringheader

Response media type. Use application/json for the current API.

Parameters

This endpoint does not define request parameters.

Responses

200Successful Response

WorkflowCapabilityManifest

schema_versioninteger

graph_schemaComplete JSON Schemas for workflow imports, nodes, and edges, plus graph-wide rules.WorkflowGraphSchemaManifest

expression_syntaxSupported node-output and loop reference forms.WorkflowExpressionSyntax

lifecycleWorkflow states, version states, and the recommended authoring sequence.WorkflowLifecycle

node_typesarray<WorkflowNodeCapability>

integration_actionsAction discovery, connection readiness, and output-schema guidance.WorkflowIntegrationActions

recipesarray<WorkflowRecipe>

Request example

curl --request GET \
  --url 'https://api.umpa.genhealth.ai/developer/v1/capabilities' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Accept: application/json'

Response example

{
  "schema_version": 1,
  "graph_schema": {
    "workflow_import_envelope": {
      "type": "object",
      "required": [
        "kind",
        "schema_version",
        "workflow"
      ],
      "properties": {
        "kind": {
          "const": "genhealth.workflow_definition"
        },
        "schema_version": {
          "const": 1
        },
        "workflow": {
          "type": "object"
        }
      },
      "additionalProperties": false
    },
    "node": {
      "type": "object",
      "required": [
        "id",
        "type",
        "name"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "type": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "config": {
          "type": "object"
        },
        "error_strategy": {
          "type": "string",
          "enum": [
            "fail",
            "fail_branch",
            "default_value",
            "retry"
          ]
        }
      },
      "additionalProperties": false
    },
    "edge": {
      "type": "object",
      "required": [
        "source_node_id",
        "target_node_id"
      ],
      "properties": {
        "source_node_id": {
          "type": "string"
        },
        "source_output": {
          "type": "string",
          "default": "default"
        },
        "target_node_id": {
          "type": "string"
        },
        "target_input": {
          "type": "string",
          "default": "default"
        }
      },
      "additionalProperties": false
    },
    "rules": [
      "Node ids are unique within a workflow.",
      "Every edge endpoint names an existing node.",
      "Expressions may only reference statically upstream nodes.",
      "Active workflows must be edited through a draft before publishing."
    ]
  },
  "expression_syntax": {
    "reference": "{{node_id.output_name.path}}",
    "whole_value_preserves_type": true,
    "embedded_reference_stringifies": true,
    "loop_item_reference": "{{loop_node_id.item}}",
    "loop_index_reference": "{{loop_node_id.index}}"
  },
  "lifecycle": {
    "states": [
      "inactive",
      "active",
      "paused"
    ],
    "version_states": [
      "draft",
      "published",
      "archived"
    ],
    "recommended_sequence": [
      "create or import an inactive workflow",
      "read the editable graph",
      "create a draft before changing any published workflow version",
      "write and audit the graph",
      "publish the draft",
      "run and inspect PHI-safe run metadata"
    ],
    "umpa_visibility": "Developer API and UMPA use the same organization-scoped workflow records and versions."
  },
  "node_types": [
    {
      "type": "integration",
      "version": 1,
      "status": "supported",
      "category": "action",
      "description": "Invoke a public action in an integration configured for the organization.",
      "config_schema": {
        "type": "object",
        "properties": {
          "handler": {
            "type": "string",
            "description": "Exact handler returned by workflow action search."
          },
          "_group": {
            "type": "string",
            "description": "Integration group returned by workflow action search."
          },
          "params": {
            "type": "object",
            "additionalProperties": true
          }
        },
        "required": [
          "handler",
          "params"
        ],
        "additionalProperties": true
      },
      "data_output_schema": {
        "type": "object",
        "properties": {
          "default": {}
        },
        "additionalProperties": true
      },
      "routing_ports": {
        "static": [
          "default"
        ],
        "dynamic": false
      },
      "examples": [
        {
          "id": "find_patient",
          "type": "integration",
          "name": "Find patient",
          "config": {
            "_group": "NikoHealth",
            "handler": "exact_handler_from_search",
            "params": {}
          }
        }
      ],
      "warnings": [
        "Input and output schemas vary by action; call workflow action search before constructing this node."
      ]
    }
  ],
  "integration_actions": {
    "discovery": "Use the workflow action search endpoint for compact, tenant-permitted results.",
    "connection_status": "Use the integration connection status endpoint before publishing; it reports only configured/validated state and never credential material.",
    "detail_source": "Each result includes an exact handler/group, compact public fields, connection type, and best-effort declared outputs. Connection configuration status is not asserted.",
    "output_schema_completeness": "best_effort_declared_or_unknown",
    "warning": "Output names may be incomplete or observed from production examples; use PHI-safe run-node shape inspection to observe runtime fields."
  },
  "recipes": [
    {
      "name": "object_literals",
      "description": "JSON objects may be supplied directly in node params, bodies, and other open config fields."
    }
  ]
}

View OpenAPI document