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

# Overview

> Run workflows and retrieve their results through the Case API

## Overview

A **case** is a single run of a workflow. The Case API lets you create a case, provide its inputs, execute it, and retrieve its output — entirely through the API. Execution is asynchronous: you either poll for status or receive the result on a callback URL.

## Base URL

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

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

## Authentication

All Case 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>
```

A request with a missing, invalid, or expired key returns `401`.

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

## Case Flow

The typical flow for running a workflow through the API follows these steps:

<Steps>
  <Step title="Get the Input Schema">
    Fetch the workflow's input schema with [Get Workflow Details](/api-reference/v1-workflow-generation/get-workflow-details) so you know which inputs the case expects.
  </Step>

  <Step title="Initiate the Case">
    Create a case for the workflow using `POST /case` and save the returned `caseId` — every subsequent call requires it.
  </Step>

  <Step title="Upload Files (if needed)">
    If the workflow has `file` or `array_files` inputs, upload each file first via the [File API](/api-reference/v1-file/file-introduction) and reference the returned `fileUrl` in your payload.
  </Step>

  <Step title="Execute the Case">
    Run the case using `POST /case/{caseId}/execute` with the input schema populated with values. Optionally pass a `callbackUrl` to be notified when the run finishes.
  </Step>

  <Step title="Track Progress">
    Poll `GET /case/{caseId}/status` until the case reaches a terminal status — or skip polling and wait for your `callbackUrl` to be called. Use [Case Audit Log](/api-reference/v1-case/case-audit-log) for a per-node view.
  </Step>

  <Step title="Get the Results">
    Once the case completes, fetch its output variables with `GET /case/{caseId}/results`.
  </Step>
</Steps>

## Usage Notes

* **Asynchronous execution**: Execute Case returns immediately once the run is queued; the result arrives later via polling or your `callbackUrl`.
* **Terminal statuses**: `COMPLETED`, `FAILED`, `CANCELLED`, and `TIMED_OUT` — once one is returned, the status will not change again.
* **Versioning**: A case runs against the latest active version of the workflow unless you pin one with `workflowVersionId` or `workflowVersionNumber` at initiation.
* **Results before completion**: Fetching results for an unfinished case returns HTTP `202` with no results — wait for a terminal status first.

## Available Endpoints

<CardGroup cols={2}>
  <Card title="Initiate Case" icon="circle-play" href="/api-reference/v1-case/initiate-case">
    Create a case for a workflow and receive a caseId
  </Card>

  <Card title="Execute Case" icon="bolt" href="/api-reference/v1-case/execute-case">
    Run the case with populated inputs
  </Card>

  <Card title="Get Case Status" icon="spinner" href="/api-reference/v1-case/get-case-status">
    Poll the execution status of a case
  </Card>

  <Card title="Get Case Results" icon="inbox-in" href="/api-reference/v1-case/get-case-results">
    Retrieve the output variables of a finished case
  </Card>

  <Card title="Case Audit Log" icon="list-check" href="/api-reference/v1-case/case-audit-log">
    Inspect the per-node execution audit of a case
  </Card>
</CardGroup>