dgi.workflow-request.create

Capture a user's request for a workflow that does not exist yet

Capture a request for a workflow/capability that does not exist yet.

Inputs:

• organization_uuid: UUID of the organization (required)
• user_uuid: deprecated; the request is always owned by the authenticated caller
• requested_capability: natural-language description of the desired capability (required)
• requested_workflow_type: optional best-guess canonical workflow name
• conversation_uuid: optional originating conversation uuid
• source: origin surface (default "dgi")
• context: free-form triage context snapshot

Outputs (terminal state_data):

• request_uuid: WorkflowRequest.uuid
• status: lifecycle status ("pending")
• created_at: ISO-8601 timestamp

Failure reasons:

• organization_not_found_or_unauthorized
• validation_failed
• database_error

Overview

Property	Value
Workflow type	Atomic
Library	App-dgi
Version	1.0

Input Schema

Field	Type	Required	Default	Description
organization_uuid	uuid	Yes	—	UUID of the organization that owns the request
user_uuid	uuid	No	—	Deprecated. The request is always owned by the authenticated caller; this value is not used for authorization or attribution
requested_capability	string	Yes	—	Natural-language description of the desired capability (max 4000 chars)
requested_workflow_type	string	No	—	Optional best-guess canonical workflow name (max 255 chars)
conversation_uuid	string	No	—	Optional originating chat/DGI conversation uuid
source	string	No	—	Origin surface (default 'dgi', max 32 chars)
context	json	No	—	Free-form triage context snapshot (reasoning trace, last message, ...)

Output Schema

Field	Type	Required	Default	Description
request_uuid	uuid	Yes	—	Created WorkflowRequest.uuid (external identifier)
status	string	Yes	—	Lifecycle status of the request (pending on creation)
created_at	string	Yes	—	ISO-8601 creation timestamp
failure_reason	string	No	—	Controlled-vocabulary failure key OR raw engine message
error	string	No	—	Human-readable error detail (echoed by action_fail)
error_type	string	No	—	Exception class name (engine-stamped)
failed_at_state	string	No	—	State name where the failure occurred (engine-stamped)
failed_step	string	No	—	DAG step name where the failure occurred (engine-stamped)
failed_layer	string	No	—	DAG layer where the failure occurred (engine-stamped)
organization_uuid	uuid	No	—	Organization UUID echoed by action_fail
user_uuid	uuid	No	—	User UUID echoed by action_fail

States

State	Initial	Terminal	Success	Auto-advance	Description
pending	Yes	No	—	execute	—
completed	No	Yes	Yes	—	—
failed	No	Yes	No	—	—

State Diagram

Transitions

From	Action	To	Description
pending	execute	completed	—
* (any state)	fail	failed	—

API Usage

POST /api/workflows/start
Content-Type: application/json

{
  "workflow_type": "dgi.workflow-request.create",
  "initial_data": {
    "organization_uuid": "value",
    "requested_capability": "value"
  }
}