Hyperfold AI

Workflow API

Create, manage, and monitor multi-step automated workflows.

Overview

The Workflow API allows you to define and manage automated processes that coordinate multiple agents and actions. Workflows can be triggered by events, schedules, or manual invocation.

EndpointPurpose
/v1/workflowsList and create workflows
/v1/workflows/:id/executionsView execution history
/v1/workflows/:id/triggersManage workflow triggers
/v1/workflows/templatesPre-built workflow templates

Manage Workflows

bash
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
# GET /v1/workflows
# List all workflows
 
curl -X GET https://api.hyperfold.io/v1/workflows \
  -H "Authorization: Bearer hf_live_xxx" \
  -H "X-Project-ID: proj_acme"
 
# Response
{
  "data": [
    {
      "id": "wf_order_fulfillment",
      "name": "order-fulfillment",
      "description": "Process orders from confirmation to shipment",
      "version": "v3",
      "status": "active",
      "steps": 4,
      "triggers": ["order.created"],
      "executions_24h": 456,
      "success_rate": 0.995
    },
    {
      "id": "wf_cart_abandonment",
      "name": "cart-abandonment",
      "description": "Re-engage customers with abandoned carts",
      "version": "v2",
      "status": "active",
      "steps": 3,
      "triggers": ["cart.abandoned"],
      "executions_24h": 89
    }
  ]
}
 
# POST /v1/workflows
# Create a new workflow
 
curl -X POST https://api.hyperfold.io/v1/workflows \
  -H "Authorization: Bearer hf_live_xxx" \
  -H "X-Project-ID: proj_acme" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "vip-order-alert",
    "description": "Alert sales team for high-value orders",
    "steps": [
      {
        "id": "check_value",
        "type": "condition",
        "config": {
          "expression": "order.total > 500"
        },
        "on_true": "notify_team",
        "on_false": "end"
      },
      {
        "id": "notify_team",
        "type": "action",
        "agent": "notification-agent",
        "config": {
          "channels": ["slack", "email"],
          "template": "vip-order"
        }
      }
    ],
    "triggers": [
      {"type": "event", "event": "order.created"}
    ]
  }'
 
# Response
{
  "id": "wf_vip_alert",
  "name": "vip-order-alert",
  "version": "v1",
  "status": "active",
  "created_at": "2025-01-20T10:00:00Z"
}

Step Types

TypeDescription
actionExecute an agent or external action
conditionBranch based on expression
parallelExecute multiple steps concurrently
waitDelay execution for duration or event
loopIterate over collection

Executions

bash
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
# GET /v1/workflows/:id/executions
# List workflow executions
 
curl -X GET "https://api.hyperfold.io/v1/workflows/wf_order_fulfillment/executions?\
status=completed&\
since=24h&\
limit=50" \
  -H "Authorization: Bearer hf_live_xxx"
 
# Response
{
  "data": [
    {
      "id": "exec_abc123",
      "workflow_id": "wf_order_fulfillment",
      "version": "v3",
      "status": "completed",
      "trigger": {"type": "event", "event": "order.created", "data": {"order_id": "ord_xyz"}},
      "started_at": "2025-01-20T10:00:00Z",
      "completed_at": "2025-01-20T10:00:03Z",
      "duration_ms": 3100,
      "steps_completed": 4,
      "output": {"shipment_id": "ship_xyz", "tracking": "1Z999..."}
    }
  ],
  "summary": {
    "total": 456,
    "completed": 454,
    "failed": 2,
    "avg_duration_ms": 3250
  }
}
 
# GET /v1/workflows/:id/executions/:exec_id
# Get execution details
 
curl -X GET https://api.hyperfold.io/v1/workflows/wf_order_fulfillment/executions/exec_abc123 \
  -H "Authorization: Bearer hf_live_xxx"
 
# Response includes step-by-step trace
{
  "id": "exec_abc123",
  "workflow_id": "wf_order_fulfillment",
  "status": "completed",
  "input": {"order_id": "ord_xyz"},
  "output": {"shipment_id": "ship_xyz"},
  "steps": [
    {
      "id": "validate_order",
      "status": "completed",
      "agent": "order-validator",
      "started_at": "2025-01-20T10:00:00.100Z",
      "completed_at": "2025-01-20T10:00:00.220Z",
      "duration_ms": 120,
      "input": {"order_id": "ord_xyz"},
      "output": {"valid": true, "items": 2}
    },
    {
      "id": "reserve_inventory",
      "status": "completed",
      "agent": "inventory-manager",
      "duration_ms": 340,
      "output": {"reserved": true, "items": [{"sku": "SHOE-001", "qty": 1}]}
    },
    {
      "id": "create_shipment",
      "status": "completed",
      "agent": "fulfillment-agent",
      "duration_ms": 2100,
      "output": {"shipment_id": "ship_xyz", "carrier": "USPS"}
    },
    {
      "id": "notify_customer",
      "status": "completed",
      "agent": "notification-agent",
      "duration_ms": 450,
      "output": {"email_sent": true, "sms_sent": true}
    }
  ]
}
 
# POST /v1/workflows/:id/execute
# Manually trigger workflow
 
curl -X POST https://api.hyperfold.io/v1/workflows/wf_order_fulfillment/execute \
  -H "Authorization: Bearer hf_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {"order_id": "ord_manual_123"},
    "async": true
  }'

Triggers

bash
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
# GET /v1/workflows/:id/triggers
# List workflow triggers
 
curl -X GET https://api.hyperfold.io/v1/workflows/wf_order_fulfillment/triggers \
  -H "Authorization: Bearer hf_live_xxx"
 
# Response
{
  "data": [
    {
      "id": "trg_abc123",
      "type": "event",
      "event": "order.created",
      "filter": null,
      "status": "active",
      "executions_24h": 456
    }
  ]
}
 
# POST /v1/workflows/:id/triggers
# Add a trigger
 
curl -X POST https://api.hyperfold.io/v1/workflows/wf_order_fulfillment/triggers \
  -H "Authorization: Bearer hf_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "schedule",
    "schedule": "0 6 * * *",
    "timezone": "America/Los_Angeles"
  }'
 
# DELETE /v1/workflows/:id/triggers/:trigger_id
# Remove a trigger
 
curl -X DELETE https://api.hyperfold.io/v1/workflows/wf_order_fulfillment/triggers/trg_abc123 \
  -H "Authorization: Bearer hf_live_xxx"

Trigger Types

TypeDescription
eventSystem events (order.created, etc.)
scheduleCron schedule
webhookExternal HTTP trigger
manualAPI or CLI invocation only

Templates

bash
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
# GET /v1/workflows/templates
# List available workflow templates
 
curl -X GET https://api.hyperfold.io/v1/workflows/templates \
  -H "Authorization: Bearer hf_live_xxx"
 
# Response
{
  "data": [
    {
      "id": "tmpl_order_fulfillment",
      "name": "Order Fulfillment",
      "description": "Standard order processing workflow",
      "category": "fulfillment",
      "steps": 4,
      "estimated_setup": "5 minutes"
    },
    {
      "id": "tmpl_cart_recovery",
      "name": "Cart Recovery",
      "description": "Abandoned cart email sequence",
      "category": "marketing",
      "steps": 3
    },
    {
      "id": "tmpl_inventory_sync",
      "name": "Inventory Sync",
      "description": "Sync inventory across channels",
      "category": "operations",
      "steps": 2
    }
  ]
}
 
# POST /v1/workflows/from-template
# Create workflow from template
 
curl -X POST https://api.hyperfold.io/v1/workflows/from-template \
  -H "Authorization: Bearer hf_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "tmpl_order_fulfillment",
    "name": "my-order-workflow",
    "config": {
      "notification_channels": ["email", "slack"],
      "auto_fulfill": true
    }
  }'
Templates provide pre-configured workflows for common use cases. Customize them after creation to fit your specific needs.
For CLI workflow management, see workflow register and workflow trigger.