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

# 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

# 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

# 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

# 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
    }
  }'