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

# Execute Case

> Run a case with populated inputs

This is the primary step where you provide all inputs and run the workflow.

<Note>
  Case execution is asynchronous. This endpoint returns immediately once the run is queued; the final result is delivered to your `callbackUrl` (and is also retrievable via [Get Case Results](/api-reference/v1-case/get-case-results)).
</Note>

The request body consists of:

* The `payload` — the input schema from [Get Workflow Details](/api-reference/v1-workflow-generation/get-workflow-details) with values populated for each input
* An optional `callbackUrl` that Opus will POST to when the case finishes

## Path Parameters

<ParamField path="caseId" type="string" required>
  The case ID returned by [Initiate Case](/api-reference/v1-case/initiate-case)
</ParamField>

## Headers

<ParamField header="x-service-key" type="string" required>
  Your API authentication key
</ParamField>

## Body Parameters

<ParamField body="payload" type="object" required>
  An object where each key is a variable name from your workflow's input schema, and each value is a Variable Object (see below).
</ParamField>

<ParamField body="callbackUrl" type="string">
  HTTPS URL that Opus will POST the case result to once the run finishes. Must be reachable from the Opus platform.
</ParamField>

### Variable Object

Each entry in `payload` uses your variable name as the key (e.g., `VARIABLE_NAME_1`) and maps to an object with the following properties:

<ParamField body="value" type="any" required>
  The value for this input (type depends on field type)
</ParamField>

<ParamField body="type" type="string" required>
  The data type: str, float, bool, date, file, array, array\_files, or object
</ParamField>

<ParamField body="typeDefinition" type="object">
  Type definition of the variable, as provided by the workflow's input schema.
</ParamField>

<ParamField body="displayName" type="string">
  The variable name displayed in the Opus platform UI
</ParamField>

<Warning>
  While `displayName` is optional, omitting it may cause display glitches on the Opus platform UI. We strongly recommend including it for each input field.
</Warning>

## Response

<ResponseField name="success" type="boolean" required>
  Whether the case execution was successfully started
</ResponseField>

<ResponseField name="caseId" type="string" required>
  The case ID
</ResponseField>

<ResponseField name="message" type="string" required>
  Status message
</ResponseField>

<ResponseField name="error" type="object">
  Error payload if the case could not be started
</ResponseField>

## Errors

<ResponseField name="401" type="Unauthorized">
  Missing, invalid, or expired API key.
</ResponseField>

<ResponseField name="404" type="Not Found">
  The case does not exist.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://operator.opus.com/api/v1/case/{YOUR_CASE_ID}/execute \
    --header 'Content-Type: application/json' \
    --header 'x-service-key: {YOUR_SERVICE_KEY}' \
    --data '{
      "callbackUrl": "https://your-app.example.com/opus/callback",
      "payload": {
        "{VARIABLE_NAME_1}": {
          "value": "API Test Project",
          "type": "str",
          "displayName": "Variable Name 1"
        },
        "{VARIABLE_NAME_2}": {
          "value": 45.8,
          "type": "float",
          "displayName": "Variable Name 2"
        }
      }
    }'
  ```

  ```python Python theme={null}
  import requests

  case_id = "{YOUR_CASE_ID}"
  url = f"https://operator.opus.com/api/v1/case/{case_id}/execute"
  headers = {
      "Content-Type": "application/json",
      "x-service-key": "{YOUR_SERVICE_KEY}"
  }
  payload = {
      "callbackUrl": "https://your-app.example.com/opus/callback",
      "payload": {
          "{VARIABLE_NAME_1}": {
              "value": "API Test Project",
              "type": "str",
              "displayName": "Variable Name 1"
          },
          "{VARIABLE_NAME_2}": {
              "value": 45.8,
              "type": "float",
              "displayName": "Variable Name 2"
          }
      }
  }

  response = requests.post(url, json=payload, headers=headers)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const caseId = "{YOUR_CASE_ID}";
  const response = await fetch(`https://operator.opus.com/api/v1/case/${caseId}/execute`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-service-key": "{YOUR_SERVICE_KEY}",
    },
    body: JSON.stringify({
      callbackUrl: "https://your-app.example.com/opus/callback",
      payload: {
        "{VARIABLE_NAME_1}": {
          value: "API Test Project",
          type: "str",
          displayName: "Variable Name 1",
        },
        "{VARIABLE_NAME_2}": {
          value: 45.8,
          type: "float",
          displayName: "Variable Name 2",
        },
      },
    }),
  });

  const data = await response.json();
  console.log(data);
  ```
</RequestExample>

<ResponseExample>
  ```json 201 Response theme={null}
  {
    "success": true,
    "caseId": "{CASE_ID}",
    "message": "Job execution started"
  }
  ```
</ResponseExample>