# 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"
}'
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())
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);
{
"jobExecutionId": "{JOB_EXECUTION_ID}"
}
Deprecated
Initiate Job
Create a new job instance and receive a jobExecutionId
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"
}'
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())
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);
{
"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
Body Parameters
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.Workflow reference entity UUID. Required unless
workflowId is provided. Takes precedence over workflowId if both are sent.Pin the job to a specific workflow version by version number. Omit to run the latest active version.
The ID of the user who initiated the job. Useful for attributing API-triggered jobs back to a specific end user.
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.Optional comma-separated workspace IDs used to validate workflow access. Used by machine-key callers that operate across multiple workspaces.
Initial user-provided inputs to store on the job at creation time. Accepts arbitrary key/value pairs that match your workflow’s input schema.
The ID of the web app that initiated this job, when the job is launched from a published Opus web app.
Response
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"
}'
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())
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);
{
"jobExecutionId": "{JOB_EXECUTION_ID}"
}
Was this page helpful?