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

# Initiate Case

> Create a new case for a workflow and receive a caseId

This step creates a case for a workflow and returns the unique `caseId` required for execution and monitoring. A case is a single run of a workflow.

Identify the workflow with the `workflowId` returned by the [workflow endpoints](/api-reference/v1-workflow-generation/get-workflow-details). The case runs against the latest active version of the workflow unless you pin one with `workflowVersionId` or `workflowVersionNumber`.

<Warning>
  You must save the `caseId` returned by this endpoint for all subsequent steps.
</Warning>

## Headers

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

## Body Parameters

<ParamField body="workflowId" type="string" required>
  The workflow to run — the `workflowId` UUID returned by the workflow endpoints.
</ParamField>

<ParamField body="workflowVersionId" type="string">
  Pin the case to a specific workflow version by UUID. Omit to run the latest active version.
</ParamField>

<ParamField body="workflowVersionNumber" type="number">
  Pin the case to a specific workflow version by version number. Omit to run the latest active version.
</ParamField>

<ParamField body="title" type="string">
  Case title shown in the Opus UI
</ParamField>

<ParamField body="description" type="string">
  Case description shown in the Opus UI
</ParamField>

## Response

<ResponseField name="caseId" type="string" required>
  The unique identifier for this case. Use this ID in all subsequent API calls.
</ResponseField>

## Errors

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

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

<RequestExample>
  ```bash cURL theme={null}
  # Latest active version (minimal)
  curl --request POST \
    --url https://operator.opus.com/api/v1/case \
    --header 'Content-Type: application/json' \
    --header 'x-service-key: {YOUR_SERVICE_KEY}' \
    --data '{
      "workflowId": "{YOUR_WORKFLOW_ID}",
      "title": "Q4 Report Processing",
      "description": "Processing quarterly financial reports"
    }'

  # Pinned to a specific version number
  curl --request POST \
    --url https://operator.opus.com/api/v1/case \
    --header 'Content-Type: application/json' \
    --header 'x-service-key: {YOUR_SERVICE_KEY}' \
    --data '{
      "workflowId": "{YOUR_WORKFLOW_ID}",
      "workflowVersionNumber": 3,
      "title": "Q4 Report Processing"
    }'
  ```

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

  url = "https://operator.opus.com/api/v1/case"
  headers = {
      "Content-Type": "application/json",
      "x-service-key": "{YOUR_SERVICE_KEY}"
  }

  payload = {
      "workflowId": "{YOUR_WORKFLOW_ID}",
      # Pin a specific workflow version (omit both to use the latest active version):
      # "workflowVersionNumber": 3,
      # "workflowVersionId": "{WORKFLOW_VERSION_ID}",
      "title": "Q4 Report Processing",
      "description": "Processing quarterly financial reports"
  }

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

  ```javascript JavaScript theme={null}
  const response = await fetch("https://operator.opus.com/api/v1/case", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-service-key": "{YOUR_SERVICE_KEY}",
    },
    body: JSON.stringify({
      workflowId: "{YOUR_WORKFLOW_ID}",
      // Pin a specific workflow version (omit both to use the latest active version):
      // workflowVersionNumber: 3,
      // workflowVersionId: "{WORKFLOW_VERSION_ID}",
      title: "Q4 Report Processing",
      description: "Processing quarterly financial reports",
    }),
  });

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

<ResponseExample>
  ```json 201 Response theme={null}
  {
    "caseId": "{CASE_ID}"
  }
  ```
</ResponseExample>