Skip to main content

​
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:

​
Authentication

All Case API endpoints require authentication with your Opus API key, sent in the x-service-key header.
A request with a missing, invalid, or expired key returns 401.
Your API key is a unique, secret credential. Store it securely and never expose it in client-side code.

​
Case Flow

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

Get the Input Schema

Fetch the workflow’s input schema with Get Workflow Details so you know which inputs the case expects.
2

Initiate the Case

Create a case for the workflow using POST /case and save the returned caseId — every subsequent call requires it.
3

Upload Files (if needed)

If the workflow has file or array_files inputs, upload each file first via the File API and reference the returned fileUrl in your payload.
4

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

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 for a per-node view.
6

Get the Results

Once the case completes, fetch its output variables with GET /case/{caseId}/results.

​
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

Initiate Case

Create a case for a workflow and receive a caseId

Execute Case

Run the case with populated inputs

Get Case Status

Poll the execution status of a case

Get Case Results

Retrieve the output variables of a finished case

Case Audit Log

Inspect the per-node execution audit of a case