Workflows API — Create and Execute Pipelines

Workflows are deterministic, multi-step pipelines that orchestrate agent tasks in sequence. Unlike probabilistic agent runs, a workflow defines a fixed series of steps with persistent state — making them suitable for repeatable business processes, data pipelines, and structured automation that requires auditable execution history. All requests require a valid bearer token in the Authorization header. Workflow access is tenant-scoped: operations on workflows belonging to another organization return 404 Not Found.

List workflows

GET /api/v1/workflows

Returns a paginated list of workflow definitions for the authenticated tenant.

number

default:"0"

Zero-based page index.

number

default:"20"

Number of workflows per page.

string

Sort field and direction, e.g. createdAt,desc.

curl --request GET \
  --url "http://localhost:8080/api/v1/workflows?page=0&size=20" \
  --header "Authorization: Bearer {token}"

Example response

{
  "content": [
    {
      "id": "wf_abc123",
      "name": "Daily Market Briefing",
      "description": "Fetches stock prices and generates a daily summary report.",
      "steps": []
    }
  ],
  "totalElements": 1,
  "totalPages": 1,
  "number": 0
}

Create a workflow

POST /api/v1/workflows

Creates a new workflow definition. Returns 201 Created with the persisted WorkflowDTO.

string

required

Human-readable name for the workflow.

string

Optional description of the workflow’s purpose.

object[]

Initial steps to create with the workflow. You can also add steps after creation via the steps endpoint.

curl --request POST \
  --url "http://localhost:8080/api/v1/workflows" \
  --header "Authorization: Bearer {token}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Daily Market Briefing",
    "description": "Fetches stock prices and generates a daily summary report.",
    "steps": []
  }'

Example response

{
  "id": "wf_abc123",
  "name": "Daily Market Briefing",
  "description": "Fetches stock prices and generates a daily summary report.",
  "steps": []
}

Get a workflow

GET /api/v1/workflows/{id}

Fetches a single workflow definition by ID. Returns 404 Not Found if the workflow does not exist or belongs to another tenant.

string

required

The workflow identifier.

curl --request GET \
  --url "http://localhost:8080/api/v1/workflows/wf_abc123" \
  --header "Authorization: Bearer {token}"

Update a workflow

PATCH /api/v1/workflows/{id}

Updates a workflow’s metadata (name, description). Send only the fields you want to change.

string

required

The workflow identifier.

string

Updated name for the workflow.

string

Updated description.

curl --request PATCH \
  --url "http://localhost:8080/api/v1/workflows/wf_abc123" \
  --header "Authorization: Bearer {token}" \
  --header "Content-Type: application/json" \
  --data '{ "name": "Daily Market Briefing v2" }'

Delete a workflow

DELETE /api/v1/workflows/{id}

Permanently deletes a workflow and all its associated steps. Returns 204 No Content.

string

required

The workflow identifier.

curl --request DELETE \
  --url "http://localhost:8080/api/v1/workflows/wf_abc123" \
  --header "Authorization: Bearer {token}"

List workflow steps

GET /api/v1/workflows/{id}/steps

Returns all steps for a workflow in their ordered sequence.

string

required

The workflow identifier.

curl --request GET \
  --url "http://localhost:8080/api/v1/workflows/wf_abc123/steps" \
  --header "Authorization: Bearer {token}"

Example response

[
  {
    "id": "step_001",
    "stepOrder": 1,
    "agentId": "finance_agent",
    "action": "Fetch current prices for NVDA, AAPL, and MSFT."
  },
  {
    "id": "step_002",
    "stepOrder": 2,
    "agentId": "procurator_assistant",
    "action": "Summarize the price data into a 3-paragraph executive briefing."
  }
]

Add a step

POST /api/v1/workflows/{id}/steps

Appends a new step to the workflow. Returns 201 Created with the persisted WorkflowStepDTO.

string

required

The workflow to add the step to.

string

required

The agent to invoke for this step.

string

required

The prompt or instruction sent to the agent for this step.

number

The position in the sequence, starting from 1. Steps execute in ascending order.

curl --request POST \
  --url "http://localhost:8080/api/v1/workflows/wf_abc123/steps" \
  --header "Authorization: Bearer {token}" \
  --header "Content-Type: application/json" \
  --data '{
    "agentId": "finance_agent",
    "action": "Fetch current prices for NVDA, AAPL, and MSFT.",
    "stepOrder": 1
  }'

Remove a step

DELETE /api/v1/workflows/{id}/steps/{stepId}

Removes a specific step from a workflow. Returns 204 No Content.

string

required

The workflow identifier.

string

required

The step identifier to remove.

curl --request DELETE \
  --url "http://localhost:8080/api/v1/workflows/wf_abc123/steps/step_001" \
  --header "Authorization: Bearer {token}"

Clone a workflow

POST /api/v1/workflows/{id}/clone

Creates a deep copy of the workflow and all its steps. The cloned workflow’s name is appended with " (Copy)". Returns 201 Created.

string

required

The workflow to clone.

curl --request POST \
  --url "http://localhost:8080/api/v1/workflows/wf_abc123/clone" \
  --header "Authorization: Bearer {token}"

Example response

{
  "id": "wf_def456",
  "name": "Daily Market Briefing (Copy)",
  "description": "Fetches stock prices and generates a daily summary report.",
  "steps": [...]
}

Execute a workflow

POST /api/v1/workflows/{id}/run

Submits the workflow for asynchronous execution. Returns immediately with a jobId, workflowId, and sessionId. The workflow executes each step in order, passing outputs between steps.

string

required

The workflow to execute.

string

required

The initial input text passed to the first step.

string

UUID of an existing session to associate with this run. A new session is created if omitted.

string

Background job identifier for tracking execution.

string

The workflow that was triggered.

string

The session associated with this run.

curl --request POST \
  --url "http://localhost:8080/api/v1/workflows/wf_abc123/run" \
  --header "Authorization: Bearer {token}" \
  --header "Content-Type: application/json" \
  --data '{
    "input": "Generate today'\''s market briefing.",
    "sessionId": "550e8400-e29b-41d4-a716-446655440000"
  }'

Example response

{
  "jobId": "job_9d2e4c78-3a1b-4f5e-8d6c-xyz789abc012",
  "workflowId": "wf_abc123",
  "sessionId": "550e8400-e29b-41d4-a716-446655440000"
}

List workflow runs

GET /api/v1/workflows/{workflowId}/runs

Returns a paginated list of historical execution records for a workflow, ordered newest first. Returns 200 OK with an empty page if the workflow exists but has no runs yet.

string

required

The workflow whose run history to fetch.

number

default:"0"

Zero-based page index.

number

default:"20"

Number of runs per page. Maximum enforced by server configuration.

object[]

Array of WorkflowRunResponse objects.

Show WorkflowRunResponse fields

string

Unique run identifier.

string

The workflow this run belongs to.

string

The session associated with this run.

string

Run status: QUEUED, RUNNING, COMPLETED, FAILED, or PAUSED.

number

The index of the step currently executing. null for completed or failed runs.

number

Total wall-clock duration in milliseconds from creation to last update. null for in-flight runs.

string

ISO-8601 timestamp when the run was submitted.

string

ISO-8601 timestamp of the last status change.

curl --request GET \
  --url "http://localhost:8080/api/v1/workflows/wf_abc123/runs?page=0&size=10" \
  --header "Authorization: Bearer {token}"

Example response

{
  "content": [
    {
      "id": "run_7f3a9c12",
      "workflowId": "wf_abc123",
      "sessionId": "550e8400-e29b-41d4-a716-446655440000",
      "status": "COMPLETED",
      "currentStepOrder": null,
      "durationMs": 8450,
      "createdAt": "2026-05-06T09:00:00Z",
      "updatedAt": "2026-05-06T09:00:08Z"
    }
  ],
  "totalElements": 1,
  "totalPages": 1,
  "number": 0
}

Resume a paused workflow run

POST /api/v1/workflows/runs/{runId}/resume

Resumes a workflow run that paused at a Human-in-the-Loop step. Provide the human-approved output to inject into the next step. Returns a new jobId for the resumed execution.

string

required

The run identifier of the paused workflow run.

string

required

The human-approved content to pass as input to the next workflow step.

string

Background job identifier for the resumed execution.

string

The run that was resumed.

curl --request POST \
  --url "http://localhost:8080/api/v1/workflows/runs/run_7f3a9c12/resume" \
  --header "Authorization: Bearer {token}" \
  --header "Content-Type: application/json" \
  --data '{ "output": "Approved. Proceed with the summarization step." }'

Example response

{
  "jobId": "job_5e3f2b91-4c2a-4d1b-9e7f-bcd345efg012",
  "runId": "run_7f3a9c12"
}

Agents

Knowledge & Sessions

Workflows & Teams

Workflows API — Create and Execute Pipelines

List workflows

Create a workflow

Get a workflow

Update a workflow

Delete a workflow

List workflow steps

Add a step

Remove a step

Clone a workflow

Execute a workflow

List workflow runs

Resume a paused workflow run

​List workflows

​Create a workflow

​Get a workflow

​Update a workflow

​Delete a workflow

​List workflow steps

​Add a step

​Remove a step

​Clone a workflow

​Execute a workflow

​List workflow runs

​Resume a paused workflow run

List workflows

Create a workflow

Get a workflow

Update a workflow

Delete a workflow

List workflow steps

Add a step

Remove a step

Clone a workflow

Execute a workflow

List workflow runs

Resume a paused workflow run