Initiate Job

# 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}"
}

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

string

required

Your API authentication key

Body Parameters

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.

string

Workflow reference entity UUID. Required unless workflowId is provided. Takes precedence over workflowId if both are sent.

string

Pin the job to a specific workflow version by UUID. Omit to run the latest active version.

number

Pin the job to a specific workflow version by version number. Omit to run the latest active version.

string

Job title shown in the Opus UI

string

Job description shown in the Opus UI

string

The ID of the user who initiated the job. Useful for attributing API-triggered jobs back to a specific end user.

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.

string

Optional comma-separated workspace IDs used to validate workflow access. Used by machine-key callers that operate across multiple workspaces.

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.

string

The ID of the web app that initiated this job, when the job is launched from a published Opus web app.

Response

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"
  }'

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}"
}

⌘I

Get Started

Jobs

Workflow Generation

Headers

Body Parameters

Response

​Headers

​Body Parameters

​Response

Headers

Body Parameters

Response