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

> Create a new job instance and receive a jobExecutionId

This step creates a job instance in the system and returns the unique `jobExecutionId` required for execution and monitoring.

You can identify the workflow with either `workflowId` or `referenceEntityId` (a workflow reference entity UUID). If both are sent, `referenceEntityId` takes precedence. The job runs against the latest active version of the workflow unless you pin one with `workflowVersionId` or `workflowVersionNumber`.

<Warning>
  You must save the `jobExecutionId` 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">
  The ID of the workflow to be used for your job. Required unless `referenceEntityId` is provided. The platform resolves it to a workflow reference entity via lookup.
</ParamField>

<ParamField body="referenceEntityId" type="string">
  Workflow reference entity UUID. Required unless `workflowId` is provided. Takes precedence over `workflowId` if both are sent.
</ParamField>

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

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

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

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

<ParamField body="refUserId" type="string">
  The ID of the user who initiated the job. Useful for attributing API-triggered jobs back to a specific end user.
</ParamField>

<ParamField body="source" type="string" default="api">
  Where the job was triggered from. Defaults to `api` for service-key callers. Allowed values: `email-agent`, `chat-agent`, `scheduled`, `api`, `manual`, `agent`, `opus-ai`, `web-app`.
</ParamField>

<ParamField body="workspaces" type="string">
  Optional comma-separated workspace IDs used to validate workflow access. Used by machine-key callers that operate across multiple workspaces.
</ParamField>

<ParamField body="initialInput" type="object">
  Initial user-provided inputs to store on the job at creation time. Accepts arbitrary key/value pairs that match your workflow's input schema.
</ParamField>

<ParamField body="webAppId" type="string">
  The ID of the web app that initiated this job, when the job is launched from a published Opus web app.
</ParamField>

## Response

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

<RequestExample>
  ```bash cURL theme={null}
  # Latest active version (minimal)
  curl --request POST \
    --url https://operator.opus.com/job/initiate \
    --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",
      "source": "api",
      "initialInput": {
        "quarter": "Q4",
        "fiscalYear": 2025
      }
    }'

  # Pinned to a specific version number, with attribution + workspace scoping
  curl --request POST \
    --url https://operator.opus.com/job/initiate \
    --header 'Content-Type: application/json' \
    --header 'x-service-key: {YOUR_SERVICE_KEY}' \
    --data '{
      "workflowId": "{YOUR_WORKFLOW_ID}",
      "workflowVersionNumber": 3,
      "title": "Q4 Report Processing",
      "description": "Processing quarterly financial reports",
      "source": "api",
      "refUserId": "{END_USER_ID}",
      "workspaces": "{WORKSPACE_ID_1},{WORKSPACE_ID_2}",
      "initialInput": {
        "quarter": "Q4",
        "fiscalYear": 2025
      }
    }'

  # Pinned to a specific version UUID, identified by referenceEntityId instead of workflowId
  curl --request POST \
    --url https://operator.opus.com/job/initiate \
    --header 'Content-Type: application/json' \
    --header 'x-service-key: {YOUR_SERVICE_KEY}' \
    --data '{
      "referenceEntityId": "{REFERENCE_ENTITY_ID}",
      "workflowVersionId": "{WORKFLOW_VERSION_ID}",
      "title": "Q4 Report Processing",
      "source": "api"
    }'
  ```

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

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

  payload = {
      "workflowId": "{YOUR_WORKFLOW_ID}",
      # Or identify the workflow by its reference entity instead:
      # "referenceEntityId": "{REFERENCE_ENTITY_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",
      "source": "api",
      "refUserId": "{END_USER_ID}",
      "workspaces": "{WORKSPACE_ID_1},{WORKSPACE_ID_2}",
      "initialInput": {
          "quarter": "Q4",
          "fiscalYear": 2025
      }
  }

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

  ```javascript JavaScript theme={null}
  const response = await fetch("https://operator.opus.com/job/initiate", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-service-key": "{YOUR_SERVICE_KEY}",
    },
    body: JSON.stringify({
      workflowId: "{YOUR_WORKFLOW_ID}",
      // Or identify the workflow by its reference entity instead:
      // referenceEntityId: "{REFERENCE_ENTITY_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",
      source: "api",
      refUserId: "{END_USER_ID}",
      workspaces: "{WORKSPACE_ID_1},{WORKSPACE_ID_2}",
      initialInput: {
        quarter: "Q4",
        fiscalYear: 2025,
      },
    }),
  });

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

<ResponseExample>
  ```json 201 Response theme={null}
  {
    "jobExecutionId": "{JOB_EXECUTION_ID}"
  }
  ```
</ResponseExample>