Workflow Developer API

Get Workflow Capabilities V2

Describe graph controls plus the public webhook lifecycle contract.

GET/developer/v1/capabilities/v2

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

WorkflowDeveloperCapabilityManifestV2

expression_syntaxobject<string, any>

graph_schemaobject<string, any>

integration_actionsobject<string, any>

lifecycleobject<string, any>

node_typesarray<WorkflowNodeCapability>

public_webhooksComplete public webhook lifecycle safe to expose to an AI agent.WorkflowDeveloperPublicWebhookCapability

recipesarray<object<string, any>>

schema_versioninteger

Request example

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

Response example

{
  "expression_syntax": {
    "embedded_reference_stringifies": true,
    "loop_index_reference": "{{loop_node_id.index}}",
    "loop_item_reference": "{{loop_node_id.item}}",
    "reference": "{{node_id.output_name.path}}",
    "whole_value_preserves_type": true
  },
  "graph_schema": {
    "edge": {
      "additionalProperties": false,
      "properties": {
        "id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Id"
        },
        "source_node_id": {
          "title": "Source Node Id",
          "type": "string"
        },
        "source_output": {
          "default": "default",
          "title": "Source Output",
          "type": "string"
        },
        "target_input": {
          "default": "default",
          "title": "Target Input",
          "type": "string"
        },
        "target_node_id": {
          "title": "Target Node Id",
          "type": "string"
        }
      },
      "required": [
        "source_node_id",
        "target_node_id"
      ],
      "title": "WorkflowEdgeSchema",
      "type": "object"
    },
    "node": {
      "additionalProperties": false,
      "allOf": [
        {
          "else": {
            "properties": {
              "retry_config": {
                "type": "null"
              }
            }
          },
          "if": {
            "properties": {
              "error_strategy": {
                "const": "retry"
              }
            },
            "required": [
              "error_strategy"
            ]
          },
          "then": {
            "properties": {
              "retry_config": {
                "additionalProperties": false,
                "description": "Stricter retry settings advertised and enforced for third-party authors.",
                "properties": {
                  "delay_seconds": {
                    "default": 0,
                    "maximum": 300,
                    "minimum": 0,
                    "title": "Delay Seconds",
                    "type": "number"
                  },
                  "max_retries": {
                    "maximum": 3,
                    "minimum": 0,
                    "title": "Max Retries",
                    "type": "integer"
                  }
                },
                "required": [
                  "max_retries"
                ],
                "title": "PublicWorkflowRetryConfig",
                "type": "object"
              }
            },
            "required": [
              "retry_config"
            ]
          }
        }
      ],
      "properties": {
        "config": {
          "additionalProperties": true,
          "title": "Config",
          "type": "object"
        },
        "default_value": {
          "anyOf": [
            {
              "additionalProperties": true,
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Default Value"
        },
        "error_strategy": {
          "default": "fail",
          "enum": [
            "fail",
            "fail_branch",
            "default_value",
            "retry"
          ],
          "type": "string"
        },
        "id": {
          "title": "Id",
          "type": "string"
        },
        "name": {
          "title": "Name",
          "type": "string"
        },
        "position": {
          "anyOf": [
            {
              "maxItems": 2,
              "minItems": 2,
              "prefixItems": [
                {
                  "type": "integer"
                },
                {
                  "type": "integer"
                }
              ],
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Position"
        },
        "retry_config": {
          "anyOf": [
            {
              "additionalProperties": false,
              "description": "Stricter retry settings advertised and enforced for third-party authors.",
              "properties": {
                "delay_seconds": {
                  "default": 0,
                  "maximum": 300,
                  "minimum": 0,
                  "title": "Delay Seconds",
                  "type": "number"
                },
                "max_retries": {
                  "maximum": 3,
                  "minimum": 0,
                  "title": "Max Retries",
                  "type": "integer"
                }
              },
              "required": [
                "max_retries"
              ],
              "title": "PublicWorkflowRetryConfig",
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "type": {
          "title": "Type",
          "type": "string"
        }
      },
      "required": [
        "id",
        "type",
        "name"
      ],
      "title": "WorkflowNodeSchema",
      "type": "object"
    },
    "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."
    ],
    "workflow_import_envelope": {
      "$defs": {
        "WorkflowEdgeSchema": {
          "additionalProperties": false,
          "properties": {
            "id": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Id"
            },
            "source_node_id": {
              "title": "Source Node Id",
              "type": "string"
            },
            "source_output": {
              "default": "default",
              "title": "Source Output",
              "type": "string"
            },
            "target_input": {
              "default": "default",
              "title": "Target Input",
              "type": "string"
            },
            "target_node_id": {
              "title": "Target Node Id",
              "type": "string"
            }
          },
          "required": [
            "source_node_id",
            "target_node_id"
          ],
          "title": "WorkflowEdgeSchema",
          "type": "object"
        },
        "WorkflowImportBody": {
          "additionalProperties": false,
          "description": "Upload shape with write-side limits that do not constrain exports.",
          "properties": {
            "config": {
              "anyOf": [
                {
                  "additionalProperties": true,
                  "type": "object"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Config"
            },
            "description": {
              "anyOf": [
                {
                  "maxLength": 20000,
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Description"
            },
            "edges": {
              "items": {
                "$ref": "#/$defs/WorkflowEdgeSchema"
              },
              "title": "Edges",
              "type": "array"
            },
            "name": {
              "title": "Name",
              "type": "string"
            },
            "nodes": {
              "items": {
                "$ref": "#/$defs/WorkflowNodeSchema"
              },
              "title": "Nodes",
              "type": "array"
            },
            "route": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Route"
            },
            "trigger": {
              "anyOf": [
                {
                  "additionalProperties": true,
                  "type": "object"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "description": "Only `webhook` and manual `config.run_fields` are active; other triggers are ignored. The server syncs `webhook` from the `webhook_trigger` node. Trigger-only updates leave it unchanged; missing or mismatched values fail closed until publish or a node-bearing update. `type: manual` fields: `key`, `label`, `type`, `required`, `default`. `key` is required and unique; `type`: `boolean`, `number`, `text` (default `text`); `required` defaults to false; `default` must match `type`. An `upload_trigger` uses `text`, `date`, `number` run-field types, distinct from manual. Max 50 fields; keys 128 chars; labels 200 chars. Invalid manual triggers are rejected; see `details[].msg` and `details[].loc`.",
              "examples": [
                {
                  "config": {
                    "run_fields": [
                      {
                        "default": false,
                        "key": "dry_run",
                        "type": "boolean"
                      },
                      {
                        "key": "limit",
                        "required": true,
                        "type": "number"
                      }
                    ]
                  },
                  "type": "manual"
                }
              ],
              "title": "Trigger"
            }
          },
          "required": [
            "name",
            "nodes",
            "edges"
          ],
          "title": "WorkflowImportBody",
          "type": "object"
        },
        "WorkflowNodeSchema": {
          "additionalProperties": false,
          "allOf": [
            {
              "else": {
                "properties": {
                  "retry_config": {
                    "type": "null"
                  }
                }
              },
              "if": {
                "properties": {
                  "error_strategy": {
                    "const": "retry"
                  }
                },
                "required": [
                  "error_strategy"
                ]
              },
              "then": {
                "properties": {
                  "retry_config": {
                    "additionalProperties": false,
                    "description": "Stricter retry settings advertised and enforced for third-party authors.",
                    "properties": {
                      "delay_seconds": {
                        "default": 0,
                        "maximum": 300,
                        "minimum": 0,
                        "title": "Delay Seconds",
                        "type": "number"
                      },
                      "max_retries": {
                        "maximum": 3,
                        "minimum": 0,
                        "title": "Max Retries",
                        "type": "integer"
                      }
                    },
                    "required": [
                      "max_retries"
                    ],
                    "title": "PublicWorkflowRetryConfig",
                    "type": "object"
                  }
                },
                "required": [
                  "retry_config"
                ]
              }
            }
          ],
          "properties": {
            "config": {
              "additionalProperties": true,
              "title": "Config",
              "type": "object"
            },
            "default_value": {
              "anyOf": [
                {
                  "additionalProperties": true,
                  "type": "object"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Default Value"
            },
            "error_strategy": {
              "default": "fail",
              "enum": [
                "fail",
                "fail_branch",
                "default_value",
                "retry"
              ],
              "type": "string"
            },
            "id": {
              "title": "Id",
              "type": "string"
            },
            "name": {
              "title": "Name",
              "type": "string"
            },
            "position": {
              "anyOf": [
                {
                  "maxItems": 2,
                  "minItems": 2,
                  "prefixItems": [
                    {
                      "type": "integer"
                    },
                    {
                      "type": "integer"
                    }
                  ],
                  "type": "array"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Position"
            },
            "retry_config": {
              "anyOf": [
                {
                  "additionalProperties": false,
                  "description": "Stricter retry settings advertised and enforced for third-party authors.",
                  "properties": {
                    "delay_seconds": {
                      "default": 0,
                      "maximum": 300,
                      "minimum": 0,
                      "title": "Delay Seconds",
                      "type": "number"
                    },
                    "max_retries": {
                      "maximum": 3,
                      "minimum": 0,
                      "title": "Max Retries",
                      "type": "integer"
                    }
                  },
                  "required": [
                    "max_retries"
                  ],
                  "title": "PublicWorkflowRetryConfig",
                  "type": "object"
                },
                {
                  "type": "null"
                }
              ],
              "default": null
            },
            "type": {
              "title": "Type",
              "type": "string"
            }
          },
          "required": [
            "id",
            "type",
            "name"
          ],
          "title": "WorkflowNodeSchema",
          "type": "object"
        }
      },
      "additionalProperties": false,
      "properties": {
        "kind": {
          "const": "genhealth.workflow_definition",
          "title": "Kind",
          "type": "string"
        },
        "schema_version": {
          "const": 1,
          "title": "Schema Version",
          "type": "integer"
        },
        "workflow": {
          "$ref": "#/$defs/WorkflowImportBody"
        }
      },
      "required": [
        "kind",
        "schema_version",
        "workflow"
      ],
      "title": "WorkflowImportEnvelope",
      "type": "object"
    }
  },
  "integration_actions": {
    "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.",
    "discovery": "Use the workflow action search endpoint for compact, tenant-permitted results.",
    "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."
  },
  "lifecycle": {
    "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"
    ],
    "states": [
      "inactive",
      "active",
      "paused"
    ],
    "umpa_visibility": "Developer API and UMPA use the same organization-scoped workflow records and versions.",
    "version_states": [
      "draft",
      "published",
      "archived"
    ]
  },
  "node_types": [
    {
      "category": "action",
      "config_schema": {
        "additionalProperties": true,
        "properties": {
          "_group": {
            "description": "Integration group returned by workflow action search.",
            "type": "string"
          },
          "handler": {
            "description": "Exact handler returned by workflow action search.",
            "type": "string"
          },
          "params": {
            "additionalProperties": true,
            "properties": {},
            "type": "object"
          }
        },
        "required": [
          "handler",
          "params"
        ],
        "type": "object"
      },
      "data_output_schema": {
        "additionalProperties": true,
        "properties": {
          "default": {}
        },
        "type": "object"
      },
      "description": "Invoke a public action in an integration configured for the organization.",
      "examples": [
        {
          "config": {
            "_group": "NikoHealth",
            "handler": "exact_handler_from_search",
            "params": {}
          },
          "id": "find_patient",
          "name": "Find patient",
          "type": "integration"
        }
      ],
      "routing_ports": {
        "dynamic": false,
        "static": [
          "default"
        ]
      },
      "status": "supported",
      "type": "integration",
      "version": 1,
      "warnings": [
        "Input and output schemas vary by action; call workflow action search before constructing this node."
      ]
    },
    {
      "category": "action",
      "config_schema": {
        "additionalProperties": true,
        "properties": {
          "agent_id": {
            "type": "string"
          },
          "instructions": {
            "type": "string"
          },
          "max_iterations": {
            "default": 10,
            "minimum": 1,
            "type": "integer"
          },
          "model": {
            "type": "string"
          },
          "tools": {
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "required": [
          "instructions"
        ],
        "type": "object"
      },
      "data_output_schema": {
        "additionalProperties": true,
        "properties": {
          "default": {},
          "steps": {},
          "tool_calls": {}
        },
        "type": "object"
      },
      "description": "Run an agent with instructions and an approved tool set.",
      "examples": [],
      "routing_ports": {
        "dynamic": false,
        "static": [
          "default"
        ]
      },
      "status": "internal_only",
      "type": "agent",
      "version": 1,
      "warnings": [
        "Not accepted by third-party developer endpoints until referenced agents and tools have a public authorization contract."
      ]
    },
    {
      "category": "action",
      "config_schema": {
        "additionalProperties": true,
        "properties": {
          "max_tokens": {
            "minimum": 1,
            "type": "integer"
          },
          "model": {
            "type": "string"
          },
          "prompt": {
            "type": "string"
          },
          "seed": {
            "minimum": 0,
            "type": "integer"
          },
          "structured_output": {
            "additionalProperties": true,
            "properties": {},
            "type": "object"
          },
          "system_prompt": {
            "type": "string"
          },
          "temperature": {
            "default": 0.7,
            "maximum": 2,
            "minimum": 0,
            "type": "number"
          }
        },
        "required": [
          "prompt"
        ],
        "type": "object"
      },
      "data_output_schema": {
        "additionalProperties": true,
        "properties": {
          "default": {},
          "model": {},
          "output": {},
          "text": {}
        },
        "type": "object"
      },
      "description": "Generate text or configured structured fields with a language model.",
      "examples": [],
      "routing_ports": {
        "dynamic": false,
        "static": [
          "default"
        ]
      },
      "status": "supported",
      "type": "llm",
      "version": 1,
      "warnings": []
    },
    {
      "category": "action",
      "config_schema": {
        "additionalProperties": true,
        "properties": {
          "code": {
            "type": "string"
          }
        },
        "required": [
          "code"
        ],
        "type": "object"
      },
      "data_output_schema": {
        "additionalProperties": true,
        "properties": {
          "default": {}
        },
        "type": "object"
      },
      "description": "Run a Python transformation for trusted, internally authored workflows.",
      "examples": [],
      "routing_ports": {
        "dynamic": false,
        "static": [
          "default"
        ]
      },
      "status": "internal_only",
      "type": "code",
      "version": 1,
      "warnings": [
        "Not accepted by third-party developer endpoints because execution isolation is not yet a public contract."
      ]
    },
    {
      "category": "annotation",
      "config_schema": {
        "additionalProperties": true,
        "properties": {
          "body": {
            "type": "string"
          },
          "heading": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "data_output_schema": {
        "additionalProperties": true,
        "properties": {
          "body": {},
          "default": {},
          "heading": {}
        },
        "type": "object"
      },
      "description": "Carry human-readable documentation through the graph without performing an external action.",
      "examples": [],
      "routing_ports": {
        "dynamic": false,
        "static": [
          "default"
        ]
      },
      "status": "supported",
      "type": "comment",
      "version": 1,
      "warnings": []
    },
    {
      "category": "action",
      "config_schema": {
        "additionalProperties": true,
        "properties": {
          "operations": {
            "items": {
              "additionalProperties": true,
              "properties": {
                "op": {
                  "enum": [
                    "add",
                    "add_duration",
                    "append",
                    "as_datetime_text",
                    "as_unix_milliseconds",
                    "as_unix_seconds",
                    "base64_decode",
                    "base64_encode",
                    "difference_to_now",
                    "hash",
                    "length",
                    "lowercase",
                    "pad_end",
                    "pad_start",
                    "parse_date",
                    "parse_datetime",
                    "parse_json",
                    "parse_number",
                    "parse_url",
                    "prepend",
                    "replace",
                    "replace_all",
                    "replace_regex",
                    "split",
                    "substring",
                    "subtract",
                    "subtract_duration",
                    "time_since",
                    "trim",
                    "truncate",
                    "uppercase",
                    "url_encode"
                  ],
                  "type": "string"
                }
              },
              "required": [
                "op"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "source": {}
        },
        "required": [
          "source",
          "operations"
        ],
        "type": "object"
      },
      "data_output_schema": {
        "additionalProperties": true,
        "properties": {
          "default": {},
          "result": {}
        },
        "type": "object"
      },
      "description": "Apply a chain of text, date, parsing, encoding, and hashing transformations to one value.",
      "examples": [
        {
          "config": {
            "operations": [
              {
                "op": "trim"
              },
              {
                "op": "lowercase"
              }
            ],
            "source": "{{lookup.status}}"
          },
          "id": "normalize_status",
          "name": "Normalize status",
          "type": "formatter"
        }
      ],
      "routing_ports": {
        "dynamic": false,
        "static": [
          "default"
        ]
      },
      "status": "supported",
      "type": "formatter",
      "version": 1,
      "warnings": [
        "Formatter transforms one value; it is not a general object/dictionary projection node."
      ]
    },
    {
      "category": "action",
      "config_schema": {
        "additionalProperties": true,
        "properties": {
          "auth": {
            "additionalProperties": true,
            "properties": {
              "audience": {
                "type": "string"
              },
              "client_auth": {
                "enum": [
                  "body",
                  "header"
                ],
                "type": "string"
              },
              "client_id": {
                "type": "string"
              },
              "client_secret": {
                "type": "string"
              },
              "key_in": {
                "enum": [
                  "header",
                  "query"
                ],
                "type": "string"
              },
              "key_name": {
                "type": "string"
              },
              "key_value": {
                "type": "string"
              },
              "password": {
                "type": "string"
              },
              "scope": {
                "type": "string"
              },
              "token": {
                "type": "string"
              },
              "token_url": {
                "type": "string"
              },
              "type": {
                "enum": [
                  "none",
                  "basic",
                  "bearer",
                  "api_key",
                  "digest",
                  "oauth2_client_credentials"
                ],
                "type": "string"
              },
              "username": {
                "type": "string"
              }
            },
            "type": "object"
          },
          "body": {},
          "body_type": {
            "enum": [
              "none",
              "json",
              "form",
              "multipart",
              "raw"
            ],
            "type": "string"
          },
          "fail_on_error_status": {
            "default": false,
            "type": "boolean"
          },
          "follow_redirects": {
            "default": true,
            "type": "boolean"
          },
          "headers": {
            "additionalProperties": {
              "type": "string"
            },
            "type": "object"
          },
          "max_redirects": {
            "default": 10,
            "maximum": 20,
            "minimum": 0,
            "type": "integer"
          },
          "method": {
            "enum": [
              "GET",
              "POST",
              "PUT",
              "PATCH",
              "DELETE",
              "HEAD",
              "OPTIONS"
            ],
            "type": "string"
          },
          "pagination": {
            "additionalProperties": true,
            "properties": {
              "items_path": {
                "type": "string"
              },
              "max_pages": {
                "default": 10,
                "maximum": 100,
                "minimum": 1,
                "type": "integer"
              },
              "mode": {
                "enum": [
                  "off",
                  "next_url",
                  "increment"
                ],
                "type": "string"
              },
              "next_url_path": {
                "type": "string"
              },
              "param": {
                "type": "string"
              },
              "start": {
                "type": "integer"
              },
              "step": {
                "minimum": 1,
                "type": "integer"
              }
            },
            "type": "object"
          },
          "query": {
            "type": "object"
          },
          "raw_content_type": {
            "type": "string"
          },
          "response_format": {
            "enum": [
              "auto",
              "json",
              "text"
            ],
            "type": "string"
          },
          "timeout": {
            "default": 30,
            "maximum": 300,
            "minimum": 1,
            "type": "number"
          },
          "url": {
            "format": "uri",
            "type": "string"
          }
        },
        "required": [
          "url"
        ],
        "type": "object"
      },
      "data_output_schema": {
        "additionalProperties": true,
        "properties": {
          "default": {}
        },
        "type": "object"
      },
      "description": "Make a generic HTTP request for trusted, internally authored workflows.",
      "examples": [],
      "routing_ports": {
        "dynamic": false,
        "static": [
          "default"
        ]
      },
      "status": "internal_only",
      "type": "http",
      "version": 1,
      "warnings": [
        "Not accepted by third-party developer endpoints until DNS-aware egress controls are enforced."
      ]
    },
    {
      "category": "control",
      "config_schema": {
        "oneOf": [
          {
            "additionalProperties": true,
            "properties": {
              "condition": {
                "oneOf": [
                  {
                    "description": "Literal JSON value or expression string tested for truthiness.",
                    "type": [
                      "string",
                      "number",
                      "boolean",
                      "array"
                    ]
                  },
                  {
                    "additionalProperties": false,
                    "properties": {
                      "left": {},
                      "operator": {
                        "enum": [
                          "eq",
                          "gt",
                          "gte",
                          "is_empty",
                          "is_not_empty",
                          "length_eq",
                          "length_gt",
                          "length_gte",
                          "length_lt",
                          "length_lte",
                          "length_neq",
                          "lt",
                          "lte",
                          "neq"
                        ],
                        "type": "string"
                      },
                      "right": {}
                    },
                    "required": [
                      "left",
                      "operator"
                    ],
                    "type": "object"
                  }
                ]
              }
            },
            "required": [
              "condition"
            ],
            "type": "object"
          },
          {
            "additionalProperties": true,
            "properties": {
              "conditions": {
                "items": {
                  "additionalProperties": false,
                  "properties": {
                    "condition": {
                      "oneOf": [
                        {
                          "description": "Literal JSON value or expression string tested for truthiness.",
                          "type": [
                            "string",
                            "number",
                            "boolean",
                            "array"
                          ]
                        },
                        {
                          "additionalProperties": false,
                          "properties": {
                            "left": {},
                            "operator": {
                              "enum": [
                                "eq",
                                "gt",
                                "gte",
                                "is_empty",
                                "is_not_empty",
                                "length_eq",
                                "length_gt",
                                "length_gte",
                                "length_lt",
                                "length_lte",
                                "length_neq",
                                "lt",
                                "lte",
                                "neq"
                              ],
                              "type": "string"
                            },
                            "right": {}
                          },
                          "required": [
                            "left",
                            "operator"
                          ],
                          "type": "object"
                        }
                      ]
                    },
                    "name": {
                      "minLength": 1,
                      "type": "string"
                    }
                  },
                  "required": [
                    "name",
                    "condition"
                  ],
                  "type": "object"
                },
                "minItems": 1,
                "type": "array"
              }
            },
            "required": [
              "conditions"
            ],
            "type": "object"
          }
        ]
      },
      "data_output_schema": {
        "additionalProperties": true,
        "properties": {
          "branch": {},
          "default": {}
        },
        "type": "object"
      },
      "description": "Route execution through a two-way condition or an ordered named else-if chain.",
      "examples": [
        {
          "config": {
            "condition": {
              "left": "{{search.orders}}",
              "operator": "length_gt",
              "right": 0
            }
          },
          "id": "has_orders",
          "name": "Has orders",
          "type": "if"
        }
      ],
      "routing_ports": {
        "description": "Named-condition mode uses each condition name plus else instead of true/false.",
        "dynamic": true,
        "static": [
          "true",
          "false"
        ]
      },
      "status": "supported",
      "type": "if",
      "version": 1,
      "warnings": []
    },
    {
      "category": "control",
      "config_schema": {
        "additionalProperties": true,
        "properties": {
          "cases": {
            "additionalProperties": {
              "type": "string"
            },
            "type": "object"
          },
          "value": {}
        },
        "required": [
          "value",
          "cases"
        ],
        "type": "object"
      },
      "data_output_schema": {
        "additionalProperties": true,
        "properties": {
          "default": {}
        },
        "type": "object"
      },
      "description": "Route a resolved value to a configured output handle, falling back to default.",
      "examples": [
        {
          "config": {
            "cases": {
              "active": "process",
              "inactive": "skip"
            },
            "value": "{{lookup.status}}"
          },
          "id": "route_status",
          "name": "Route status",
          "type": "switch"
        }
      ],
      "routing_ports": {
        "description": "Case values map to output-handle names; default is used when no case matches.",
        "dynamic": true,
        "static": [
          "default"
        ]
      },
      "status": "supported",
      "type": "switch",
      "version": 1,
      "warnings": [
        "Named if conditions are preferred for new multi-branch workflows."
      ]
    },
    {
      "category": "control",
      "config_schema": {
        "additionalProperties": true,
        "properties": {
          "execution_mode": {
            "default": "inline",
            "enum": [
              "inline",
              "item_step"
            ],
            "type": "string"
          },
          "items": {
            "description": "Array value or expression resolving to an array."
          },
          "loop_iteration_concurrency": {
            "default": 10,
            "maximum": 20,
            "minimum": 1,
            "type": "integer"
          },
          "max_iterations": {
            "description": "Required public execution cap. Each loop is limited to 100 iterations and the product of all loop caps in one graph cannot exceed 500.",
            "maximum": 100,
            "minimum": 1,
            "type": "integer"
          },
          "mode": {
            "default": "single_node",
            "enum": [
              "single_node",
              "subgraph"
            ],
            "type": "string"
          }
        },
        "required": [
          "items",
          "max_iterations"
        ],
        "type": "object"
      },
      "data_output_schema": {
        "additionalProperties": true,
        "properties": {
          "count": {},
          "default": {},
          "failure_count": {},
          "items": {},
          "results": {},
          "success_count": {}
        },
        "type": "object"
      },
      "description": "Iterate over an array using a single body node or an owned subgraph.",
      "examples": [
        {
          "config": {
            "items": "{{search.orders}}",
            "max_iterations": 100,
            "mode": "subgraph"
          },
          "id": "each_order",
          "name": "Each order",
          "type": "loop"
        }
      ],
      "routing_ports": {
        "description": "default enters the loop body; complete continues after all iterations.",
        "dynamic": false,
        "static": [
          "default",
          "complete"
        ]
      },
      "status": "supported",
      "type": "loop",
      "version": 1,
      "warnings": [
        "Loop-body expressions use {{loop_node_id.item}} and {{loop_node_id.index}}.",
        "execution_mode=item_step requires mode=subgraph.",
        "The developer API requires max_iterations <= 100; all loop caps have a cumulative product budget of 500."
      ]
    },
    {
      "category": "control",
      "config_schema": {
        "additionalProperties": true,
        "properties": {},
        "type": "object"
      },
      "data_output_schema": {
        "additionalProperties": true,
        "properties": {
          "default": {}
        },
        "type": "object"
      },
      "description": "Legacy parallel branch marker; new graphs are rejected.",
      "examples": [],
      "routing_ports": {
        "dynamic": false,
        "static": [
          "default"
        ]
      },
      "status": "deprecated",
      "type": "fan_out",
      "version": 1,
      "warnings": [
        "Use ordinary DAG branches or loop subgraphs instead."
      ]
    },
    {
      "category": "control",
      "config_schema": {
        "additionalProperties": true,
        "properties": {},
        "type": "object"
      },
      "data_output_schema": {
        "additionalProperties": true,
        "properties": {
          "default": {}
        },
        "type": "object"
      },
      "description": "Reserved node type for invoking another workflow; no runtime implementation is registered.",
      "examples": [],
      "routing_ports": {
        "dynamic": false,
        "static": [
          "default"
        ]
      },
      "status": "unavailable",
      "type": "subworkflow",
      "version": null,
      "warnings": [
        "Do not use this node type in a graph."
      ]
    },
    {
      "category": "trigger",
      "config_schema": {
        "additionalProperties": true,
        "properties": {
          "active_hours_end": {
            "anyOf": [
              {
                "maximum": 23,
                "minimum": 0,
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          },
          "active_hours_start": {
            "anyOf": [
              {
                "maximum": 23,
                "minimum": 0,
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          },
          "cron": {
            "description": "Runnable five-field cron expression; required when schedule_type is cron.",
            "minLength": 1,
            "type": "string"
          },
          "days_of_week": {
            "items": {
              "maximum": 6,
              "minimum": 0,
              "type": "integer"
            },
            "minItems": 1,
            "type": "array",
            "uniqueItems": true
          },
          "interval": {
            "description": "Repeat count; must be 1 for days, weeks, and months.",
            "minimum": 1,
            "type": "integer"
          },
          "jitter_seconds": {
            "maximum": 300,
            "minimum": 0,
            "type": "integer"
          },
          "review_route": {
            "default": "workflow-review",
            "type": "string"
          },
          "schedule_type": {
            "description": "Required; choose the schedule evaluation mode explicitly.",
            "enum": [
              "cron",
              "interval"
            ],
            "type": "string"
          },
          "timezone": {
            "type": "string"
          },
          "unit": {
            "enum": [
              "minutes",
              "hours",
              "days",
              "weeks",
              "months"
            ],
            "type": "string"
          }
        },
        "required": [
          "schedule_type"
        ],
        "type": "object"
      },
      "data_output_schema": {
        "additionalProperties": true,
        "properties": {
          "cron": {},
          "date_iso": {},
          "date_us": {},
          "day": {},
          "day_of_week": {},
          "default": {},
          "epoch_ms": {},
          "epoch_seconds": {},
          "human": {},
          "human_short": {},
          "jitter_seconds": {},
          "month": {},
          "review_route": {},
          "run_at_iso": {},
          "run_at_iso_utc": {},
          "schedule_type": {},
          "time_12h": {},
          "time_24h": {},
          "timezone": {},
          "timezone_used": {},
          "year": {}
        },
        "type": "object"
      },
      "description": "Start a workflow from a cron or interval schedule.",
      "examples": [],
      "routing_ports": {
        "dynamic": false,
        "static": [
          "default"
        ]
      },
      "status": "supported",
      "type": "schedule",
      "version": 1,
      "warnings": [
        "Cron schedules require a runnable five-field expression.",
        "For interval schedules, active-hour bounds must be paired and start must be less than end.",
        "The runtime supports only interval=1 for days, weeks, and months; use cron for longer cadences."
      ]
    },
    {
      "category": "trigger",
      "config_schema": {
        "additionalProperties": true,
        "properties": {
          "accepted_types": {
            "description": "Comma-separated MIME types or file extensions.",
            "type": "string"
          },
          "completion_behavior": {
            "default": "always_review",
            "enum": [
              "always_review",
              "always_complete",
              "review_on_failure"
            ],
            "type": "string"
          },
          "review_route": {
            "default": "workflow-review",
            "type": "string"
          },
          "run_fields": {
            "items": {
              "additionalProperties": false,
              "properties": {
                "key": {
                  "minLength": 1,
                  "type": "string"
                },
                "label": {
                  "type": "string"
                },
                "required": {
                  "default": true,
                  "type": "boolean"
                },
                "type": {
                  "enum": [
                    "text",
                    "date",
                    "number"
                  ],
                  "type": "string"
                }
              },
              "required": [
                "key",
                "label",
                "type"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "upload_fields": {
            "items": {
              "additionalProperties": false,
              "properties": {
                "key": {
                  "minLength": 1,
                  "type": "string"
                },
                "label": {
                  "type": "string"
                },
                "required": {
                  "default": true,
                  "type": "boolean"
                }
              },
              "required": [
                "key",
                "label"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "upload_instructions": {
            "type": "string"
          },
          "upload_mode": {
            "default": "single",
            "enum": [
              "single",
              "structured"
            ],
            "type": "string"
          }
        },
        "type": "object"
      },
      "data_output_schema": {
        "additionalProperties": true,
        "properties": {
          "default": {},
          "document_content": {},
          "document_id": {},
          "document_title": {},
          "truncated": {}
        },
        "type": "object"
      },
      "description": "Start a workflow from a single or structured document upload.",
      "examples": [],
      "routing_ports": {
        "dynamic": false,
        "static": [
          "default"
        ]
      },
      "status": "supported",
      "type": "upload_trigger",
      "version": 1,
      "warnings": [
        "Configured upload and run fields add dynamic properties to the trigger output."
      ]
    },
    {
      "category": "trigger",
      "config_schema": {
        "additionalProperties": true,
        "properties": {
          "provider": {
            "enum": [
              "generic"
            ],
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "slug_token": {
            "readOnly": true,
            "type": "string"
          }
        },
        "required": [
          "provider"
        ],
        "type": "object"
      },
      "data_output_schema": {
        "additionalProperties": true,
        "properties": {
          "call_uuid": {},
          "correlation_id": {},
          "default": {
            "additionalProperties": true,
            "description": "Full inbound JSON object. Reference an arbitrary body field as {{webhook_node_id.default.field_name}}.",
            "properties": {},
            "type": "object"
          },
          "order_id": {},
          "org_id": {},
          "patient_id": {},
          "recording_url": {},
          "status": {},
          "transcript": {}
        },
        "type": "object"
      },
      "description": "Start a workflow from a public generic webhook or a trusted internal provider webhook.",
      "examples": [
        {
          "config": {
            "provider": "generic",
            "slug": "orders"
          },
          "id": "receive_event",
          "name": "Receive event",
          "type": "webhook_trigger"
        }
      ],
      "routing_ports": {
        "dynamic": false,
        "static": [
          "default"
        ]
      },
      "status": "supported",
      "type": "webhook_trigger",
      "version": 1,
      "warnings": [
        "The server manages the unguessable slug token; clients must not supply or persist it.",
        "Public agents may author only generic webhooks; provider-specific webhooks such as Plivo remain internal.",
        "For generic webhooks, read the complete request body from default; provider-specific named outputs may be empty."
      ]
    },
    {
      "category": "trigger",
      "config_schema": {
        "additionalProperties": true,
        "properties": {
          "fields": {
            "items": {
              "additionalProperties": false,
              "properties": {
                "key": {
                  "minLength": 1,
                  "type": "string"
                },
                "label": {
                  "type": "string"
                },
                "required": {
                  "default": true,
                  "type": "boolean"
                },
                "source": {
                  "enum": [
                    "billing",
                    "manual"
                  ],
                  "type": "string"
                },
                "type": {
                  "enum": [
                    "text",
                    "date",
                    "code_ranges",
                    "payer"
                  ],
                  "type": "string"
                }
              },
              "required": [
                "key",
                "label",
                "type",
                "source"
              ],
              "type": "object"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "data_output_schema": {
        "additionalProperties": true,
        "properties": {
          "default": {}
        },
        "type": "object"
      },
      "description": "Start a workflow from a billing-system URL using configured input fields.",
      "examples": [],
      "routing_ports": {
        "dynamic": false,
        "static": [
          "default"
        ]
      },
      "status": "supported",
      "type": "billing_url_trigger",
      "version": 1,
      "warnings": [
        "Configured fields add dynamic properties to the trigger output."
      ]
    },
    {
      "category": "action",
      "config_schema": {
        "additionalProperties": true,
        "properties": {
          "allow_reprocess": {
            "type": "boolean"
          },
          "completion_behavior": {
            "default": "always_review",
            "enum": [
              "always_complete",
              "always_review"
            ],
            "type": "string"
          },
          "document_id": {
            "minLength": 1,
            "type": "string"
          },
          "related_document_ids": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "review_route": {
            "default": "workflow-review",
            "type": "string"
          },
          "summary_json": {},
          "target_document_id": {},
          "title": {
            "type": "string"
          }
        },
        "required": [
          "document_id"
        ],
        "type": "object"
      },
      "data_output_schema": {
        "additionalProperties": true,
        "properties": {
          "default": {},
          "display_status": {},
          "document_id": {},
          "primary_document_id": {},
          "related_document_ids": {},
          "review_route": {},
          "success": {},
          "title": {}
        },
        "type": "object"
      },
      "description": "Publish a workflow result as an operator-review artifact in UMPA.",
      "examples": [],
      "routing_ports": {
        "dynamic": false,
        "static": [
          "default"
        ]
      },
      "status": "supported",
      "type": "publish_to_inbox",
      "version": 1,
      "warnings": []
    },
    {
      "category": "control",
      "config_schema": {
        "additionalProperties": true,
        "properties": {
          "correlation_id": {
            "description": "Literal value or resolved expression must match [A-Za-z0-9_.:\\-]{1,256}.",
            "minLength": 1,
            "type": "string"
          },
          "event_name": {
            "default": "etl/workflow.callback.received",
            "enum": [
              "etl/workflow.callback.received"
            ],
            "type": "string"
          },
          "timeout_seconds": {
            "default": 900,
            "minimum": 1,
            "type": "integer"
          }
        },
        "required": [
          "correlation_id"
        ],
        "type": "object"
      },
      "data_output_schema": {
        "additionalProperties": true,
        "properties": {
          "default": {}
        },
        "type": "object"
      },
      "description": "Durably pause a run until a correlated callback arrives or the wait times out.",
      "examples": [
        {
          "config": {
            "correlation_id": "{{submit.request_id}}",
            "timeout_seconds": 900
          },
          "id": "wait_for_vendor",
          "name": "Wait for vendor callback",
          "type": "wait_for_callback"
        }
      ],
      "routing_ports": {
        "dynamic": false,
        "static": [
          "default",
          "timeout"
        ]
      },
      "status": "supported",
      "type": "wait_for_callback",
      "version": 1,
      "warnings": []
    }
  ],
  "public_webhooks": {
    "authoring_example": {
      "config": {
        "provider": "generic",
        "slug": "orders"
      },
      "id": "receive_event",
      "name": "Receive event",
      "type": "webhook_trigger"
    },
    "authoring_rules": [
      "The optional slug is a readable label, not the URL credential.",
      "Do not supply slug_token or require_idempotency_key; the server owns both fields.",
      "Do not supply top-level trigger.webhook metadata; the server derives it from the node.",
      "Provider-specific webhooks such as Plivo are internal and cannot be authored through this API."
    ],
    "delivery": {
      "additional_authentication_headers_required": false,
      "authentication": "webhook_url_credential",
      "body_type": "json_object",
      "conflicting_retry_result": "HTTP 409",
      "content_type": "application/json",
      "exact_retry_result": "Returns the original delivery and workflow run identifiers without dispatching again.",
      "idempotency_key_guidance": "Generate one stable opaque key per logical delivery, reuse it only for an exact retry with the same body, and never include PHI or credentials.",
      "invalid_json_or_delivery_status": 400,
      "max_body_bytes": 256000,
      "method": "POST",
      "oversized_body_status": 413,
      "quota_exceeded_status": 429,
      "required_idempotency_header": "Idempotency-Key",
      "success_response_fields": [
        "success",
        "run_id",
        "correlation_id",
        "workflow_definition_id",
        "delivery_id",
        "duplicate"
      ],
      "success_status": 200
    },
    "deployment_enabled": false,
    "disabled_behavior": "When false, public webhook authoring and endpoint retrieval are unavailable.",
    "endpoint_retrieval": {
      "available_as_mcp_tool": false,
      "credential_handling": "The returned URL is an execution credential. Fetch it outside MCP, honor no-store, and do not place it in model context, logs, or persisted workflow JSON.",
      "handoff_guidance": "After authoring and publishing, hand the definition_id to an authorized operator or non-LLM credential client to retrieve and store the URL. An MCP-only agent is not expected to retrieve it.",
      "method": "GET",
      "operator_handoff_required": true,
      "path_template": "/developer/v1/workflows/{definition_id}/webhook-endpoint",
      "prerequisites": [
        "workflow status is active",
        "active workflow version is published"
      ],
      "required_scope": "workflow:run",
      "transport": "rest_only"
    },
    "node_type": "webhook_trigger",
    "payload": {
      "accepted_body_schema": "open_json_object",
      "configurable_payload_schema": false,
      "expression_template": "{{webhook_node_id.default.field_name}}",
      "trigger_output": "default",
      "validation_guidance": "The trigger does not configure an accepted-payload schema. Validate or branch on required fields in downstream nodes."
    },
    "provider": "generic",
    "status": "supported"
  },
  "recipes": [
    {
      "description": "JSON objects may be supplied directly in node params, bodies, and other open config fields.",
      "name": "object_literals"
    },
    {
      "description": "There is no public first-class dictionary projection node yet; compose known fields in a target action's params.",
      "name": "object_transform",
      "status": "limited"
    },
    {
      "description": "Use if for truthy/operator checks and named conditions; connect its named routing ports with edges.",
      "name": "branching"
    },
    {
      "description": "Use loop with default edges into the body and a complete edge to the post-loop continuation.",
      "name": "iteration"
    }
  ],
  "schema_version": 2
}

View OpenAPI document