> ## Documentation Index
> Fetch the complete documentation index at: https://operativusai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflows API — Create and Execute Pipelines

> Design, manage, and execute deterministic multi-step agent workflows with CRUD operations, step management, cloning, and paginated run history.

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.

<ParamField query="page" type="number" default="0">
  Zero-based page index.
</ParamField>

<ParamField query="size" type="number" default="20">
  Number of workflows per page.
</ParamField>

<ParamField query="sort" type="string">
  Sort field and direction, e.g. `createdAt,desc`.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url "http://localhost:8080/api/v1/workflows?page=0&size=20" \
    --header "Authorization: Bearer {token}"
  ```
</CodeGroup>

**Example response**

```json theme={null}
{
  "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`.

<ParamField body="name" type="string" required>
  Human-readable name for the workflow.
</ParamField>

<ParamField body="description" type="string">
  Optional description of the workflow's purpose.
</ParamField>

<ParamField body="steps" type="object[]">
  Initial steps to create with the workflow. You can also add steps after creation via the steps endpoint.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  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": []
    }'
  ```
</CodeGroup>

**Example response**

```json theme={null}
{
  "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.

<ParamField path="id" type="string" required>
  The workflow identifier.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url "http://localhost:8080/api/v1/workflows/wf_abc123" \
    --header "Authorization: Bearer {token}"
  ```
</CodeGroup>

***

## Update a workflow

```
PATCH /api/v1/workflows/{id}
```

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

<ParamField path="id" type="string" required>
  The workflow identifier.
</ParamField>

<ParamField body="name" type="string">
  Updated name for the workflow.
</ParamField>

<ParamField body="description" type="string">
  Updated description.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  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" }'
  ```
</CodeGroup>

***

## Delete a workflow

```
DELETE /api/v1/workflows/{id}
```

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

<ParamField path="id" type="string" required>
  The workflow identifier.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request DELETE \
    --url "http://localhost:8080/api/v1/workflows/wf_abc123" \
    --header "Authorization: Bearer {token}"
  ```
</CodeGroup>

***

## List workflow steps

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

Returns all steps for a workflow in their ordered sequence.

<ParamField path="id" type="string" required>
  The workflow identifier.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url "http://localhost:8080/api/v1/workflows/wf_abc123/steps" \
    --header "Authorization: Bearer {token}"
  ```
</CodeGroup>

**Example response**

```json theme={null}
[
  {
    "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`.

<ParamField path="id" type="string" required>
  The workflow to add the step to.
</ParamField>

<ParamField body="agentId" type="string" required>
  The agent to invoke for this step.
</ParamField>

<ParamField body="action" type="string" required>
  The prompt or instruction sent to the agent for this step.
</ParamField>

<ParamField body="stepOrder" type="number">
  The position in the sequence, starting from 1. Steps execute in ascending order.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  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
    }'
  ```
</CodeGroup>

***

## Remove a step

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

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

<ParamField path="id" type="string" required>
  The workflow identifier.
</ParamField>

<ParamField path="stepId" type="string" required>
  The step identifier to remove.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request DELETE \
    --url "http://localhost:8080/api/v1/workflows/wf_abc123/steps/step_001" \
    --header "Authorization: Bearer {token}"
  ```
</CodeGroup>

***

## 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`.

<ParamField path="id" type="string" required>
  The workflow to clone.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url "http://localhost:8080/api/v1/workflows/wf_abc123/clone" \
    --header "Authorization: Bearer {token}"
  ```
</CodeGroup>

**Example response**

```json theme={null}
{
  "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.

<ParamField path="id" type="string" required>
  The workflow to execute.
</ParamField>

<ParamField body="input" type="string" required>
  The initial input text passed to the first step.
</ParamField>

<ParamField body="sessionId" type="string">
  UUID of an existing session to associate with this run. A new session is created if omitted.
</ParamField>

<ResponseField name="jobId" type="string">
  Background job identifier for tracking execution.
</ResponseField>

<ResponseField name="workflowId" type="string">
  The workflow that was triggered.
</ResponseField>

<ResponseField name="sessionId" type="string">
  The session associated with this run.
</ResponseField>

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```
</CodeGroup>

**Example response**

```json theme={null}
{
  "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.

<ParamField path="workflowId" type="string" required>
  The workflow whose run history to fetch.
</ParamField>

<ParamField query="page" type="number" default="0">
  Zero-based page index.
</ParamField>

<ParamField query="size" type="number" default="20">
  Number of runs per page. Maximum enforced by server configuration.
</ParamField>

<ResponseField name="content" type="object[]">
  Array of `WorkflowRunResponse` objects.

  <Expandable title="WorkflowRunResponse fields">
    <ResponseField name="id" type="string">
      Unique run identifier.
    </ResponseField>

    <ResponseField name="workflowId" type="string">
      The workflow this run belongs to.
    </ResponseField>

    <ResponseField name="sessionId" type="string">
      The session associated with this run.
    </ResponseField>

    <ResponseField name="status" type="string">
      Run status: `QUEUED`, `RUNNING`, `COMPLETED`, `FAILED`, or `PAUSED`.
    </ResponseField>

    <ResponseField name="currentStepOrder" type="number">
      The index of the step currently executing. `null` for completed or failed runs.
    </ResponseField>

    <ResponseField name="durationMs" type="number">
      Total wall-clock duration in milliseconds from creation to last update. `null` for in-flight runs.
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO-8601 timestamp when the run was submitted.
    </ResponseField>

    <ResponseField name="updatedAt" type="string">
      ISO-8601 timestamp of the last status change.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url "http://localhost:8080/api/v1/workflows/wf_abc123/runs?page=0&size=10" \
    --header "Authorization: Bearer {token}"
  ```
</CodeGroup>

**Example response**

```json theme={null}
{
  "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.

<ParamField path="runId" type="string" required>
  The run identifier of the paused workflow run.
</ParamField>

<ParamField body="output" type="string" required>
  The human-approved content to pass as input to the next workflow step.
</ParamField>

<ResponseField name="jobId" type="string">
  Background job identifier for the resumed execution.
</ResponseField>

<ResponseField name="runId" type="string">
  The run that was resumed.
</ResponseField>

<CodeGroup>
  ```bash cURL theme={null}
  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." }'
  ```
</CodeGroup>

**Example response**

```json theme={null}
{
  "jobId": "job_5e3f2b91-4c2a-4d1b-9e7f-bcd345efg012",
  "runId": "run_7f3a9c12"
}
```