Skip to main content
POST
/
job
/
initiate
# 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"
  }'

{
  "jobExecutionId": "{JOB_EXECUTION_ID}"
}
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.
You must save the jobExecutionId returned by this endpoint for all subsequent steps.

​
Headers

​
x-service-key
string
required
Your API authentication key

​
Body Parameters

​
workflowId
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.
​
referenceEntityId
string
Workflow reference entity UUID. Required unless workflowId is provided. Takes precedence over workflowId if both are sent.
​
workflowVersionId
string
Pin the job to a specific workflow version by UUID. Omit to run the latest active version.
​
workflowVersionNumber
number
Pin the job to a specific workflow version by version number. Omit to run the latest active version.
​
title
string
Job title shown in the Opus UI
​
description
string
Job description shown in the Opus UI
​
refUserId
string
The ID of the user who initiated the job. Useful for attributing API-triggered jobs back to a specific end user.
​
source
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.
​
workspaces
string
Optional comma-separated workspace IDs used to validate workflow access. Used by machine-key callers that operate across multiple workspaces.
​
initialInput
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.
​
webAppId
string
The ID of the web app that initiated this job, when the job is launched from a published Opus web app.

​
Response

​
jobExecutionId
string
required
The unique identifier for this job execution. Use this ID in all subsequent API calls.
# 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"
  }'

{
  "jobExecutionId": "{JOB_EXECUTION_ID}"
}