Skip to main content

Workflows

A workflow is a structured alternative to free-form agent reasoning — an explicit sequence of steps (collect info, check availability, confirm, escalate) instead of leaving the whole conversation to the model's judgment. Bind a workflow to an agent via workflowVersionId and the runtime drives the call through it directly.

Workflows exist for the same reason state machines exist anywhere: cases where "the model figures it out" is too unpredictable and you want a guaranteed set of steps to happen in order — appointment scheduling and structured intake are the primary use cases today.

The draft/publish model​

Workflows use the same lifecycle as agents: create opens a draft, nothing runs live until you publish, and every publish is a new numbered version.

curl -X POST https://convostack.ai/api/workflows \
  -H "Authorization: Bearer cak_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Appointment scheduling"}'

curl -X POST https://convostack.ai/api/workflows/{id}/publish \
  -H "Authorization: Bearer cak_live_..."

Templates​

GET /api/workflows/templates lists curated, ready-to-use workflow templates. Instantiate one into your own editable draft rather than building from a blank definition:

curl -X POST https://convostack.ai/api/workflows/templates/{templateId}/instantiate \
  -H "Authorization: Bearer cak_live_..." \
  -H "Content-Type: application/json" \
  -d '{"parameters": {}}'

Validating and simulating before you publish​

Two ways to check a workflow before it ever touches a real call:

# Static structural check — is this definition well-formed?
curl -X POST https://convostack.ai/api/workflows/validate \
  -H "Authorization: Bearer cak_live_..." \
  -H "Content-Type: application/json" \
  -d '{ /* a WorkflowDefinition */ }'

# Deterministic simulation — run a scripted sequence of steps against it
curl -X POST https://convostack.ai/api/workflows/{id}/simulate \
  -H "Authorization: Bearer cak_live_..." \
  -H "Content-Type: application/json" \
  -d '{"steps": [ /* simulated turns */ ]}'

GET /api/workflows/{id}/readiness reports whether the workflow (live or draft) is actually launch-ready — the same kind of checklist agents get, scoped to workflow-specific concerns like unreachable steps or missing tool bindings.

Watching runs​

# Recent runs for one workflow
curl https://convostack.ai/api/workflows/{id}/runs \
  -H "Authorization: Bearer cak_live_..."

# Full detail for a specific run, keyed by the conversation it drove
curl https://convostack.ai/api/workflows/runs/{conversationId} \
  -H "Authorization: Bearer cak_live_..."

# Org-wide operational overview across every workflow
curl https://convostack.ai/api/workflows/ops/overview \
  -H "Authorization: Bearer cak_live_..."

ops/overview and ops/trends are the aggregate views — how many runs, which gates/tools are getting hit, trend over time — useful for a dashboard rather than debugging one specific call.