Workflow Definitions

A workflow definition is a versioned blueprint that describes the steps your workflow will execute. Definitions are immutable once created -- to change a workflow, create a new definition with an incremented version.

Create a Workflow Definition

POST /v1/workflow-definitions

Creates a new workflow definition in your workspace.

Request Body

Field	Type	Required	Description
`name`	`string`	Yes	Name of the workflow (1-200 characters)
`version`	`string`	Yes	Version identifier (1-50 characters)
`description`	`string`	No	Description of the workflow (max 1000 characters)
`steps`	`Step[]`	Yes	Array of step definitions (at least one)

Step Types

Each step in the steps array must include a type field. The available types are:

Type	Description
`task`	Execute a named handler function
`wait`	Pause for a duration or until a timestamp
`condition`	Branch based on an expression
`external_event`	Wait for an external signal
`llm`	Call an LLM with tool support and guardrails
`approval`	Request human approval before continuing

Example Request

curl -X POST https://api.stevora.dev/v1/workflow-definitions \
  -H "x-api-key: stv_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "customer-onboarding",
    "version": "1.0.0",
    "description": "Automated customer onboarding with AI research",
    "steps": [
      {
        "type": "task",
        "name": "enrich-company",
        "handler": "enrichCompanyData",
        "config": { "source": "clearbit" }
      },
      {
        "type": "llm",
        "name": "generate-welcome-email",
        "model": "gpt-4o",
        "messages": [
          { "role": "user", "content": "Write a welcome email for {{companyName}}" }
        ],
        "temperature": 0.7,
        "maxTokens": 500
      },
      {
        "type": "approval",
        "name": "review-email",
        "contentKey": "welcomeEmail",
        "prompt": "Review the generated welcome email before sending"
      },
      {
        "type": "task",
        "name": "send-email",
        "handler": "sendEmail"
      }
    ]
  }'

Response `201 Created`

{
  "success": true,
  "data": {
    "id": "wfdef_abc123",
    "workspaceId": "ws_xyz789",
    "name": "customer-onboarding",
    "version": "1.0.0",
    "description": "Automated customer onboarding with AI research",
    "steps": [ ... ],
    "createdAt": "2026-04-02T12:00:00.000Z",
    "updatedAt": "2026-04-02T12:00:00.000Z"
  }
}

Error Responses

Status	Code	Cause
400	`VALIDATION_ERROR`	Invalid or missing fields in the request body
401	`AUTH_ERROR`	Missing or invalid API key

List Workflow Definitions

GET /v1/workflow-definitions

Returns all workflow definitions in your workspace.

Example Request

curl https://api.stevora.dev/v1/workflow-definitions \
  -H "x-api-key: stv_your_api_key"

Response `200 OK`

{
  "success": true,
  "data": [
    {
      "id": "wfdef_abc123",
      "workspaceId": "ws_xyz789",
      "name": "customer-onboarding",
      "version": "1.0.0",
      "description": "Automated customer onboarding with AI research",
      "steps": [ ... ],
      "createdAt": "2026-04-02T12:00:00.000Z",
      "updatedAt": "2026-04-02T12:00:00.000Z"
    }
  ]
}

Error Responses

Status	Code	Cause
401	`AUTH_ERROR`	Missing or invalid API key

Get a Workflow Definition

GET /v1/workflow-definitions/:id

Returns a single workflow definition by ID.

Path Parameters

Parameter	Type	Description
`id`	`string`	The workflow definition ID

Example Request

curl https://api.stevora.dev/v1/workflow-definitions/wfdef_abc123 \
  -H "x-api-key: stv_your_api_key"

Response `200 OK`

{
  "success": true,
  "data": {
    "id": "wfdef_abc123",
    "workspaceId": "ws_xyz789",
    "name": "customer-onboarding",
    "version": "1.0.0",
    "description": "Automated customer onboarding with AI research",
    "steps": [
      {
        "type": "task",
        "name": "enrich-company",
        "handler": "enrichCompanyData",
        "config": { "source": "clearbit" }
      }
    ],
    "createdAt": "2026-04-02T12:00:00.000Z",
    "updatedAt": "2026-04-02T12:00:00.000Z"
  }
}

Error Responses

Status	Code	Cause
401	`AUTH_ERROR`	Missing or invalid API key
404	`NOT_FOUND`	Definition does not exist or belongs to another workspace

Workflow Definitions

On this page