Documentation Index Fetch the complete documentation index at: https://operativusai.mintlify.app/llms.txt
Use this file to discover all available pages before exploring further.
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 Returns a paginated list of workflow definitions for the authenticated tenant.
Number of workflows per page.
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 Creates a new workflow definition. Returns 201 Created with the persisted WorkflowDTO.
Human-readable name for the workflow.
Optional description of the workflow’s purpose.
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.
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.
Updated name for the workflow.
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.
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.
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.
The workflow to add the step to.
The agent to invoke for this step.
The prompt or instruction sent to the agent for this step.
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.
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.
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.
The initial input text passed to the first step.
UUID of an existing session to associate with this run. A new session is created if omitted.
Background job identifier for tracking execution.
The workflow that was triggered.
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.
The workflow whose run history to fetch.
Number of runs per page. Maximum enforced by server configuration.
Array of WorkflowRunResponse objects. Show WorkflowRunResponse fields
The workflow this run belongs to.
The session associated with this run.
Run status: QUEUED, RUNNING, COMPLETED, FAILED, or PAUSED.
The index of the step currently executing. null for completed or failed runs.
Total wall-clock duration in milliseconds from creation to last update. null for in-flight runs.
ISO-8601 timestamp when the run was submitted.
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.
The run identifier of the paused workflow run.
The human-approved content to pass as input to the next workflow step.
Background job identifier for the resumed execution.
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" }