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

# Introduction

> Create, read, update, archive and restore Opus workflows through the API

## 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](/api-reference/v1-case/case-introduction).

## Base URL

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

```text theme={null}
https://operator.opus.com/api/v1/workflow/
```

## Authentication

All API endpoints require authentication with your Opus API key, sent in the `x-service-key` header.

```text theme={null}
x-service-key: <your_api_key>
```

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

<Note>
  Your API key is a unique, secret credential. Store it securely and never expose it in client-side code.
</Note>

## Two Ways To Build A Workflow

<CardGroup cols={2}>
  <Card title="Define it yourself" icon="diagram-project" href="/api-reference/v1-workflow-generation/create-workflow">
    `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.
  </Card>

  <Card title="Generate it from a prompt" icon="wand-magic-sparkles" href="/api-reference/v1-workflow-generation/generate-headless">
    `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.
  </Card>
</CardGroup>

Both produce an ordinary workflow — the same `workflowId`, readable with the same [Get Workflow Details](/api-reference/v1-workflow-generation/get-workflow-details) call, editable with the same [Update a Workflow](/api-reference/v1-workflow-generation/update-workflow) call. The choice is only about how the first version gets written.

## Lifecycle

<Steps>
  <Step title="Create">
    [Create a workflow](/api-reference/v1-workflow-generation/create-workflow) directly, or [generate one](/api-reference/v1-workflow-generation/generate-headless) from a prompt. Either way you get a `workflowId`.
  </Step>

  <Step title="Read">
    [Get Workflow Details](/api-reference/v1-workflow-generation/get-workflow-details) returns the full definition, including the input schema you need to run it.
  </Step>

  <Step title="Update">
    [Update a Workflow](/api-reference/v1-workflow-generation/update-workflow) replaces the definition and mints a new version. Earlier versions stay retrievable.
  </Step>

  <Step title="Run">
    Execute the workflow as a [case](/api-reference/v1-case/case-introduction).
  </Step>

  <Step title="Archive or restore">
    [Archive](/api-reference/v1-workflow-generation/archive-workflow) takes a workflow out of listings; [Restore](/api-reference/v1-workflow-generation/restore-workflow) brings it back.
  </Step>
</Steps>

## 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](/api-reference/v1-workflow-generation/update-workflow) is a **replace** — send the whole definition, because anything absent is removed from the new version.
* [Get Workflow Details](/api-reference/v1-workflow-generation/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.

<CardGroup cols={2}>
  <Card title="Node Process Types" icon="sitemap" href="/api-reference/v1-workflow-generation/node-process-types">
    Which process object goes with which node type
  </Card>

  <Card title="Variable Schemas" icon="brackets-curly" href="/api-reference/v1-workflow-generation/variable-schemas">
    How a node declares the variables it takes in and hands on
  </Card>
</CardGroup>

## Generation Runs

These notes apply only to [Generate Workflow](/api-reference/v1-workflow-generation/generate-headless), not to the other endpoints.

<Note>
  **One run at a time** per workflow. Starting a second run while one is active returns `409`. [Cancel the current run](/api-reference/v1-workflow-generation/cancel-run) or wait for it to finish.
</Note>

* **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

<CardGroup cols={2}>
  <Card title="Create a Workflow" icon="plus" href="/api-reference/v1-workflow-generation/create-workflow">
    Create a workflow, optionally pre-populated with nodes and edges
  </Card>

  <Card title="Get Workflow Details" icon="diagram-project" href="/api-reference/v1-workflow-generation/get-workflow-details">
    Retrieve the workflow object — name, status, nodes and edges
  </Card>

  <Card title="Update a Workflow" icon="pen-to-square" href="/api-reference/v1-workflow-generation/update-workflow">
    Replace a workflow's definition and mint a new version
  </Card>

  <Card title="Archive a Workflow" icon="box-archive" href="/api-reference/v1-workflow-generation/archive-workflow">
    Archive a workflow, removing it from listings
  </Card>

  <Card title="Restore a Workflow" icon="arrow-rotate-left" href="/api-reference/v1-workflow-generation/restore-workflow">
    Un-archive a workflow, returning it to listings
  </Card>
</CardGroup>

### Generating Workflows

<CardGroup cols={2}>
  <Card title="Generate Workflow" icon="wand-magic-sparkles" href="/api-reference/v1-workflow-generation/generate-headless">
    Start a new workflow generation run from a prompt
  </Card>

  <Card title="Get Run Status" icon="spinner" href="/api-reference/v1-workflow-generation/get-run-status">
    Poll a generation run until it completes
  </Card>

  <Card title="Cancel a Run" icon="circle-stop" href="/api-reference/v1-workflow-generation/cancel-run">
    Stop an in-progress generation run
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.