Skip to main content

​
Overview

A workflow is the unit of automation in Opus: a graph of steps — agents, code, human tasks and integrations — that runs against the inputs you give it. The Workflow API manages the full lifecycle of a workflow with no browser session required. You can create one, read its definition, replace it, archive it and restore it. Once a workflow exists, you run it as a case.

​
Base URL

All API requests should be made to the following base URL:

​
Authentication

All API endpoints require authentication with your Opus API key, sent in the x-service-key header.
The key is also accepted as a Bearer token (Authorization: Bearer <your_api_key>). Your key determines your identity: the acting user, your organization, and the workspaces you can target. Each endpoint additionally requires the listed workflow permission in the target workspace. A request with a missing, invalid, or expired key returns 401. Keys are also rate limited — sustained bursts return 429.
Your API key is a unique, secret credential. Store it securely and never expose it in client-side code.

​
Two Ways To Build A Workflow

Define it yourself

POST /workflow with the nodes and edges you want. You control the graph exactly. Best when you already know the steps, or you are generating workflows from your own system.

Generate it from a prompt

POST /workflow/generate with a description in plain language. Opus AI agents design and build the graph, and you poll the run until it finishes.
Both produce an ordinary workflow — the same workflowId, readable with the same Get Workflow Details call, editable with the same Update a Workflow call. The choice is only about how the first version gets written.

​
Lifecycle

1

Create

Create a workflow directly, or generate one from a prompt. Either way you get a workflowId.
2

Read

Get Workflow Details returns the full definition, including the input schema you need to run it.
3

Update

Update a Workflow replaces the definition and mints a new version. Earlier versions stay retrievable.
4

Run

Execute the workflow as a case.
5

Archive or restore

Archive takes a workflow out of listings; Restore brings it back.

​
Versioning

Every update mints a new version rather than editing in place, so a workflow is a history, not a single document.
  • Update a Workflow is a replace — send the whole definition, because anything absent is removed from the new version.
  • Get Workflow Details reads the latest version by default, and any earlier one by version UUID, semantic version or version number.
  • A workflow with an active version cannot be archived — deactivate it first.

​
Defining Nodes And Edges

When you send a workflow definition, each node’s handler_class determines the shape of its process, and every node carries an input and output schema.

Node Process Types

Which process object goes with which node type

Variable Schemas

How a node declares the variables it takes in and hands on

​
Generation Runs

These notes apply only to Generate Workflow, not to the other endpoints.
One run at a time per workflow. Starting a second run while one is active returns 409. Cancel the current run or wait for it to finish.
  • Polling: Progress updates continuously; polling every 3–10 seconds is plenty.
  • Time limit: Runs that exceed 25 minutes are cancelled automatically.
  • Files: Attach only files your user can access. A file that can’t be read is skipped with a note in the run’s task results rather than failing the run.

​
Available Endpoints

​
Managing Workflows

Create a Workflow

Create a workflow, optionally pre-populated with nodes and edges

Get Workflow Details

Retrieve the workflow object — name, status, nodes and edges

Update a Workflow

Replace a workflow’s definition and mint a new version

Archive a Workflow

Archive a workflow, removing it from listings

Restore a Workflow

Un-archive a workflow, returning it to listings

​
Generating Workflows

Generate Workflow

Start a new workflow generation run from a prompt

Get Run Status

Poll a generation run until it completes

Cancel a Run

Stop an in-progress generation run